文本对话

接口用途与路由

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

https://niuapi.vip/v1

完整路由为：

POST https://niuapi.vip/v1/chat/completions

请求头至少应包含：

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

请求体字段

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

model

要调用的模型名称。它必须是当前可用且填写正确的值。

messages

对话消息数组，也是这个接口最核心的字段。每条消息通常包含 role 和 content。

temperature

可选。用于控制输出的发散程度。数值越高，结果通常越灵活；数值越低，结果通常越稳定。

max_tokens

可选。用于限制本次生成的最大输出 token 数。

stream

可选。设为 true 时，响应会按流式分块返回；未设置或为 false 时，返回完整 JSON 结果。

`messages` 结构

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

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

一个最小结构示例：

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

多轮对话示例

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

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

标准请求示例

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，结构类似下面这样：

{
  "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 一次性返回。一个流式请求示例：

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
  }'

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

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]

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

常见错误与排查

401 Unauthorized：认证失败

先检查 Authorization: Bearer YOUR_API_KEY 是否完整，再确认 Key 本身是否有效。

400 Bad Request：请求体不合法

常见原因包括 messages 不是数组、缺少 model、字段类型错误，或 JSON 格式本身不合法。

模型不可用或模型名错误

如果返回模型不存在或不可用，请先确认 model 是否填写为当前支持的有效名称。

调用地址错误

Base URL 必须是 https://niuapi.vip/v1。如果漏掉 /v1，或把 SDK Base URL 写成完整接口路径，都会导致请求异常。

流式读取没有结果或提前中断

请确认你已传入 stream: true，并且客户端确实按流式方式读取响应；如果按普通 JSON 解析，通常会表现为读取失败或结果不完整。

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

开始使用

模型分组介绍

快速使用

API 参考

接口用途与路由

请求体字段

`messages` 结构

多轮对话示例

标准请求示例

标准响应示例

流式返回说明

常见错误与排查

​接口用途与路由

​请求体字段

​messages 结构

​多轮对话示例

​标准请求示例

​标准响应示例

​流式返回说明

​常见错误与排查

接口用途与路由

请求体字段

`messages` 结构

多轮对话示例

标准请求示例

标准响应示例

流式返回说明

常见错误与排查