OpenAI Chat Completions

接口信息

• 接口路径：POST https://router.253.com/v1/chat/completions
• 认证方式：API Key
• 响应格式：application/json

用于基于消息历史生成聊天回复，兼容 OpenAI Chat Completions 请求和响应格式。

请求头

复制成功⧉
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
Content-Type: application/json

请求参数

messages 结构

多模态 content 支持的常见内容块：

基础请求示例

复制成功⧉
curl -X POST "https://router.253.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-name",
    "messages": [
      {
        "role": "system",
        "content": "你是一个简洁、准确的助手。"
      },
      {
        "role": "user",
        "content": "用三句话介绍杭州。"
      }
    ],
    "temperature": 0.7,
    "max_completion_tokens": 500
  }'

2.5 非流式响应示例

复制成功⧉
{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "created": 1792368000,
  "model": "your-model-name",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "杭州是浙江省省会，以西湖和深厚的人文历史闻名。这里兼具数字经济活力与江南山水气质。龙井茶、灵隐寺和京杭大运河也是城市的重要名片。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 48,
    "total_tokens": 73
  }
}

finish_reason 常见值：

流式请求示例

复制成功⧉
curl -N -X POST "https://router.253.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-name",
    "messages": [
      {"role": "user", "content": "写一句关于秋天的话。"}
    ],
    "stream": true,
    "stream_options": {
      "include_usage": true
    }
  }'

响应由多个 data: 块组成：

复制成功⧉
data: {"id":"chatcmpl-example","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-example","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"秋风掠过树梢，"},"finish_reason":null}]}

data: {"id":"chatcmpl-example","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"把黄昏染成了金色。"},"finish_reason":null}]}

data: [DONE]

工具调用示例

请求：

复制成功⧉
{
  "model": "your-model-name",
  "messages": [
    {
      "role": "user",
      "content": "杭州现在天气怎么样？"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "查询指定城市天气",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "城市名称"
            }
          },
          "required": [
            "city"
          ]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

模型可能返回：

复制成功⧉
{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_001",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"杭州\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

执行工具后，将结果作为 tool 消息再次提交：

复制成功⧉
{
  "model": "your-model-name",
  "messages": [
    {
      "role": "user",
      "content": "杭州现在天气怎么样？"
    },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_001",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"city\":\"杭州\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_001",
      "content": "{\"temperature\":24,\"condition\":\"晴\"}"
    }
  ]
}

---

OpenAI Responses

接口信息

• 接口路径：POST https://router.253.com/v1/responses
• 认证方式：API Key
• 响应格式：application/json

Responses API 使用统一的 input 和 output 结构，适合推理模型、多轮响应、工具调用和多模态输入。

请求头

复制成功⧉
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
Content-Type: application/json

请求参数

input 可以直接使用字符串：

复制成功⧉
{
  "input": "解释什么是幂等性。"
}

也可以使用消息数组：

复制成功⧉
{
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "描述这张图片。"
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/image.jpg"
        }
      ]
    }
  ]
}

常见输入内容块：

基础请求示例

复制成功⧉
curl -X POST "https://router.253.com/v1/responses" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-name",
    "instructions": "回答应准确、简洁。",
    "input": "解释 REST API 中幂等性的含义。",
    "max_output_tokens": 500
  }'

非流式响应示例

复制成功⧉
{
  "id": "resp_example",
  "object": "response",
  "created_at": 1792368000,
  "status": "completed",
  "model": "your-model-name",
  "output": [
    {
      "type": "message",
      "id": "msg_example",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "幂等性表示同一个请求执行一次或多次，对服务端产生的最终效果相同。"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 30,
    "total_tokens": 48
  }
}

status 常见值：

不要假设 output[0].content[0] 永远是文本。output 还可能包含推理项、函数调用、Web Search 调用、文件搜索调用或图片生成调用，应根据每个元素的 type 分支处理。

流式请求示例

复制成功⧉
curl -N -X POST "https://router.253.com/v1/responses" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-name",
    "input": "写一段 50 字以内的产品介绍。",
    "stream": true
  }'

流式响应由带 type 的事件组成，常见事件包括：

复制成功⧉
data: {"type":"response.created","response":{"id":"resp_example","status":"in_progress"}}

data: {"type":"response.output_item.added","output_index":0,"item":{"type":"message","role":"assistant"}}

data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"这是一款"}

data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"高效的智能助手。"}

data: {"type":"response.completed","response":{"id":"resp_example","status":"completed"}}

客户端应按照 type 处理事件，并通过 output_index、content_index、item_id 等字段组装完整输出。

工具调用示例

请求：

复制成功⧉
{
  "model": "your-model-name",
  "input": "查询杭州天气。",
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "查询指定城市天气",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          }
        },
        "required": [
          "city"
        ],
        "additionalProperties": false
      },
      "strict": true
    }
  ],
  "tool_choice": "auto"
}

模型可能在 output 中返回：

复制成功⧉
{
  "type": "function_call",
  "id": "fc_example",
  "call_id": "call_001",
  "name": "get_weather",
  "arguments": "{\"city\":\"杭州\"}"
}

执行函数后，可通过 previous_response_id 和 function_call_output 继续请求：

复制成功⧉
{
  "model": "your-model-name",
  "previous_response_id": "resp_example",
  "input": [
    {
      "type": "function_call_output",
      "call_id": "call_001",
      "output": "{\"temperature\":24,\"condition\":\"晴\"}"
    }
  ]
}

