对话补全

POST /v1/chat/completions

对话补全是最核心的接口，支持：

• 多轮对话
• 流式输出（SSE）
• 图片理解（多模态消息）
• 函数/工具调用（Function Calling）
• 强制 JSON 输出

请求参数

必填参数

参数	类型	说明
model	string	模型 ID，可从 /v1/models 获取
messages	array	消息数组，见下方说明

常用可选参数

参数	类型	默认值	说明
stream	boolean	false	是否以 SSE 流式返回
stream_options	object	—	流式选项，如 {"include_usage": true} 在最后一块返回用量
temperature	number	1	采样温度 0–2，越大越随机
top_p	number	1	核采样阈值，建议与 temperature 二选一调节
max_tokens	integer	—	回复的最大 token 数
stop	string / array	—	停止序列，最多 4 个
tools	array	—	工具/函数定义列表
tool_choice	string / object	—	工具选择策略（auto / none / 指定工具）
response_format	object	—	如 {"type": "json_object"} 强制 JSON 输出

messages 格式

每条消息为一个对象，role 取以下值：

role	说明
system	系统提示词，设定助手角色与行为规范
user	用户消息
assistant	助手历史回复（多轮对话时提供）
tool	工具调用返回结果

content 可以是字符串，也可以是多模态内容数组（文本 + 图片）。

基础示例

curl https://api.idreame.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "你是一个专业的代码助手。"},
      {"role": "user",   "content": "用 Python 写一个快速排序。"}
    ],
    "temperature": 0.7
  }'

响应示例

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1752600000,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "def quick_sort(arr):\n    if len(arr) <= 1:\n        return arr\n    ..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 120,
    "total_tokens": 148
  }
}

流式输出

设置 "stream": true 后响应以 Server-Sent Events 返回，每行以 data: 开头，增量内容在 choices[0].delta.content，以 data: [DONE] 结束：

curl https://api.idreame.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

data: {"id":"chatcmpl-abc","choices":[{"delta":{"role":"assistant"},"index":0}]}

data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"你"},"index":0}]}

data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"好！"},"index":0}]}

data: {"id":"chatcmpl-abc","choices":[{"delta":{},"finish_reason":"stop","index":0}]}

data: [DONE]

Python 流式处理示例：

from openai import OpenAI

client = OpenAI(
    base_url="https://api.idreame.com/v1",
    api_key="sk-xxxxxxxx",
)

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "用 100 字介绍量子计算"}],
    stream=True,
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

图片理解（多模态）

支持图片理解的模型（如 gpt-4o、claude-sonnet-5）可在 content 中传入图片：

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text",      "text": "这张图片里有什么？"},
        {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
      ]
    }
  ]
}

也支持传入 base64 编码的图片：

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/jpeg;base64,/9j/4AAQSkZJRgAB..."
  }
}

函数调用（Tool Calling）

{
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "北京现在几点？"}],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_current_time",
        "description": "获取指定城市的当前时间",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "城市名称"}
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

JSON 强制输出

{
  "model": "gpt-4o",
  "messages": [
    {"role": "system", "content": "你必须以 JSON 格式输出。"},
    {"role": "user",   "content": "给我一个包含 name 和 age 字段的用户信息示例。"}
  ],
  "response_format": {"type": "json_object"}
}

WARNING

使用 response_format: json_object 时，system prompt 中必须明确提及 JSON，否则部分模型可能报错。