模型 API 参考

本页说明常用接口的请求与响应结构。所有路径相对于本站 API 根地址；完整接入步骤见首次调用。

通用约定

以下 JSON 为最小结构示例，模型名和 ID 均需替换。可选字段是否受支持，取决于模型、渠道和协议转换路径。

模型列表

GET /v1/models

{
  "object": "list",
  "data": [
    { "id": "your-enabled-model", "object": "model" }
  ]
}

使用 data[].id 发起调用。GET /v1/models/{model} 可查询单个模型；附加字段与协议模式有关。列表可见性不保证当前生成请求一定成功。

Chat Completions

POST /v1/chat/completions

最小请求：

{
  "model": "your-enabled-model",
  "messages": [{ "role": "user", "content": "Hello!" }]
}

响应的核心字段：

{
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello!" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 10, "completion_tokens": 3, "total_tokens": 13 }
}

读取 choices[].message，并检查 finish_reason。工具调用可能返回 tool_calls；达到输出上限时内容可能不完整。流式改为读取 choices[].delta，详见流式响应、工具调用和结构化输出。

Responses

POST /v1/responses

{"model":"your-enabled-model","input":"Hello!"}

input 可为字符串或协议支持的内容项。简化响应：

{
  "id": "resp_example",
  "object": "response",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Hello!" }]
    }
  ]
}

遍历 output 中的 message 及 output_text 内容项，不要按 Chat 的 choices 解析。SDK 可能提供 output_text 便利属性。格式约束使用 text.format，流式使用命名事件。

background: true 和 GET /v1/responses/{response_id} 仅在支持该模式的任务插件路径下适用；普通 relay 返回的响应 ID 不保证可由本站检索。保留原始返回 ID，并使用对应协议的查询入口。

Anthropic Messages

POST /v1/messages

{
  "model": "your-messages-model",
  "max_tokens": 256,
  "messages": [{ "role": "user", "content": "Hello!" }]
}

max_tokens 为正整数输出上限，需符合模型及网关限制。兼容 Anthropic 客户端时，使用本站密钥填写 x-api-key，并按客户端协议发送 anthropic-version；直接 HTTP 调用也可使用本站支持的 Bearer 鉴权。

简化响应：

{
  "id": "msg_example",
  "type": "message",
  "role": "assistant",
  "content": [{ "type": "text", "text": "Hello!" }],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 10, "output_tokens": 3 }
}

按 content 块类型处理文本、工具等结果。/v1/messages/count_tokens 当前未启用。

Gemini

POST /v1beta/models/{model}:generateContent

{
  "contents": [
    { "role": "user", "parts": [{ "text": "Hello!" }] }
  ]
}

模型名位于路径中。简化响应：

{
  "candidates": [
    {
      "content": { "role": "model", "parts": [{ "text": "Hello!" }] },
      "finishReason": "STOP"
    }
  ]
}

读取 candidates 中的 content.parts，按类型处理。流式 action 为 streamGenerateContent，SSE 客户端通常使用 ?alt=sse。

鉴权可使用本站支持的 Bearer 或兼容客户端的 x-goog-api-key。优先使用请求头，避免密钥进入 URL 日志。countTokens 当前未实现。

媒体与任务

错误响应

错误可能由网关、上游或代理返回。OpenAI 兼容错误通常具有 error 对象，例如：

{
  "error": {
    "message": "Example error message",
    "type": "invalid_request_error",
    "code": "example_code"
  }
}

以上为结构示意，不是固定错误文案。Messages、Gemini 和插件接口可能使用各自格式；message、type、code 也不保证全部存在。

保留 HTTP 状态、协议错误字段和实际返回的请求标识。HTML 错误页通常需要进一步检查代理或接入地址。具体处理见调用失败排查。

能力边界与补充资料

文件管理、微调、图片 variations 和模型删除等占位接口不属于可用能力。上游完整字段应参考对应服务商官方协议，同时核对本站模型与渠道支持范围。

New API 官方 API 文档提供项目层面的补充参考，RouTok 服务范围以本站为准。