完整请求案例

/v1/chat/completions 接口详解

本文完整拆解 /v1/chat/completions 接口的请求参数和返回结果，帮助你快速上手 AIone 的 OpenAI Compatible 接口。

如果你要使用 Gemini 图片生成模型，以及 aspect_ratio、image_size、top_k 这类图片相关参数，请同时查看《Gemini 图片生成》。

一、请求参数详解

必填参数

model（必填）

要使用的模型 ID。完整列表请查看 模型与定价。

"model": "claude-sonnet-4-6"

messages（必填）

对话消息数组，每条消息包含 role 和 content：

"messages": [
  {"role": "system", "content": "你是一个专业的技术顾问"},
  {"role": "user", "content": "请解释什么是 API Gateway"}
]

role 取值：

• system：系统提示词，设定 AI 的行为和角色
• user：用户消息
• assistant：AI 的回复（用于多轮对话）

可选参数

temperature（默认 1.0）

控制输出的随机性，范围 0-2：

• 0：确定性输出，适合代码生成、数据提取
• 0.7：平衡创造性和一致性，推荐日常使用
• 1.5+：高创造性，适合创意写作

max_tokens

最大生成 token 数。不设置则使用模型默认值。

stream（默认 false）

是否启用流式响应。设为 true 后返回 SSE 格式数据流。

强烈建议在交互场景中启用 stream: true，可将首字等待时间从 10 秒以上降低至 2-3 秒。非流式请求需要等待模型生成全部内容后才返回，大模型生成较长内容时容易超时。

top_p（默认 1.0）

核采样参数。通常只需调整 temperature 或 top_p 其中一个。

tools

Function calling 工具定义，让模型调用外部函数：

"tools": [
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "获取指定城市的天气",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {"type": "string", "description": "城市名"}
        },
        "required": ["city"]
      }
    }
  }
]

response_format

指定响应格式，支持 JSON mode：

"response_format": {"type": "json_object"}

二、完整请求示例（流式，推荐）

{
  "model": "claude-sonnet-4-6",
  "messages": [
    {"role": "system", "content": "你是一个有帮助的助手，请用简洁的中文回答。"},
    {"role": "user", "content": "什么是 RESTful API？请用3句话解释。"}
  ],
  "max_tokens": 500,
  "temperature": 0.7,
  "stream": true
}

三、流式返回格式

启用 stream: true 后，返回 SSE（Server-Sent Events）格式。每个 chunk 是一个 JSON 对象：

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"content":"REST"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"content":"ful"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

关键字段：

• choices[0].delta.content：本次增量输出的文本片段
• choices[0].finish_reason：为 null 表示未结束，stop 表示正常结束，length 表示达到 max_tokens

四、非流式返回格式

{
  "id": "chatcmpl-abc123def456",
  "object": "chat.completion",
  "created": 1711500000,
  "model": "claude-sonnet-4-6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "RESTful API 是一种基于 HTTP 协议的接口设计风格..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 85,
    "total_tokens": 127
  }
}

关键字段说明：

五、注意事项

1. 推荐流式模式：交互场景（聊天、IDE 编程）请始终使用 stream: true，体验和稳定性显著优于非流式
2. 权限与密钥：确保 API Key 有效且有权访问所选模型
3. 参数格式：messages 是数组格式，每条消息必须包含 role 和 content
4. token 计费：input + output token 分别计费，价格不同
5. 兼容性：AIone 完全兼容 OpenAI SDK，可直接使用 openai 库
6. 错误处理：建议对 429（限频）和 5xx（服务端错误）使用指数退避重试