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

# 文本对话

> 使用 `/chat/completions` 发起文本对话请求，了解字段、示例和常见报错。

## 接口用途与路由

`/chat/completions` 用于发起文本对话请求，适合单轮问答、多轮上下文续写、摘要、改写和通用指令式生成。

基础地址固定为：

```text theme={null}
https://niuapi.vip/v1
```

完整路由为：

```text theme={null}
POST https://niuapi.vip/v1/chat/completions
```

请求头至少应包含：

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

## 请求体字段

下面是最常用的请求字段：

<AccordionGroup>
  <Accordion icon="box" title="model">
    要调用的模型名称。它必须是当前可用且填写正确的值。
  </Accordion>

  <Accordion icon="messages" title="messages">
    对话消息数组，也是这个接口最核心的字段。每条消息通常包含 `role` 和 `content`。
  </Accordion>

  <Accordion icon="sliders" title="temperature">
    可选。用于控制输出的发散程度。数值越高，结果通常越灵活；数值越低，结果通常越稳定。
  </Accordion>

  <Accordion icon="arrow-down-1-9" title="max_tokens">
    可选。用于限制本次生成的最大输出 token 数。
  </Accordion>

  <Accordion icon="waves" title="stream">
    可选。设为 `true` 时，响应会按流式分块返回；未设置或为 `false` 时，返回完整 JSON 结果。
  </Accordion>
</AccordionGroup>

## `messages` 结构

`messages` 是一个按顺序排列的数组。常见角色如下：

* `system`：定义助手行为、语气或回答边界
* `user`：用户输入的问题或指令
* `assistant`：历史回答内容，用于继续多轮对话

一个最小结构示例：

```json theme={null}
[
  {
    "role": "user",
    "content": "请用一句话介绍智牛API。"
  }
]
```

## 多轮对话示例

如果你要继续上下文，就把历史消息按顺序一起传入：

```json theme={null}
{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "system",
      "content": "你是一个简洁、专业的技术助手。"
    },
    {
      "role": "user",
      "content": "请解释什么是文本对话接口。"
    },
    {
      "role": "assistant",
      "content": "文本对话接口用于向模型发送消息数组，并获取生成结果。"
    },
    {
      "role": "user",
      "content": "那你再补一句它适合什么场景。"
    }
  ]
}
```

## 标准请求示例

```bash theme={null}
curl https://niuapi.vip/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "system",
        "content": "你是一个简洁的中文助手。"
      },
      {
        "role": "user",
        "content": "请用三句话介绍智牛API 的文本对话能力。"
      }
    ],
    "temperature": 0.7
  }'
```

## 标准响应示例

非流式请求通常会返回完整 JSON，结构类似下面这样：

```json theme={null}
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "智牛API 提供兼容 OpenAI 的文本对话接入方式。你可以使用熟悉的 SDK 和消息结构快速集成。它适合问答、摘要、改写等常见文本生成场景。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 41,
    "total_tokens": 73
  }
}
```

你通常只需要优先关注：

* `choices[0].message.content`：模型输出内容
* `finish_reason`：生成结束原因
* `usage`：token 消耗统计

## 流式返回说明

如果请求中显式传入 `"stream": true`，可以按流式方式接收增量结果。此时服务端会持续推送分块内容，客户端应按 SSE 风格逐段读取，而不是等待单个完整 JSON 一次性返回。

一个流式请求示例：

```bash theme={null}
curl https://niuapi.vip/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "请流式输出一句欢迎语。"
      }
    ],
    "stream": true
  }'
```

流式分块内容通常会是类似下面的形式：

```text theme={null}
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","choices":[{"delta":{"content":"欢迎"},"index":0}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","choices":[{"delta":{"content":"使用智牛API"},"index":0}]}

data: [DONE]
```

<Note>
  如果你使用的是官方 OpenAI SDK，是否以及如何消费流式结果，还取决于客户端代码写法。文档这里重点说明 `stream` 参数和分块返回方式本身。
</Note>

## 常见错误与排查

<AccordionGroup>
  <Accordion icon="key" title="401 Unauthorized：认证失败">
    先检查 `Authorization: Bearer YOUR_API_KEY` 是否完整，再确认 Key 本身是否有效。
  </Accordion>

  <Accordion icon="circle-exclamation" title="400 Bad Request：请求体不合法">
    常见原因包括 `messages` 不是数组、缺少 `model`、字段类型错误，或 JSON 格式本身不合法。
  </Accordion>

  <Accordion icon="box-open" title="模型不可用或模型名错误">
    如果返回模型不存在或不可用，请先确认 `model` 是否填写为当前支持的有效名称。
  </Accordion>

  <Accordion icon="link-slash" title="调用地址错误">
    Base URL 必须是 `https://niuapi.vip/v1`。如果漏掉 `/v1`，或把 SDK Base URL 写成完整接口路径，都会导致请求异常。
  </Accordion>

  <Accordion icon="waves" title="流式读取没有结果或提前中断">
    请确认你已传入 `stream: true`，并且客户端确实按流式方式读取响应；如果按普通 JSON 解析，通常会表现为读取失败或结果不完整。
  </Accordion>
</AccordionGroup>

<Tip>
  排查问题时，优先检查四件事：URL、`Authorization`、模型名、`messages` 结构。大多数接入问题都出在这里。
</Tip>