梭子蟹API 文档
用量
立即开始
Base URLhttps://suoxie.codes/v1

API 参考

Responses API

发送文本、多模态和工具调用请求。

Responses API ​

新项目优先使用 Responses API 处理文本、多模态输入和工具调用。

POST /v1/responses

开始前准备 ​

  • 认证：Authorization: Bearer <API_KEY>
  • 模型：来自当前 Key 的 GET /v1/models
  • 内容类型：application/json

最小请求 ​

bash
curl --fail-with-body https://suoxie.codes/v1/responses \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model":"<MODEL>","input":"Reply with OK","store":false}'

常用请求字段 ​

字段类型必填说明
modelstring是/v1/models 返回的精确模型 ID
inputstring 或输入数组是用户输入；先用短字符串验证链路
storeboolean否调试和隐私敏感场景可显式设为 false
streamboolean否true 时使用流式事件；先完成非流式测试
toolsarray否工具定义；支持范围取决于模型和上游能力

未在本站稳定验证的高级字段应以当前模型能力和实际响应为准。不要一次加入多个高级参数。

成功响应 ​

json
{
  "id": "resp_example",
  "object": "response",
  "status": "completed",
  "model": "<MODEL>",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "OK"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 7,
    "output_tokens": 2,
    "total_tokens": 9
  }
}

ID、用量数值和 output 项会随请求变化。客户端不应依赖数组中永远只有一个 message；应按 type 读取支持的输出项。

如何判断完成 ​

  • HTTP 状态为 200。
  • 顶层 status 为 completed。
  • output 中出现可处理的消息或工具输出。
  • usage 可用于核对本次 Token，但最终费用以控制台用量记录为准。

流式请求 ​

确认非流式请求成功后，再把 stream 设为 true。流式响应是事件序列，不是一次性 JSON。调用方必须处理正常结束和 response.failed 等错误事件，并设置合理的连接空闲超时。

常见错误 ​

状态或现象处理
400检查 JSON、model、input 和字段类型
401回到 /v1/models 验证 Key 与 Bearer 头
403检查分组、模型和工具/图片权限
429读取 Retry-After，检查配额、余额和并发；退避后重试
5xx保存请求 ID，使用指数退避有限重试，不要无限循环

只对可重试失败进行有限次数重试。400、401、403 通常需要修改请求或权限，原样重试不会解决问题。

下一步 ​

迁移旧 SDK 时查看 Chat Completions。准备正式上线前阅读上线前检查与Key 用量。