OpenAI Chat Completions API · Schema 完整参考

概览

1. 端点与认证

POST https://api.openai.com/v1/chat/completions
Authorization: Bearer <OPENAI_API_KEY>
Content-Type: application/json

2. 请求对象 ChatCompletionRequest

除 model 和 messages 外全部字段可选——这是 OpenAI 协议"宽松 schema"的典型形态。

type ChatCompletionRequest = {
  // —— 必填 ——
  model: string,                          // 模型 ID（"gpt-4o" / "gpt-5" / "deepseek-chat" ...）
  messages: MessageParam[],               // 对话历史（无状态全量回放）

  // —— 采样控制 ——
  temperature?: number,                   // 默认 1.0；推理模型忽略
  top_p?: number,                         // 默认 1.0（与 temperature 二选一）
  n?: number,                             // 生成几条候选，默认 1
  seed?: number,                          // 尽力而为的确定性
  stop?: string | string[],               // 最多 4 个停止序列

  // —— 长度控制 ——
  max_completion_tokens?: number,         // 新字段（推理模型时代）
  max_tokens?: number,                    // ⚠ deprecated，但兼容端点普遍只认它

  // —— 工具 ——
  tools?: ToolDefinition[],
  tool_choice?: "none" | "auto" | "required"
              | { type: "function", function: { name: string } },
  parallel_tool_calls?: boolean,          // 默认 true

  // —— 结构化输出 ——
  response_format?: { type: "text" }
                  | { type: "json_object" }
                  | { type: "json_schema", json_schema: {
                        name: string, schema: object, strict?: boolean } },

  // —— 流式 ——
  stream?: boolean,
  stream_options?: { include_usage?: boolean },

  // —— 惩罚与采样微调 ——
  presence_penalty?: number,              // -2.0 ~ 2.0
  frequency_penalty?: number,
  logit_bias?: Record<string, number>,
  logprobs?: boolean,
  top_logprobs?: number,

  // —— 元信息 ——
  user?: string,                          // 终端用户标识（OpenAI 滥用检测用）
  store?: boolean,                        // 是否存储请求/响应（用于 eval）
  metadata?: object,                      // 自定义键值对，16 个 key 限制
  service_tier?: "auto" | "default" | "flex",
  reasoning_effort?: "low" | "medium" | "high"   // 推理模型专属（o1/o3 系列）
}

3. 消息类型 MessageParam

5 种 role 各自有独立的字段约束——这是 Chat Completions 协议"扁平 message + role 判别"的典型形态。

type MessageParam =
  // 系统指令（developer 是 2025 年新增的更细粒度角色）
  | { role: "system" | "developer",
      content: string | TextPart[] }

  // 用户输入（content 支持 string 或多模态部件数组）
  | { role: "user",
      content: string | (TextPart | ImageUrlPart | AudioPart)[] }

  // 模型回复（回放历史时用；tool_calls 是可选字段挂在同一层）
  | { role: "assistant",
      content?: string | null,            // 发起工具调用时可为 null！
      tool_calls?: ToolCall[],
      refusal?: string | null }

  // 工具结果（独立 role；tool_call_id 与 ToolCall.id 严格配对）
  | { role: "tool",
      content: string | TextPart[],
      tool_call_id: string }

4. 工具定义 ToolDefinition

type ToolDefinition = {
  type: "function",                      // 固定为 "function"（预留非 function 扩展位）
  function: {
    name: string,                        // ^[a-zA-Z0-9_-]{1,64}（最多 64 字符）
    description?: string,                // 工具描述（模型看这段决定调不调）
    parameters?: JSONSchema,             // 标准 JSON Schema 对象
    strict?: boolean                     // true = 强约束模式（参数 100% 遵循 schema）
  }
}

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "查指定城市的当前天气。返回温度、天气状况、湿度。",
    "strict": true,
    "parameters": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "城市名，如 '北京' / '上海'"
        },
        "unit": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"],
          "description": "温度单位"
        }
      },
      "required": ["city"],
      "additionalProperties": false
    }
  }
}

5. 响应对象 ChatCompletion

