> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 原生 OpenAI 格式（ChatCompletions）

## 简介

通用文本对话接口，支持 OpenAI 兼容的大语言模型生成对话回答。通过统一的 API 接口，您可以调用 OpenAI、Claude、DeepSeek、Grok、通义千问等多个主流大模型。

## 认证

<ParamField header="Authorization" type="string" required>
  Bearer Token，如 `Bearer sk-xxxxxxxxxx`
</ParamField>

## 请求参数

<ParamField body="model" type="string" required>
  模型标识，支持的模型包括：

  * OpenAI 系列：`gpt-5.5`、`gpt-5.4`、`gpt-5.4-pro`、`gpt-5.4-mini`、`gpt-5.4-nano`、`gpt-4o` 等
  * Claude 系列：`claude-opus-4-8`、`claude-opus-4-7`、`claude-opus-4-6`、`claude-sonnet-4-5-20250929`、`claude-haiku-4-5-20251001` 等
  * DeepSeek 系列：`deepseek-v4-pro`、`deepseek-v4-flash`、`deepseek-v3-1-250821`、`deepseek-v3`、`deepseek-r1` 等
  * Grok 系列：`grok-4`、`grok-4-fast-reasoning`、`grok-3` 等
  * Gemini 系列：`gemini-3.1-pro-preview`、`gemini-3-pro-preview`、`gemini-3-flash-preview`、`nano-banana-pro` 及其 `-thinking/-nothinking` / `-thinking-<预算>` / `-thinking-low/-thinking-high` 后缀变体
  * 国产模型系列：`glm-5`、`glm-4.7`、`doubao-seed-1-8-251228`（豆包 Seed 系列）、`qwen3-coder-plus`、`kimi-k2.5` 等
</ParamField>

<ParamField body="messages" type="array" required>
  对话消息列表，每个元素包含 `role`（user/system/assistant）和 `content`
</ParamField>

<ParamField body="temperature" type="number" default="0.7">
  随机性控制，0-2，值越高回复越随机
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  是否启用流式输出，返回 SSE 格式的分片数据
</ParamField>

<ParamField body="max_tokens" type="number">
  最大生成 token 数，控制回复长度
</ParamField>

<ParamField body="top_p" type="number">
  核采样参数，0-1，控制生成的多样性
</ParamField>

## 基础示例

<Tab>
  <Tab title="非流式请求">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "glm-5",
        "messages": [
          {"role": "system", "content": "你是一个有用的助手"},
          {"role": "user", "content": "请用中文简要介绍人工智能"}
        ],
        "temperature": 0.7
      }'
    ```
  </Tab>

  <Tab title="流式请求（SSE）">
    ```bash theme={null}
    curl -N -X POST "https://api.gravitex.ai/v1/chat/completions" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "doubao-seed-1-8-251228",
        "stream": true,
        "messages": [
          {"role": "system", "content": "你是一个有用的助手"},
          {"role": "user", "content": "请用中文简要介绍人工智能"}
        ]
      }'
    ```
  </Tab>

  <Tab title="Python 示例">
    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(
        api_key="sk-xxxxxxxxxx",
        base_url="https://api.gravitex.ai/v1"
    )

    # 非流式
    completion = client.chat.completions.create(
        model="glm-5",
        messages=[
            {"role": "system", "content": "你是一个有用的助手"},
            {"role": "user", "content": "请用中文简要介绍人工智能"}
        ],
        temperature=0.7
    )
    print(completion.choices[0].message.content)

    # 流式
    stream = client.chat.completions.create(
        model="doubao-seed-1-8-251228",
        messages=[
            {"role": "user", "content": "请用中文简要介绍人工智能"}
        ],
        stream=True
    )
    for chunk in stream:
        if chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="")
    ```
  </Tab>
</Tab>

