> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viviai.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Chat

> 通过 Chat Completions 协议调用模型，支持多轮消息和流式输出。

## 请求地址

```http theme={null}
POST https://api.viviai.cc/v1/chat/completions
```

使用 OpenAI SDK 时，将 `base_url` 设置为 `https://api.viviai.cc/v1`，SDK 会追加 `/chat/completions`。

## 鉴权

```http theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

`YOUR_API_KEY` 是 ViVi-API 的密钥。示例中的 `YOUR_OPENAI_MODEL` 是模型占位符，请替换为账号可用、支持 Chat Completions 的完整模型 ID。

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | 是 | 完整模型 ID。 |
| `messages` | array | 是 | 按对话顺序排列的消息。 |
| `messages[].role` | string | 是 | 常用 `user`、`assistant`；系统指令角色视模型而定。 |
| `messages[].content` | string / array | 是\* | 文本或模型支持的内容块；本文示例使用字符串。 |
| `stream` | boolean | 否 | 设置为 `true` 时返回 SSE 事件流。 |
| `max_completion_tokens` | integer | 否 | 生成 token 上限；推理模型可能同时计入推理 token。 |
| `temperature` | number | 否 | 控制采样随机性；是否可设置及范围由模型决定。 |
| `top_p` | number | 否 | 核采样参数；通常不与 temperature 同时调整。 |

\*仅含工具调用的 assistant 消息可以采用不同结构。工具调用、多模态、推理与结构化输出需由具体模型和接入渠道支持。部分旧模型使用 `max_tokens`，请按模型要求选择，不要同时发送两个长度参数。

## 调用示例

先设置 `VIVI_API_KEY`；环境变量设置方法见[快速开始](https://docs.viviai.cc/quickstart.md)。cURL 使用 Bash 语法。

```bash cURL theme={null}
curl --fail-with-body https://api.viviai.cc/v1/chat/completions \
  -H "Authorization: Bearer $VIVI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_OPENAI_MODEL",
    "messages": [
      {"role": "user", "content": "请用三句话介绍 API。"}
    ],
    "stream": false
  }'
```

```python Python SDK theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["VIVI_API_KEY"],
    base_url="https://api.viviai.cc/v1",
    timeout=120.0,
    max_retries=0,
)

response = client.chat.completions.create(
    model="YOUR_OPENAI_MODEL",
    messages=[{"role": "user", "content": "请用三句话介绍 API。"}],
)
print(response.choices[0].message.content)
```

Python SDK 安装命令：`python -m pip install openai`。示例关闭 SDK 自动重试，便于首次接入时定位错误。

## 返回结果

以下为结构示意，文本和用量是示例值。

```json theme={null}
{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "model": "YOUR_OPENAI_MODEL",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "API 是应用之间通信的接口。"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 20, "completion_tokens": 15, "total_tokens": 35}
}
```

* 文本：`choices[0].message.content`。
* 结束原因：`choices[0].finish_reason`。`stop` 通常表示正常结束，`length` 表示达到长度限制。
* 用量：`usage`。具体字段和计费规则以实际响应与控制台为准。

## 多轮对话

将必要的历史消息一并发送。接口不会仅凭 API Key 自动记住上一轮对话。

```json theme={null}
{
  "model": "YOUR_OPENAI_MODEL",
  "messages": [
    {"role": "user", "content": "我正在学习 Python。"},
    {"role": "assistant", "content": "你想先学习哪部分？"},
    {"role": "user", "content": "请介绍列表。"}
  ]
}
```

## 流式输出

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["VIVI_API_KEY"],
    base_url="https://api.viviai.cc/v1",
    timeout=120.0,
    max_retries=0,
)

stream = client.chat.completions.create(
    model="YOUR_OPENAI_MODEL",
    messages=[{"role": "user", "content": "写一段简短的欢迎语。"}],
    stream=True,
)
try:
    for chunk in stream:
        if chunk.choices:
            text = chunk.choices[0].delta.content
            if text:
                print(text, end="", flush=True)
finally:
    stream.close()
print()
```

直接处理 HTTP 时，从 SSE 的 `data:` 事件解析 JSON，增量文本位于 `choices[0].delta.content`。部分事件只包含角色或结束原因，不能假设每个事件都有文本；常见结束标记为 `data: [DONE]`。

## 接入提示

* Base URL 中只保留一份 `/v1`。
* 文本模型、图像模型与其他专用模型不一定支持该端点。
* 参数不兼容时，先使用仅包含 `model` 和 `messages` 的最小请求排查。
* 鉴权、权限、限流与超时排查见[快速开始](https://docs.viviai.cc/quickstart.md#常见问题)。

协议参考：[OpenAI Chat Completions](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)。ViVi-API 的模型范围与可选功能以实际服务为准。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.