type ChatCompletion = {
  id: string,                            // "chatcmpl-..."，每次请求唯一
  object: "chat.completion",
  created: number,                       // unix 秒
  model: string,                         // 实际使用的快照版（与请求可能不同）
  choices: [{
    index: number,                       // n>1 时区分候选
    message: {
      role: "assistant",
      content: string | null,            // 工具调用时可为 null
      tool_calls?: ToolCall[],
      refusal?: string | null,
      annotations?: Annotation[]
    },
    finish_reason: "stop" | "length" | "tool_calls"
                 | "content_filter" | "function_call",   // 末项 legacy
    logprobs?: object
  }],
  usage: {
    prompt_tokens: number,
    completion_tokens: number,
    total_tokens: number,
    prompt_tokens_details?: { cached_tokens?: number, audio_tokens?: number },
    completion_tokens_details?: { reasoning_tokens?: number }
  },
  system_fingerprint?: string            // 后端运行时指纹（用于追踪模型版本）
}

type ToolCall = {
  id: string,                            // "call_..."，回填配对用
  type: "function",
  function: {
    name: string,
    arguments: string                    // ⚠ JSON 字符串，不是对象！需 json.loads + 防御
  }
}

6. 流式 chunk ChatCompletionChunk

请求加 "stream": true 时，服务端返回 SSE 流。增量在 delta 而非 message。

type ChatCompletionChunk = {
  id: string,                            // 与非流式响应同一 id
  object: "chat.completion.chunk",        // 与非流式响应 object 不同！
  created: number,
  model: string,
  choices: [{
    index: number,
    delta: {                             // 增量在 delta（与 message 平级对应）
      role?: "assistant",                // 首个 chunk 携带
      content?: string | null,           // 文本分片
      tool_calls?: [{                    // 工具调用分片
        index: number,                   // ★ 聚合键：按 index 拼 name/arguments
        id?: string,                     // 仅首个分片携带
        type?: "function",
        function?: { name?: string, arguments?: string }
      }],
      refusal?: string | null
    },
    finish_reason?: string | null        // 仅最后一个 chunk 携带
  }]
}
// 终止哨兵：data: [DONE]（SSE 流的最后一条）

1. delta.content：每个 chunk 的 content 顺序拼接 = 完整文本
2. delta.tool_calls：必须按 index 聚合——同一个 tool_call 可能分多个 chunk 到达；先拼 name，再拼 arguments
3. arguments 是 JSON 字符串，拼接完整后再一次性 json.loads，中途解析必然失败
4. [DONE] 是终止哨兵，收到即关闭连接，不解析它
5. finish_reason 出现在最后一个 chunk的 delta 旁——不是单独的字段
6. 想拿 usage：请求加 stream_options: {include_usage: true}，最后一个 chunk 会有 usage 字段（choices 为空数组）

7. 完整往返示例（工具调用最小环）

4 段 JSON 展示从"用户提问"到"模型完成工具调用"的全过程。

{
  "model": "gpt-4o",
  "messages": [
    {"role": "user", "content": "跑一下测试"}
  ],
  "tools": [{
    "type": "function",
    "function": {
      "name": "run_tests",
      "parameters": {
        "type": "object",
        "properties": {"suite": {"type": "string"}},
        "required": ["suite"]
      }
    }
  }]
}

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1725273600,
  "model": "gpt-4o-2024-08-06",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc",
        "type": "function",
        "function": {
          "name": "run_tests",
          "arguments": "{\"suite\":\"all\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }],
  "usage": {
    "prompt_tokens": 88,
    "completion_tokens": 12,
    "total_tokens": 100
  }
}

{
  "model": "gpt-4o",
  "messages": [
    {"role": "user", "content": "跑一下测试"},
    {"role": "assistant", "content": null, "tool_calls": [
      {"id": "call_abc", "type": "function",
       "function": {"name": "run_tests", "arguments": "{\"suite\":\"all\"}"}}
    ]},
    {"role": "tool", "tool_call_id": "call_abc", "content": "42 passed"}
  ],
  "tools": [
    {"type": "function", "function": {
      "name": "run_tests",
      "parameters": {"type": "object",
        "properties": {"suite": {"type": "string"}},
        "required": ["suite"]}
    }}
  ]
}

{
  "id": "chatcmpl-def456",
  "object": "chat.completion",
  "created": 1725273610,
  "model": "gpt-4o-2024-08-06",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "测试全部通过。"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 142,
    "completion_tokens": 8,
    "total_tokens": 150
  }
}

8. 错误码与异常

两层错误：HTTP 层（传输）+ finish_reason 层（协议）。两层正交，必须分别处理。

9. 字段速查表（按字段名字母序）

10. 引用与配套资料