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

# 通用对话接口

> OpenAI Chat Completions 兼容格式，适用于 GPT / Claude / Gemini

使用 OpenAI Chat Completions 兼容格式发起对话请求，可统一调用 GPT、Claude、Gemini 等文本与多模态模型。

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://gogogotoken.ai/v1/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [
        { "role": "system", "content": "你是一个简洁的技术助手。" },
        { "role": "user", "content": "用三点说明 API 网关的作用。" }
      ],
      "stream": false
    }'
  ```

  ```bash 流式 theme={null}
  curl -N -X POST https://gogogotoken.ai/v1/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "claude-sonnet-4-20250514",
      "messages": [
        { "role": "user", "content": "Write a haiku about the sea." }
      ],
      "stream": true,
      "stream_options": {
        "include_usage": true
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "chatcmpl_abc123",
    "object": "chat.completion",
    "created": 1730000000,
    "model": "gpt-4o",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "API 网关可以统一鉴权、转发请求，并集中记录用量。"
        },
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 32,
      "completion_tokens": 18,
      "total_tokens": 50
    }
  }
  ```

  ```text 流式 theme={null}
  data: {"id":"chatcmpl_abc123","object":"chat.completion.chunk","choices":[{"delta":{"content":"API"}}]}

  data: {"id":"chatcmpl_abc123","object":"chat.completion.chunk","choices":[{"delta":{"content":" 网关"}}]}

  data: [DONE]
  ```

  ```json 401 theme={null}
  {
    "error": {
      "message": "Invalid API key",
      "type": "invalid_request_error",
      "code": "invalid_api_key"
    }
  }
  ```
</ResponseExample>

## 接口说明

该接口用于以统一对话格式调用 OpenAI、Claude、Gemini 等上游模型。默认返回完整 JSON；如需边生成边展示，请在请求体中传入 `"stream": true`。

<Info>
  模型可用范围取决于 API Key 的分组权限。完整模型清单以 `GET /v1/models` 返回为准。
</Info>

## 请求头

<ParamField header="Authorization" type="string" required>
  API Key 鉴权信息，格式为 `Bearer YOUR_API_KEY`。
</ParamField>

<ParamField header="Content-Type" type="string" required>
  固定为 `application/json`。
</ParamField>

## 请求体

<ParamField body="model" type="string" required default="gpt-4o">
  模型 ID，例如 `gpt-4o`、`claude-sonnet-4-20250514`、`gemini-2.5-pro`。可通过 `GET /v1/models` 查询当前 API Key 可用模型。
</ParamField>

<ParamField body="messages" type="object[]" required default={[{ role: "user", content: "用三点说明 API 网关的作用。" }]}>
  对话消息数组，按顺序传入上下文。

  <ParamField body="role" type="string" required>
    消息角色，常用值为 `system`、`user`、`assistant`。
  </ParamField>

  <ParamField body="content" type="string" required>
    消息内容。文本对话可传字符串；视觉模型可传 OpenAI 兼容的多模态数组。
  </ParamField>
</ParamField>

<ParamField body="stream" type="boolean" default={false}>
  是否使用 SSE 流式返回，默认 `false`。
</ParamField>

<ParamField body="stream_options.include_usage" type="boolean">
  流式模式下是否在结束前返回 token 用量信息。
</ParamField>

<ParamField body="temperature" type="number">
  采样温度，常用范围为 `0` 到 `2`。数值越高，输出越发散。
</ParamField>

<ParamField body="max_tokens" type="integer">
  最大输出 token 数。
</ParamField>

## 响应体

<ResponseField name="id" type="string">
  本次请求的唯一 ID。
</ResponseField>

<ResponseField name="object" type="string">
  对象类型。非流式响应通常为 `chat.completion`，流式片段通常为 `chat.completion.chunk`。
</ResponseField>

<ResponseField name="model" type="string">
  实际参与生成的模型 ID。
</ResponseField>

<ResponseField name="choices" type="object[]">
  模型输出结果数组。非流式响应中可读取 `choices[0].message.content`；流式响应中可逐段读取 `choices[0].delta.content`。
</ResponseField>

<ResponseField name="usage" type="object">
  token 用量统计，通常包含 `prompt_tokens`、`completion_tokens` 与 `total_tokens`。
</ResponseField>

## 多模态输入

Vision 模型支持 OpenAI 兼容的图片输入格式：

```json theme={null}
{
  "model": "gpt-4o",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "图中是什么？" },
      { "type": "image_url", "image_url": { "url": "https://example.com/cat.png" } }
    ]
  }]
}
```

## 错误码

| 状态码   | 含义            | 处理建议                   |
| ----- | ------------- | ---------------------- |
| `401` | API Key 无效或未传 | 检查 `Authorization` 请求头 |
| `403` | 无权限访问该模型      | 确认 API Key 分组是否包含目标模型  |
| `402` | 余额不足          | 充值或调整调用配额              |
| `429` | 触发限速          | 降低请求频率或联系管理员           |
| `5xx` | 上游或网关异常       | 稍后重试，并查看控制台日志          |