OpenAI Chat API 兼容接口

本平台对外提供兼容 OpenAI Chat Completions API 的聊天接口。

本文档面向客户端调用方，重点说明公开请求路径、认证方式、请求参数和示例写法。请求体字段名与 JSON 结构尽量保持与 OpenAI Chat Completions API 一致。

说明：

接口路径：POST /v1/chat/completions
能力类型：聊天 / 文本生成
返回方式：
- stream = false 或不传：返回标准 JSON
- stream = true：返回 text/event-stream SSE 流
协议风格：请求体保持 OpenAI Chat Completions 原生结构，不额外包一层 input

当前范围：

仅覆盖 POST /v1/chat/completions
POST /v1/responses 已支持，但不在本文展开，详见：/docs/api-reference/text/openai-response-api
不覆盖 embeddings、images、audio 等其他 OpenAI 接口

1. 接口概览

请求方法：POST
请求路径：/v1/chat/completions
Content-Type：application/json
响应类型：
- 非流式：application/json
- 流式：text/event-stream

2. 认证与请求头

请求头示例：

Authorization: Bearer YOUR_REACH_API_KEY
Content-Type: application/json

其中 Authorization 与 x-api-key 至少传一个。

请求头说明：

请求头	必填	说明
`Authorization`	否	平台 API Key，格式：`Bearer sk-xxxxxx`
`x-api-key`	否	也可直接通过该请求头传平台 API Key
`Content-Type`	是	固定为 `application/json`

3. 请求体

请求体保持 OpenAI Chat Completions 原生对象结构：

{
  "model": "YOUR_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "请用一句话介绍你自己。"
    }
  ],
  "temperature": 0.2,
  "stream": false
}

3.1 顶层参数说明

字段	类型	必填	说明
`model`	string	是	模型 ID
`messages`	`array<object>`	是	对话消息列表，至少一项
`temperature`	number	否	采样温度
`top_p`	number	否	nucleus sampling 参数
`n`	integer	否	候选结果数
`max_tokens`	integer	否	最大输出 token 数
`max_completion_tokens`	integer	否	部分模型支持的新输出 token 限制字段
`stop`	`string` 或 `array<string>`	否	停止序列
`stream`	boolean	否	是否以 SSE 流式返回
`stream_options`	object	否	流式附加配置，例如 `include_usage`
`tools`	`array<object>`	否	工具定义
`tool_choice`	string 或 object	否	工具调用策略
`parallel_tool_calls`	boolean	否	是否允许并行工具调用
`response_format`	object	否	结构化输出配置
`presence_penalty`	number	否	话题新颖性惩罚
`frequency_penalty`	number	否	重复惩罚
`logit_bias`	object	否	token bias 配置
`user`	string	否	终端用户标识

3.2 `messages` 参数说明

每条消息结构如下：

字段	类型	必填	说明
`role`	string	是	角色，常用值：`system`、`user`、`assistant`、`tool`
`content`	`string` 或 `array<object>`	是	消息内容，可传文本或内容块数组
`name`	string	否	可选角色名
`tool_call_id`	string	否	当 `role = tool` 时用于关联工具调用

文本形式示例：

{
  "role": "user",
  "content": "写一段 50 字以内的产品介绍。"
}

内容块形式示例：

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "请描述这张图片"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://cdn.example.com/demo.png"
      }
    }
  ]
}

4. 请求示例

4.1 标准非流式请求

curl -X POST "https://direct.reachapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "请用一句话介绍 reach-api。"
      }
    ],
    "temperature": 0.2
  }'

4.2 流式请求

curl -X POST "https://direct.reachapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "请分三行介绍今天的工作重点。"
      }
    ],
    "stream": true,
    "stream_options": {
      "include_usage": true
    }
  }'

4.3 带工具定义的请求

curl -X POST "https://direct.reachapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "帮我查一下上海天气"
      }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "查询指定城市天气",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string"
              }
            },
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

5. 成功响应

非流式响应示例：

{
  "id": "chatcmpl_123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "YOUR_MODEL_ID",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好，我是一个由模型驱动的助手。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 18,
    "total_tokens": 30
  }
}

6. 流式响应

当 stream = true 时，返回 OpenAI 风格 SSE：

data: {"id":"chatcmpl_123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}

data: {"id":"chatcmpl_123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"}}]}

data: [DONE]

7. 错误响应

OpenAI 风格错误示例：

{
  "error": {
    "message": "Field `messages` is required",
    "type": "invalid_request_error",
    "param": null,
    "code": "MISSING_REQUIRED_FIELD"
  }
}

常见场景：

请求体缺失 model
请求体缺失 messages
请求 JSON 非法
鉴权失败

8. 兼容说明

本文档列出的是常用字段和示例写法，字段名与结构以 OpenAI Chat Completions API 为准
本接口仅覆盖 Chat Completions 路径，不等同于 OpenAI 全部接口能力
若使用实验性或较新的官方字段，请结合实际可用能力验证

9. 支持模型与参考价格

以下价格整理自统一计费文档，适用于当前已整理的 GPT 文本模型。价格核对日期为 2026-04-17，详细口径以统一计费文档 gpt.md 为准。

模型	Input	Cached input	Output
`gpt-5.4`	`$2.50 / 1M tokens`	`$0.25 / 1M tokens`	`$15.00 / 1M tokens`
`gpt-5.3-codex`	`$1.75 / 1M tokens`	`$0.175 / 1M tokens`	`$14.00 / 1M tokens`
`gpt-5.2`	`$1.75 / 1M tokens`	`$0.175 / 1M tokens`	`$14.00 / 1M tokens`
`gpt-5.1-codex`	`$1.25 / 1M tokens`	`$0.125 / 1M tokens`	`$10.00 / 1M tokens`
`gpt-5.1`	`$1.25 / 1M tokens`	`$0.125 / 1M tokens`	`$10.00 / 1M tokens`
`gpt-5`	`$1.25 / 1M tokens`	`$0.125 / 1M tokens`	`$10.00 / 1M tokens`
`gpt-5.4-mini`	`$0.75 / 1M tokens`	`$0.075 / 1M tokens`	`$4.50 / 1M tokens`
`gpt-5-mini`	`$0.25 / 1M tokens`	`$0.025 / 1M tokens`	`$2.00 / 1M tokens`

说明：

Cached input 对应命中缓存的输入 token 单价
若模型列表后续有增删，请以控制台或产品配置中的实际上线模型为准

10. 参考资料

OpenAI Chat Completions API 文档： https://platform.openai.com/docs/api-reference/chat/create
OpenAI 文本生成指南： https://platform.openai.com/docs/guides/text?api-mode=chat
OpenAI API 错误说明： https://platform.openai.com/docs/guides/error-codes/api-errors
平台统一计费文档：gpt.md

OpenAI Chat API 兼容接口

On this page