<ResponseExample>
  ```json theme={null}
  {
    "id": "chatcmpl-xxx",
    "object": "chat.completion",
    "created": 1234567890,
    "model": "glm-5",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "人工智能是研究、开发用于模拟、延伸和扩展人的智能的理论、方法、技术及应用系统的一门新的技术科学..."
        },
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 25,
      "completion_tokens": 100,
      "total_tokens": 125
    }
  }
  ```
</ResponseExample>

## 高级功能

### 工具调用（Functions / Tools）

支持 OpenAI 兼容的工具调用格式，适用于 GPT、Claude、DeepSeek、Grok、通义千问等模型。

<Tabs>
  <Tab title="第一阶段：模型返回工具调用">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "glm-5",
        "messages": [
          {"role": "user", "content": "上海的天气怎么样？"}
        ],
        "tools": [
          {
            "type": "function",
            "function": {
              "name": "get_weather",
              "description": "根据城市获取天气信息",
              "parameters": {
                "type": "object",
                "properties": {
                  "city": {"type": "string"}
                },
                "required": ["city"]
              }
            }
          }
        ],
        "tool_choice": "auto"
      }'
    ```
  </Tab>

  <Tab title="第二阶段：返回工具执行结果">
    模型返回 `tool_calls` 后，需要执行工具并将结果回传给模型：

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "glm-5",
        "messages": [
          {"role": "user", "content": "上海的天气怎么样？"},
          {
            "role": "assistant",
            "tool_calls": [
              {
                "id": "call_xxx",
                "type": "function",
                "function": {
                  "name": "get_weather",
                  "arguments": "{\"city\":\"上海\"}"
                }
              }
            ]
          },
          {
            "role": "tool",
            "tool_call_id": "call_xxx",
            "content": "{\"temp\":\"22°C\",\"condition\":\"多云\",\"aqi\":53}"
          }
        ]
      }'
    ```

    <Note>
      * `tool_call_id` 必须与第一阶段返回的 ID 一致
      * 工具执行失败时应返回可读的错误信息，避免阻塞后续补全
      * 第二阶段也支持流式输出
    </Note>
  </Tab>
</Tabs>

### 结构化输出（JSON Schema）

支持通过 `response_format` 参数控制输出格式，适用于 GPT、Claude、Grok 等模型。

```bash theme={null}
curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "doubao-seed-1-8-251228",
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "Answer",
        "schema": {
          "type": "object",
          "properties": {
            "summary": {"type": "string"}
          },
          "required": ["summary"]
        }
      }
    },
    "messages": [
      {"role": "user", "content": "返回一个包含 summary 字段的 JSON"}
    ]
  }'
```

<Tip>
  严格的结构化输出建议降低 `temperature` 值（如 0.1-0.3），并设置合适的 `max_tokens` 以提升一致性。
</Tip>

### 思考能力

部分模型支持思考能力（Thinking/Reasoning），可以在生成回复时展示推理过程。不同模型的实现方式不同：

