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

API 参考

Base URL 与认证

所有请求使用统一 Base URL 和 Bearer API Key。

统一请求约定 ​

所有公开兼容端点都从以下 Base URL 开始：

https://suoxie.codes/v1

完整 URL = Base URL + 端点路径。例如 Responses 的完整地址是 https://suoxie.codes/v1/responses。如果 SDK 要求填写“Base URL”，只填到 /v1；如果它要求填写“完整端点”，再包含 /responses。

粘贴前先分清三种值 ​

Base URL 用于识别服务，端点用于识别某个操作，API Key 用于识别调用方。不要把完整端点填入会自行追加路径的字段，也不要把 Key 填入模型、Provider 或 Base URL 字段。

字段应填写的值常见错误
Base URLhttps://suoxie.codes/v1客户端会自动追加 /v1，却又填成 /v1/v1
端点路径例如 /models 或 /responses把端点路径当作 Base URL
API Key控制台创建的完整值在只要求 Key 的字段额外写入 Bearer

认证头 ​

请求使用 Bearer 认证，Key 放在 HTTP Header，不放在查询参数中：

http
Authorization: Bearer <API_KEY>
Content-Type: application/json

Bearer 与 Key 之间只有一个空格。Content-Type 适用于 JSON 请求；没有请求体的 GET /v1/models 可以省略。

最小认证检查 ​

bash
read -rsp "API key: " SUOXIE_API_KEY
echo
export SUOXIE_API_KEY
curl --fail-with-body --include https://suoxie.codes/v1/models \
  -H "Authorization: Bearer $SUOXIE_API_KEY"
unset SUOXIE_API_KEY

成功时返回 HTTP 200，并包含 object: "list" 与 data：

json
{
  "object": "list",
  "data": []
}

data 的实际内容由当前 Key 和分组决定。空数组不代表认证失败，但表示当前没有可用于下一步的模型，需要检查分组或可用状态。

不要这样传 Key ​

以下方式不安全或不再支持：

text
https://suoxie.codes/v1/models?api_key=<API_KEY>
https://suoxie.codes/v1/models?key=<API_KEY>

查询参数会进入浏览器历史、代理日志和分析系统。后端会拒绝查询参数中的 API Key，请始终使用 Authorization Header。

环境变量 ​

Windows PowerShell：

powershell
$secureKey = Read-Host "API key" -AsSecureString
$credential = [System.Net.NetworkCredential]::new("", $secureKey)
$env:SUOXIE_API_KEY = $credential.Password
Remove-Variable secureKey, credential
curl.exe --fail-with-body https://suoxie.codes/v1/models `
  -H "Authorization: Bearer $env:SUOXIE_API_KEY"
Remove-Item Env:SUOXIE_API_KEY

macOS / Linux：

bash
read -rsp "API key: " SUOXIE_API_KEY
echo
export SUOXIE_API_KEY
curl --fail-with-body https://suoxie.codes/v1/models \
  -H "Authorization: Bearer $SUOXIE_API_KEY"
unset SUOXIE_API_KEY

隐藏输入不会把 Key 值写入交互式命令历史；环境变量在请求期间仍存在于当前进程中，所以只使用专用、可撤销且有限额的 Key，并在完成后立即清理。生产服务应使用部署平台的密钥管理器。不要在浏览器前端代码、公开仓库或容器镜像中写死 Key。

状态码 ​

状态码含义下一项检查
400请求格式或不支持的传参方式JSON、Header、是否把 Key 放进查询参数
401未通过认证Bearer 格式、Key 完整性、状态和有效期
403已识别但无权限账户、IP、分组和模型/图像权限
404路径或功能不可用是否重复 /v1、端点是否对当前平台开放
429额度、速率或并发受限Retry-After、余额、Key 配额和并发

请求追踪 ​

响应头可能包含 X-Request-ID 和 X-Client-Request-ID。排错时保留这些 ID、北京时间、端点和状态码，不要保留 Authorization 头。调用方也可以发送不含个人信息和密钥的 X-Client-Request-ID，便于关联自己的日志。

若模型列表检查没有得到 HTTP 200，暂时不要配置第三方客户端。先根据上方状态码或常见错误解决问题，否则客户端会为排查增加新的变量。

下一步 ​

认证通过后，使用模型选择取得精确 ID，再在 cURL 完成可复制的基线请求，之后再配置 Responses API 或其他客户端。