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

排错

上线前检查

上线前逐项核对地址、密钥、模型和超时。

先建立最小基线 ​

上线检查的目标不是“配置看起来正确”，而是证明同一套生产配置能完成一次可追踪的最小请求。本地或预发布演练使用专用、可撤销、有限额的测试 Key，并准备一个从该 Key 实时列表取得的模型，以及不会包含用户数据的短输入。生产 Key 只允许通过密钥管理器在受控部署环境中执行最终检查，绝不能复制到个人终端。

下面所有 <API_KEY> 和 <MODEL> 都必须替换。不要把真实值写进文档、脚本仓库或前端构建变量。

最短安全路径 ​

新接入时，不要一开始就启用流式输出、工具、图片或生产流量。先在本地或预发布环境中使用专用测试 Key，逐项证明这条路径：

  1. 部署环境能够调用 GET /v1/models。
  2. 从返回中复制的一个精确模型 ID，能完成一次短的 /v1/responses 请求。
  3. 操作人员能够找到对应的用量记录和脱敏后的请求证据。

本页是新手基线的生产版本。若要在本地执行一套可直接复制的首次请求，请从 cURL 开始；若该请求失败，请先按常见错误排查，不要同时修改多项设置。演练通过后，再由密钥管理器注入生产 Key，在受控部署环境中重复最终的模型列表和最小请求检查；不要把生产 Key 移到演练环境。

1. 地址与网络 ​

  • Base URL 使用 https://suoxie.codes/v1，客户端最终请求中只出现一次 /v1。
  • 使用 HTTPS，不关闭证书校验，不在生产使用 cURL 的 -k。
  • 生产主机能够解析域名并访问 443 端口，系统时间准确，CA 证书处于受支持状态。
  • 如果使用企业代理，确认它不会删除 Authorization、Content-Type、Location 或 Retry-After。
  • 为连接、读取和整个请求分别设置合理的截止时间；超时不能无限大。

先从部署环境运行：

bash
curl --fail-with-body --show-error --connect-timeout 10 --max-time 30 \
  https://suoxie.codes/v1/models \
  -H "Authorization: Bearer <API_KEY>"

通过条件： DNS、TLS 和认证均成功，返回 HTTP 200，而不是只在开发电脑上成功。

2. Key、账户与分组 ​

  • Key 已启用、未过期且属于目标环境；测试、预览和生产分别使用独立 Key。
  • 余额、订阅或 Key 配额足以覆盖正常峰值和有限重试。
  • Key 绑定的分组允许目标模型及所需能力，例如 Responses、Messages 或图片。
  • Key 只保存在部署平台的密钥管理中，不进入 Git、镜像、前端代码、日志或报错页面。
  • 已定义轮换和紧急撤销步骤，并能在不停止所有服务的情况下更换单把 Key。

3. 模型与协议 ​

  1. 使用生产 Key 调用 GET /v1/models。
  2. 从当前 data[].id 复制完整模型 ID，不使用截图中的旧名称。
  3. 确认客户端协议与端点匹配：Responses、Anthropic Messages 或 Chat Completions。
  4. 对文本、流式、工具、图片等每一种实际使用的能力分别做最小验证。
  5. 确认客户端没有自动添加额外 /v1、模型前缀或供应商默认域名。

模型出现在列表中是必要条件，但不等于所有高级能力都已验证。

4. 最小请求与成功判定 ​

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

同时满足以下条件才算通过：

  • HTTP 状态为 200，响应可以被 JSON 解析。
  • 响应 status 和输出内容符合接口约定，而不是空白错误页或代理 HTML。
  • 控制台 /usage 能找到相同时间、Key、模型和端点的记录。
  • 日志中没有完整 Authorization 头、完整 Key 或业务输入。

如果 GET /v1/models 已成功但本请求失败，网络和 Key 已经得到验证。请保持相同的 Key 与模型，检查端点、JSON 请求体和能力权限，不要立刻轮换凭据。

5. 超时、重试与并发 ​

  • 只对可恢复错误做有限重试，例如连接中断、429 和部分 5xx；400、401、403 不应原样重试。
  • 429 优先遵守 Retry-After，否则使用带随机抖动和上限的退避。
  • 设置最大尝试次数和总截止时间，防止 SDK、网关和业务层叠加重试形成请求风暴。
  • 对可能产生费用或副作用的请求，超时后先查用量/任务状态；不要假定“没收到响应就是没执行”。
  • 从小并发逐步压测，记录成功率、P95 延迟、429、5xx 和费用，再决定生产并发。

长耗时图片优先使用异步图像任务。异步轮询遵守 Retry-After，持久化 task_id，并在 completed 或 failed 后停止。

6. 解析、兼容与降级 ​

  • 客户端按字段和 type 解析响应，不依赖数组永远只有一个元素或字段顺序固定。
  • 能接受不认识的附加字段；对必需字段缺失给出可诊断错误。
  • 流式客户端能处理增量事件、正常结束、网络中断和部分输出。
  • 上游不可用时有清晰用户提示、队列或业务降级，而不是无限等待。
  • 将模型可用性变化视为运行时条件，上线前重新查询并准备受控切换方案。

7. 可观测性与安全 ​

至少记录时间、内部请求关联 ID、端点、模型、状态码、延迟、尝试次数和脱敏后的错误类型。不要记录完整 Key、完整提示、图片原件或完整模型输出，除非业务已取得授权并设置保留期限。

上线前确认：

  • 告警能覆盖认证失败突增、429、5xx、延迟、费用和余额异常。
  • 日志、指标和用量页使用相同的时区说明，能够关联同一次请求。
  • 支持人员知道如何撤销 Key、缩小影响范围和收集脱敏材料。
  • 关键配置有回滚版本，发布失败时不需要临时在服务器上手改。

发布前打勾 ​

  • [ ] 生产主机的 /v1/models 请求返回 200。
  • [ ] 模型 ID 来自生产 Key 的实时返回。
  • [ ] 每种实际使用的端点都完成了最小请求。
  • [ ] 用量和费用与小样本预期一致。
  • [ ] 超时、重试、并发和异步轮询都有明确上限。
  • [ ] 401、403、429、5xx 和网络中断已在预发布环境演练。
  • [ ] 日志与错误页面不泄露凭据或用户内容。
  • [ ] 监控、告警、轮换、撤销和回滚负责人明确。

下一步 ​

任何一项未通过都先停止放量，按常见错误修复后重新执行清单。仍无法定位时，使用联系支持中的模板提交脱敏报告。

清单通过不代表配置永久有效：Key、分组、模型、客户端协议、网络路径或发布配置变化后，都应再次完成模型列表和最小请求检查。