<Tabs>
  <Tab title="DeepSeek">
    DeepSeek 模型支持通过 `thinking` 字段开启思考能力：

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "deepseek-v3-1-250821",
        "messages": [
          {"role": "system", "content": "你是一个有用的助手"},
          {"role": "user", "content": "给出一道中等难度的几何题并分步解析"}
        ],
        "thinking": {"type": "enabled"}
      }'
    ```

    <Note>
      * 默认 `thinking.type` 为 `"disabled"`，需要显式设置为 `"enabled"` 开启
      * 思考能力的输出形态可能因模型版本而异
      * 建议配合 `stream: true` 以获得更好的交互体验
    </Note>
  </Tab>

  <Tab title="通义千问">
    通义千问支持深度思考功能，需要配合流式输出：

    ```bash theme={null}
    curl -N -X POST "https://api.gravitex.ai/v1/chat/completions" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "qwen3-omni-flash",
        "stream": true,
        "enable_thinking": true,
        "parameters": {
          "incremental_output": true
        },
        "messages": [
          {"role": "system", "content": "你是一名优秀的数学家"},
          {"role": "user", "content": "汉诺塔的公式是啥"}
        ]
      }'
    ```

    **将推理过程内联到 content**：

    如果客户端不展示 `reasoning_content`，可以使用 `gravitex_thinking_to_content: true` 将推理内容内联到 `content` 中：

    ```bash theme={null}
    curl -N -X POST "https://api.gravitex.ai/v1/chat/completions" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "qwen3-omni-flash",
        "stream": true,
        "enable_thinking": true,
        "gravitex_thinking_to_content": true,
        "parameters": {
          "incremental_output": true
        },
        "messages": [
          {"role": "user", "content": "汉诺塔的公式是啥"}
        ]
      }'
    ```

    <Warning>
      通义千问的深度思考功能必须配合 `stream: true` 使用。如果设置了 `enable_thinking: true` 但 `stream: false`，系统会自动关闭深度思考以避免上游报错。
    </Warning>
  </Tab>

  <Tab title="Gemini">
    完整 Gemini OpenAI 兼容说明（字段映射、`extra_body`、usage、思维链等）见 [Gemini OpenAI 格式（对话）](/cn/api-reference/endpoint/gemini-chat-openai)。以下为常用速查：

    * **模型后缀**：`-thinking` 自动预算；`-thinking-<数字>` 精确预算（如 `gemini-2.5-flash-thinking-8192`）；`-nothinking` 关闭；`gemini-3-pro-preview-thinking-low/high` 直接指定级别
    * **extra\_body 配置**：`extra_body.google.thinking_config.thinking_budget` + `include_thoughts`，支持特殊值：`-1` 自动开启、`0` 关闭、`>0` 指定预算；需 `stream: true`
    * **reasoning\_effort**：在 `-thinking` 且未设置 `max_tokens` 时可用（`low/medium/high`≈20%/50%/80% 预算）
    * **Gemini 3 Pro Preview**：使用 `thinking_level`（`LOW`/`HIGH`，默认 HIGH），可同时结合搜索
    * **搜索开启**：推荐 OpenAI 兼容工具 `"tools":[{"type":"function","function":{"name":"googleSearch"}}]`；或透传 `extra_body.google.tools:[{"googleSearch":{}}]`
    * **注意**：需启用思考适配器（服务端配置），思考预算占用输出 token，务必使用 `stream: true` 才能看到 `reasoning_content`

    示例（2.5 指定预算）：

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "gemini-3-flash-preview",
        "messages": [
          {"role":"user","content":"给出一道中等难度的几何题并分步解析。"}
        ],
        "extra_body": {
          "google": {
            "thinking_config": { "thinking_budget": 6000, "include_thoughts": true }
          }
        },
        "stream": true
      }'
    ```

    示例（3 Pro Preview 思考+搜索）：

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "gemini-3-pro-preview",
        "messages": [
          {"role":"user","content":"Google 搜索一下今天广州的天气怎么样"}
        ],
        "generationConfig": {
          "thinkingConfig": { "thinkingLevel": "LOW" }
        },
        "tools": [
          { "type": "function", "function": { "name": "googleSearch" } }
        ],
        "stream": true
      }'
    ```
  </Tab>
</Tabs>

### 通义千问扩展功能

通义千问模型支持搜索、语音识别等扩展功能，所有扩展参数需放入 `parameters` 对象中。

<Tabs>
  <Tab title="搜索功能">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "qwen3-omni-flash",
        "messages": [
          {"role": "user", "content": "请先检索近期关于费马大定理的常见误解，再回答"}
        ],
        "stream": true,
        "enable_thinking": true,
        "parameters": {
          "enable_search": true,
          "search_options": {
            "region": "CN",
            "recency_days": 30
          },
          "incremental_output": true
        }
      }'
    ```
  </Tab>

  <Tab title="语音识别">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "qwen3-omni-flash",
        "messages": [
          {"role": "user", "content": "你好"}
        ],
        "parameters": {
          "asr_options": {
            "language": "zh"
          }
        }
      }'
    ```
  </Tab>
</Tabs>

<Note>
  通义千问的所有扩展参数（如 `enable_search`、`search_options`、`asr_options`、`temperature`、`top_p` 等）都需要放在 `parameters` 对象中，而不是请求体的顶层。
</Note>

### 联网搜索功能

部分模型支持实时联网搜索，可以获取最新信息并在响应中包含引用来源。

<Tabs>
  <Tab title="Claude 搜索">
    Claude   模型不支持通过 `web_search_options` 参数开启网络搜索功能，所以使用只能通过tool工具调用实现，且可能因为网络和提示词等原因不稳定,详细看上面工具调用（Functions / Tools）。

    **基础示例**（展示工具调用流程）：

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "glm-5",
        "messages": [
          {"role": "user", "content": "最近关于人工智能的新闻有哪些？"},
          {
            "role": "assistant",
            "content": "我来帮你搜索一下最近关于人工智能的新闻。",
            "tool_calls": [
              {
                "id": "toolu_xxx",
                "type": "function",
                "function": {
                  "name": "WebSearch",
                  "arguments": "{\"query\": \"人工智能 最新新闻 2025\"}"
                }
              }
            ]
          },
          {
            "role": "tool",
            "tool_call_id": "toolu_xxx",
            "name": "WebSearch",
            "content": "Web search results for query: \"人工智能 最新新闻 2025\"..."
          }
        ],
        "web_search_options": {
          "search_context_size": "medium"
        }
      }'
    ```

    **带位置信息的示例**（展示工具调用流程）：

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "glm-5",
        "messages": [
          {"role": "user", "content": "上海今天的天气怎么样？"},
          {
            "role": "assistant",
            "content": "我来帮你搜索一下上海今天的天气情况。",
            "tool_calls": [
              {
                "id": "toolu_xxx",
                "type": "function",
                "function": {
                  "name": "WebSearch",
                  "arguments": "{\"query\": \"上海今天天气\"}"
                }
              }
            ]
          },
          {
            "role": "tool",
            "tool_call_id": "toolu_xxx",
            "name": "WebSearch",
            "content": "Web search results for query: \"上海今天天气\"..."
          }
        ],
        "web_search_options": {
          "search_context_size": "medium",
          "user_location": {
            "approximate": {
              "timezone": "Asia/Shanghai",
              "country": "CN",
              "region": "Shanghai",
              "city": "Shanghai"
            }
          }
        }
      }'
    ```

    <Note>
      * 搜索功能会增加响应时间和 token 消耗（包含搜索结果内容）
      * 搜索结果会在响应中自动包含引用来源
      * 支持的模型包括 Claude Sonnet 4、Claude 3 Opus 等
      * 在多轮对话中，工具调用和结果会在消息历史中可见，模型可以基于之前的搜索结果继续对话
    </Note>

    <Note type="warning">
      **稳定性说明**：

      * 联网搜索功能依赖上游代理服务和外部搜索服务，可能存在以下不稳定性：
        * **网络波动**：网络连接问题可能导致搜索请求超时或失败
        * **服务限制**：搜索服务可能有频率限制、超时限制或临时不可用
        * **搜索结果质量**：某些查询可能无法找到相关信息，或搜索结果质量不佳
        * **模型判断**：模型会根据问题自动判断是否需要搜索，某些情况下可能不会触发搜索
    </Note>
  </Tab>

  <Tab title="Grok 搜索">
    Grok 模型支持通过 `search_parameters` 参数控制实时搜索行为。

    <ParamField body="search_parameters" type="object">
      搜索参数配置

      * `mode`（可选）：搜索模式，可选值：
        * `"off"`：禁用搜索
        * `"auto"`：模型自动判断是否需要搜索（推荐）
        * `"on"`：强制使用搜索
      * `return_citations`（可选）：是否在响应中返回引用链接，默认为 `true`
    </ParamField>

    **基础示例**：

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "grok-4",
        "messages": [
          {"role": "user", "content": "2026年人工智能领域有什么最新进展？"}
        ],
        "search_parameters": {
          "mode": "auto"
        }
      }'
    ```

    **强制搜索示例**：

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "grok-4",
        "messages": [
          {"role": "user", "content": "最新的科技新闻有哪些？"}
        ],
        "search_parameters": {
          "mode": "on",
          "return_citations": true
        }
      }'
    ```

    **Python 示例**：

    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(
        api_key="sk-xxxxxxxxxx",
        base_url="https://api.gravitex.ai/v1"
    )

    completion = client.chat.completions.create(
        model="grok-4",
        messages=[
            {"role": "user", "content": "2026年人工智能领域有什么最新进展？"}
        ],
        extra_body={
            "search_parameters": {
                "mode": "auto"
            }
        }
    )
    print(completion.choices[0].message.content)
    ```

    <Note>
      * 推荐使用 `"auto"` 模式，让模型自动判断是否需要搜索
      * 搜索功能会增加响应时间，但能获取最新的实时信息
      * 支持的模型包括 `grok-4`、`grok-3` 等系列
      * 搜索结果会在响应中包含引用来源
    </Note>
  </Tab>
