Skip to main content

​
接口用途与路由

/chat/completions 用于发起文本对话请求，适合单轮问答、多轮上下文续写、摘要、改写和通用指令式生成。 基础地址固定为： 
https://niuapi.vip/v1
完整路由为： 
POST https://niuapi.vip/v1/chat/completions
请求头至少应包含： 
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

​
请求体字段

下面是最常用的请求字段：
要调用的模型名称。它必须是当前可用且填写正确的值。
对话消息数组，也是这个接口最核心的字段。每条消息通常包含 role 和 content。
可选。用于控制输出的发散程度。数值越高，结果通常越灵活；数值越低，结果通常越稳定。
可选。用于限制本次生成的最大输出 token 数。
可选。设为 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 参数和分块返回方式本身。

​
常见错误与排查

先检查 Authorization: Bearer YOUR_API_KEY 是否完整，再确认 Key 本身是否有效。
常见原因包括 messages 不是数组、缺少 model、字段类型错误，或 JSON 格式本身不合法。
如果返回模型不存在或不可用，请先确认 model 是否填写为当前支持的有效名称。
Base URL 必须是 https://niuapi.vip/v1。如果漏掉 /v1，或把 SDK Base URL 写成完整接口路径，都会导致请求异常。
请确认你已传入 stream: true，并且客户端确实按流式方式读取响应；如果按普通 JSON 解析，通常会表现为读取失败或结果不完整。
排查问题时，优先检查四件事：URL、Authorization、模型名、messages 结构。大多数接入问题都出在这里。