---

Anthropic Claude Messages

接口信息

• 接口路径：POST https://router.253.com/v1/messages
• 认证方式：API Key
• 响应格式：application/json

用于以 Anthropic Messages API 格式调用 Claude 或其他支持该协议的模型。

请求头

推荐使用 Anthropic 风格：

复制成功⧉
x-api-key: sk-xxxxxxxxxxxxxxxx
anthropic-version: 2023-06-01
Content-Type: application/json

也可以使用 Bearer Token：

复制成功⧉
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
anthropic-version: 2023-06-01
Content-Type: application/json

请求参数

messages 结构

常见内容块：

基础请求示例

复制成功⧉
curl -X POST "https://router.253.com/v1/messages" \
  -H "x-api-key: sk-xxxxxxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-name",
    "system": "你是一个简洁、准确的助手。",
    "messages": [
      {
        "role": "user",
        "content": "用三句话介绍杭州。"
      }
    ],
    "max_tokens": 500
  }'

非流式响应示例

复制成功⧉
{
  "id": "msg_example",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "杭州是浙江省省会，以西湖和深厚的人文历史闻名。这里兼具数字经济活力与江南山水气质。龙井茶、灵隐寺和京杭大运河也是城市的重要名片。"
    }
  ],
  "model": "your-model-name",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 25,
    "output_tokens": 48,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

stop_reason 常见值：

流式请求示例

复制成功⧉
curl -N -X POST "https://router.253.com/v1/messages" \
  -H "x-api-key: sk-xxxxxxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-name",
    "messages": [
      {"role": "user", "content": "写一句关于秋天的话。"}
    ],
    "max_tokens": 200,
    "stream": true
  }'

常见 SSE 事件顺序：

复制成功⧉
event: message_start
data: {"type":"message_start","message":{"id":"msg_example","type":"message","role":"assistant","content":[],"model":"your-model-name"}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"秋风掠过树梢，"}}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}}

event: message_stop
data: {"type":"message_stop"}

工具调用示例

请求：

复制成功⧉
{
  "model": "your-model-name",
  "messages": [
    {
      "role": "user",
      "content": "查询杭州天气。"
    }
  ],
  "max_tokens": 500,
  "tools": [
    {
      "name": "get_weather",
      "description": "查询指定城市天气",
      "input_schema": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          }
        },
        "required": [
          "city"
        ]
      }
    }
  ]
}

模型可能返回：

复制成功⧉
{
  "id": "msg_example",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_001",
      "name": "get_weather",
      "input": {
        "city": "杭州"
      }
    }
  ],
  "stop_reason": "tool_use"
}

执行工具后，将结果作为 tool_result 内容块再次提交：

复制成功⧉
{
  "model": "your-model-name",
  "messages": [
    {
      "role": "user",
      "content": "查询杭州天气。"
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "tool_use",
          "id": "toolu_001",
          "name": "get_weather",
          "input": {
            "city": "杭州"
          }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_001",
          "content": "{\"temperature\":24,\"condition\":\"晴\"}"
        }
      ]
    }
  ],
  "max_tokens": 500
}

---

错误响应

OpenAI 格式错误

/v1/chat/completions 和 /v1/responses 通常返回 OpenAI 兼容错误：

复制成功⧉
{
  "error": {
    "message": "model is required (request id: xxxxxxxx)",
    "type": "new_api_error",
    "param": "",
    "code": "invalid_request"
  }
}

Claude 格式错误

/v1/messages 通常返回 Claude 兼容错误：

复制成功⧉
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "field messages is required (request id: xxxxxxxx)"
  }
}

常见 HTTP 状态码

建议记录错误响应中的 request id，以便服务端检索对应日志。

---

查询用户余额/当前APIKey余额

接口信息

• 接口路径：GET https://router.253.com/v1/me/balance
• 认证方式：API Key
• 请求格式：无请求体
• 响应格式：application/json
• 用途：查询当前 API Key 所属用户的钱包余额。

认证

请求头必须携带 Authorization：

复制成功⧉
Authorization: Bearer sk-xxxxxxxxxxxxxxxx

说明：

• 支持 Bearer <API_KEY> 格式。
• 该接口是只读认证接口。
• 已耗尽额度或已过期的令牌仍可查询余额。
• 已禁用的令牌不可查询。
• 所属用户被封禁时不可查询。
• 该接口最小调用间隔为5分钟

请求参数

Header

Query 参数

Body 参数

无。

成功响应

HTTP 状态码

200 OK

响应字段

响应示例

复制成功⧉
{
  "success": true,
  "message": "",
  "data": {
    "balance": 3.6,
    "currency": "CNY"
  }
}

错误响应

未提供 API Key

HTTP 状态码：401 Unauthorized

复制成功⧉
{
  "success": false,
  "message": "token is not provided"
}

API Key 无效

HTTP 状态码：401 Unauthorized

复制成功⧉
{
  "success": false,
  "message": "invalid token"
}

API Key 已禁用

HTTP 状态码：401 Unauthorized

复制成功⧉
{
  "success": false,
  "message": "token status is unavailable"
}

用户被封禁

HTTP 状态码：403 Forbidden

复制成功⧉
{
  "success": false,
  "message": "user is banned"
}