</Tabs>

### GPT 文件输入（Responses API）

GPT-5 等模型支持文件输入功能，需要通过 `/v1/responses` 接口调用，而不是 `/v1/chat/completions`。

<Tabs>
  <Tab title="通过文件 URL 上传">
    您可以通过链接外部网址上传 PDF 文件：

    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(
        api_key="sk-xxxxxxxxxx",
        base_url="https://api.gravitex.ai/v1/responses?api-version=2025-03-01-preview"
    )

    response = client.responses.create(
        model="gpt-5.2",
        input=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": "分析这封信，并总结其关键点"
                    },
                    {
                        "type": "input_file",
                        "file_url": "https://www.example.com/document.pdf"
                    }
                ]
            }
        ]
    )
    print(response.output_text)
    ```
  </Tab>

  <Tab title="通过 Base64 编码上传">
    作为 Base64 编码的输入发送：

    ```python theme={null}
    import base64
    from openai import OpenAI

    client = OpenAI(
        api_key="sk-xxxxxxxxxx",
        base_url="https://api.gravitex.ai/v1"
    )

    with open("document.pdf", "rb") as f:
        data = f.read()

    base64_string = base64.b64encode(data).decode("utf-8")

    response = client.responses.create(
        model="gpt-5.2",
        input=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_file",
                        "filename": "document.pdf",
                        "file_data": f"data:application/pdf;base64,{base64_string}"
                    },
                    {
                        "type": "input_text",
                        "text": "这份文档的主要内容是什么？"
                    }
                ]
            }
        ]
    )
    print(response.output_text)
    ```
  </Tab>
</Tabs>

<Note>
  * 文件大小限制：单个文件不超过 50 MB，单个请求中所有文件总大小不超过 50 MB
  * 支持的模型：`gpt-4o`、`gpt-4o-mini`、`gpt-5-chat` 等支持文本和图像输入的模型
</Note>

### Grok 推理能力

Grok 模型（特别是 `grok-4-fast-reasoning`）支持推理能力。启用后，`usage.completion_tokens_details.reasoning_tokens` 会显示推理过程消耗的 token 数。详见下方 [usage 字段说明](#usage-字段说明)。

## usage 字段说明

调用 `/v1/chat/completions` 时，响应中的 `usage` 对象包含 token 用量统计。以下先介绍**通用字段**（普通对话模型场景），再说明仅在特定场景下才会出现非零值的**专属字段**。

### 通用字段

适用范围：GPT 系列、Claude 对话/思考模型、Gemini、DeepSeek 等经由 `/v1/chat/completions` 走文本对话场景。不包含仅在底层实际调用 Claude Messages 协议或图片生成模型时才出现的字段——那些见 [特殊场景专属字段](#特殊场景专属字段)。

```json theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1752345600,
  "model": "gpt-5.6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "这是模型的回复内容"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 85,
    "total_tokens": 205,

    "prompt_tokens_details": {
      "cached_tokens": 30,
      "cache_write_tokens": 5,
      "text_tokens": 0,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "image_tokens": 0,
      "reasoning_tokens": 42,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    },

    "input_tokens": 120,
    "output_tokens": 85,
    "input_tokens_details": null
  }
}
```

| 字段                                                                                    | 什么时候会有值                                                  | 说明                                                                   |
| ------------------------------------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------- |
| `prompt_tokens`                                                                       | 始终                                                       | 输入 token 总数                                                          |
| `completion_tokens`                                                                   | 始终                                                       | 输出 token 总数                                                          |
| `total_tokens`                                                                        | 始终                                                       | `prompt_tokens + completion_tokens`                                  |
| `prompt_tokens_details.cached_tokens`                                                 | 模型/渠道支持 prompt caching 时                                 | 命中缓存、按缓存价计费的输入 token 数（OpenAI 原生缓存、Gemini 隐式缓存、Claude 缓存读取都会体现在这个字段） |
| `prompt_tokens_details.cache_write_tokens`                                            | 仅 GPT-5.6 及以上、开启显式 prompt cache 时                        | 本次请求新写入缓存、按缓存写入价计费的 token 数                                          |
| `prompt_tokens_details.audio_tokens`                                                  | 仅使用音频输入模型（如 `gpt-4o-audio-preview`）时                     | 输入中音频部分消耗的 token 数                                                   |
| `prompt_tokens_details.text_tokens` / `image_tokens`                                  | 多数纯文本对话模型下为 `0`                                          | 输入中文本 / 图片部分的 token 拆分，纯文本对话场景通常不会被填充，只是字段本身始终存在                     |
| `completion_tokens_details.reasoning_tokens`                                          | 仅推理模型（GPT o1/o3/GPT-5 系列、Claude 开启扩展思考、Gemini thinking）时 | 模型内部思考消耗的 token 数，不会出现在最终回复文本里，但按输出价计费                               |
| `completion_tokens_details.audio_tokens`                                              | 仅使用音频输出模型时                                               | 输出中音频部分消耗的 token 数                                                   |
| `completion_tokens_details.accepted_prediction_tokens` / `rejected_prediction_tokens` | 仅使用 OpenAI Predicted Outputs 功能时                         | 命中 / 未命中预测内容的 token 数；未命中的部分仍按输出价计费                                  |
| `completion_tokens_details.text_tokens` / `image_tokens`                              | 纯文本对话场景下为 `0`                                            | 见下方「关于 image\_tokens」说明                                              |
| `input_tokens` / `output_tokens`                                                      | 始终                                                       | 数值上等同于 `prompt_tokens` / `completion_tokens`，是为兼容部分上游协议保留的别名字段       |
| `input_tokens_details`                                                                | 目前对话场景下基本为 `null`                                        | 保留字段，普通对话请求不会填充                                                      |

<Note>
  * `prompt_tokens_details` / `completion_tokens_details` 这两个对象在响应里**始终存在**，即使内部子字段全是 `0` 也不会被省略；`0` 不代表「不支持」，只代表「这次请求没用到」。
  * `completion_tokens_details.image_tokens`（以及 `prompt_tokens_details.image_tokens`）留在通用文档里是因为字段结构固定存在，但**真正被赋非零值只发生在特殊场景**（Claude/图片生成模型），详见 [特殊场景专属字段](#特殊场景专属字段)。
  * `reasoning_tokens` 是跨模型通用概念：无论底层是 OpenAI 推理模型、Claude 扩展思考还是 Gemini thinking，只要该次调用启用了「思考」能力，都会体现在这一个字段里。
</Note>

### 特殊场景专属字段

以下字段只在特定情况下才会出现非零值：请求走的是 `/v1/chat/completions`，但网关内部实际把请求转换成了别的协议去调用上游（Claude Messages 协议 / 图片生成模型），转换回来的 `usage` 里就会带上这些「原生协议专属」的字段。

#### 场景一：底层实际调用 Claude（`/v1/chat/completions` → `/v1/messages`）

用 OpenAI 格式请求一个 Claude 模型时，网关会把请求转成 Anthropic Messages 协议发给上游，再把 Claude 返回的 `usage` 转换回 OpenAI 格式。Claude 的缓存机制比 OpenAI 更细（按 5 分钟 / 1 小时两档 TTL 计费），这部分信息用下面几个专属字段承载：

```json theme={null}
"usage": {
  "prompt_tokens": 120,
  "completion_tokens": 85,
  "total_tokens": 205,
  "prompt_tokens_details": {
    "cached_tokens": 30,
    "cached_creation_tokens": 10
  },
  "completion_tokens_details": {
    "reasoning_tokens": 42
  },
  "claude_cache_creation_5_m_tokens": 8,
  "claude_cache_creation_1_h_tokens": 2
}
```

| 字段                                             | 说明                                                                                                    |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `prompt_tokens_details.cached_creation_tokens` | 对应 Claude 的 `cache_creation_input_tokens`：本次请求为写入 prompt cache 而额外消耗的输入 token 数（这个总数会被下面两个字段按 TTL 拆分） |
| `claude_cache_creation_5_m_tokens`             | 上面 `cached_creation_tokens` 中，按 **5 分钟** TTL 档写入缓存的 token 数                                           |
| `claude_cache_creation_1_h_tokens`             | 上面 `cached_creation_tokens` 中，按 **1 小时** TTL 档写入缓存的 token 数（该档位单价更高）                                  |

`prompt_tokens_details.cached_tokens`、`completion_tokens_details.reasoning_tokens` 在调用 Claude 模型时也会有值（分别对应 Claude 的缓存读取 token 数、扩展思考 token 数），但这两个字段是跨模型通用字段，已在 [通用字段](#通用字段) 中说明。

#### 场景二：底层实际调用图片生成模型（`/v1/chat/completions` → `/v1/images/generations` 语义）

某些图片生成模型（如 Gemini 原生图片输出、`gpt-image` 系列）本来是走官方 `/v1/images/generations` 接口的 `usage` 结构（`input_tokens`/`output_tokens` + 按模态拆分），但当用户改用 `/v1/chat/completions` 直接对话式调用这些模型生成图片时，网关会把这部分信息映射进 chat 格式的 `usage` 里：

```json theme={null}
"usage": {
  "prompt_tokens": 50,
  "completion_tokens": 1290,
  "total_tokens": 1340,
  "prompt_tokens_details": {
    "text_tokens": 50,
    "image_tokens": 0
  },
  "completion_tokens_details": {
    "text_tokens": 0,
    "image_tokens": 1290
  },
  "generated_images": 1
}
```

| 字段                                       | 说明                                                                                              |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `completion_tokens_details.image_tokens` | 官方 `/v1/images/generations` 里的图片输出 token 数，映射进 chat 格式后落在这个字段，按图片计费比例（`ImageCompletionRatio`）计费 |
| `prompt_tokens_details.image_tokens`     | 输入侧包含图片时（如图片编辑/图生图）消耗的图片 token 数                                                                |
| `generated_images`                       | 上游实际生成的图片张数（按张计费的模型用这个数值而不是 token 数来计费，避免「请求 4 张但只出 1 张」多扣费）                                    |

#### 场景三：渠道协议差异导致的字段

这两个字段不是「转换」出来的，而是特定渠道原样透传上游响应字段，正常使用主流模型基本不会遇到：

| 字段                        | 出现条件                                    | 说明                                                                                                                                      |
| ------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt_cache_hit_tokens` | 渠道是 DeepSeek，且上游按 DeepSeek 自己的字段名返回缓存信息 | DeepSeek 官方 API 用 `prompt_cache_hit_tokens` 而不是 `cached_tokens` 表达缓存命中；网关会把它同步映射进通用的 `prompt_tokens_details.cached_tokens`，但原始字段也会保留在顶层 |
| `cost`                    | 渠道是 OpenRouter，且上游在响应里带了美元成本            | OpenRouter 专属字段，普通渠道（官方 OpenAI/Claude/Gemini 等）不会出现                                                                                     |

## 响应格式

<Tabs>
  <Tab title="非流式响应">
    ```json theme={null}
    {
      "id": "chatcmpl-xxx",
      "object": "chat.completion",
      "created": 1234567890,
      "model": "glm-5",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "回复内容..."
          },
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 25,
        "completion_tokens": 100,
        "total_tokens": 125
      }
    }
    ```

    `usage` 各字段的完整说明见上方 [usage 字段说明](#usage-字段说明)。
  </Tab>

  <Tab title="流式响应">
    流式响应以 SSE（Server-Sent Events）格式返回，每个分片包含部分内容：

    ```json theme={null}
    data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"doubao-seed-1-8-251228","choices":[{"index":0,"delta":{"content":"回"},"finish_reason":null}]}

    data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"doubao-seed-1-8-251228","choices":[{"index":0,"delta":{"content":"复"},"finish_reason":null}]}

    data: [DONE]
    ```

    最后一个分片通常包含 `usage` 统计信息。
  </Tab>
</Tabs>

## 错误处理

| 异常类型                | 触发场景         | 返回信息                    |
| ------------------- | ------------ | ----------------------- |
| AuthenticationError | API密钥无效或未授权  | 错误：API密钥无效或未授权          |
| NotFoundError       | 模型不存在或不被支持   | 错误：模型 \[model] 不存在或不被支持 |
| APIConnectionError  | 网络中断或服务器未响应  | 错误：无法连接到API服务器          |
| APIError            | 请求格式错误等服务端异常 | API请求失败：\[错误详情]         |

## 支持的模型系列

### OpenAI 系列

* GPT-5.5、GPT-5.4 系列（5.4 / Pro / Mini / Nano）、GPT-4o、GPT-4o Mini

### Claude 系列（Anthropic）

* Claude Sonnet 4、Claude 3 Opus、Claude 3 Haiku

### DeepSeek 系列

* DeepSeek V3、DeepSeek R1

### Grok 系列（xAI）

* Grok-4、Grok-3、Grok-3-fast、Grok-4-fast-reasoning

### 通义千问系列（Qwen）

* Qwen3-omni-flash 等

### 豆包 Seed 系列（Doubao）

* doubao-seed-1-8-251228 等

### 其他模型

* Gemini 系列、GLM 系列（含 glm-5）、Kimi 系列等

完整模型列表请查看 [模型信息页面](/cn/api-reference/models)。

## 注意事项

<Note>
  * `messages` 列表中 `system` 角色用于设定模型行为，`user` 角色为用户提问
  * 多轮对话需追加历史记录（包含 `assistant` 角色的回复）
  * 依赖 `openai` 库：`pip install openai`
  * 不同模型对某些功能的支持程度可能不同，建议在使用前查看具体模型的文档
</Note>

<Tip>
  * 使用流式输出可以提升首字响应时间和交互体验
  * 工具调用需要做好超时与重试机制，避免阻塞模型响应
  * 通义千问的扩展参数必须放在 `parameters` 对象中
</Tip>

## 相关资源

<Columns cols={2}>
  <Card title="常见问题" icon="question-circle" href="/cn/faq/chat-completions">
    查看对话接口的常见问题解答
  </Card>

  <Card title="模型列表" icon="list" href="/cn/api-reference/models">
    查看所有支持的模型信息
  </Card>
</Columns>