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

开始使用

五分钟快速开始

按七个步骤完成注册、密钥和第一次请求。

七步完成接入 ​

准备一台能打开控制台并运行终端的电脑。主路径是：登录 -> 可选的简短兑换 -> 创建 API Key -> 选择分组 -> GET /v1/models -> Windows PowerShell curl.exe 基线 -> 选择接入方式 -> 第一次 Responses 请求 -> 查看用量。

本文有两个占位符：<API_KEY> 要替换为你创建的完整 Key；<MODEL> 要替换为 /v1/models 返回的一个完整模型 ID。替换时不要输入尖括号，也不要保留示例值。

下面的概念图概括同一条主路径：登录 -> 创建专用 Key -> 读取实时模型列表 -> 建立 cURL 基线 -> 发送第一次请求并核对用量。即使图片无法加载，也按这段文字和下方七步继续。

零基础 API 主路径：登录、创建专用 Key、读取模型列表、建立 cURL 基线、发送请求并核对用量
零基础 API 主路径。该图只解释稳定顺序，不描绘或替代当前生产控制台界面。

1. 注册并登录 ​

  1. 打开 梭子蟹首页，确认地址栏是 HTTPS 和正式域名。
  2. 已有账户就登录；新用户按页面提示注册并完成验证。
  3. 登录后打开控制台，确认能看到自己的账户和“API 密钥”入口。

成功标志： 刷新控制台后仍保持登录。失败时先检查 Cookie、系统时间和验证是否完成。验证码、密码和会话链接不得发给他人。下一步查看注册与登录，或继续准备余额。

2. 获取当前兑换码 ​

只有需要充值时才准备兑换码，并且只从当前站点公布的正式渠道获取。不要使用搜索结果、旧截图或他人转发的历史链接，也不要公开完整兑换码。

成功标志： 兑换码未使用、未过期且来源可确认。已有可用余额或有效订阅可以跳过第 2、3 步，直接创建 API Key。

3. 兑换到钱包 ​

  1. 打开 https://suoxie.codes/redeem，先记下兑换前余额。
  2. 粘贴兑换码，核对首尾字符，只提交一次。
  3. 刷新页面，同时核对兑换记录与余额变化。

成功标志： 记录和余额一致。若出现 403 或结果不明确，先不要重复提交，按兑换码与钱包核对账户、记录和余额。反馈时只提供兑换码末四位。

4. 创建 API Key ​

  1. 打开 https://suoxie.codes/keys，创建一把用途明确的专用 Key。
  2. 为 Key 选择与目标模型和能力匹配的分组；不确定时先使用最小测试额度。
  3. 立即把完整 Key 保存到密码管理器或密钥存储，关闭展示窗口。

成功标志： 列表出现名称、分组和状态正确的新 Key。若创建按钮不可用，先检查余额或订阅、账户状态和分组。完整 Key 不写入聊天、截图、日志或 Git；丢失后重新创建，不尝试找回。详见创建 API Key和选择分组。

5. 准备连接信息 ​

准备 Base URL https://suoxie.codes/v1、完整 API Key 和模型 ID。先在 Windows PowerShell 设置 Key，再获取当前 Key 真正可用的模型列表：

powershell
$env:SUOXIE_API_KEY = '<API_KEY>'
curl.exe --fail-with-body --show-error `
  https://suoxie.codes/v1/models `
  -H "Authorization: Bearer $env:SUOXIE_API_KEY"

macOS / Linux 等价命令：

bash
export SUOXIE_API_KEY='<API_KEY>'
curl --fail-with-body --show-error \
  https://suoxie.codes/v1/models \
  -H "Authorization: Bearer $SUOXIE_API_KEY"

从返回的 data 中选择一个 id，再设置模型变量：

powershell
$env:SUOXIE_MODEL = '<MODEL>'
bash
export SUOXIE_MODEL='<MODEL>'

成功标志： HTTP 200 且 data 至少有一个模型。失败时先检查 Bearer 格式、Key 状态和分组；模型必须来自同一把 Key 的实时返回。终端变量仍属于敏感信息，用完后关闭终端，不把它们写入仓库。

6. 生成客户端配置 ​

先用上一步的 Windows PowerShell curl.exe 结果作为基线，再按选择接入方式分类：直接 API 适合自己写程序，普通客户端适合日常对话或开发，CC Switch 与 Cockpit Tools 属于辅助管理工具，不是普通 API 客户端。

  1. 选择一种路径，只填写已经验证的 Base URL、Key 和模型 ID。
  2. 完全重启客户端，再发送一条短测试消息。
  3. cURL 成功而客户端失败时，先检查客户端的 Base URL、Provider、模型缓存和代理。

成功标志： 客户端返回正常文字。不要把 Key 粘贴到插件反馈、公开配置或截图。下一步用 Responses API 做协议基线。

7. 发送第一次请求 ​

Windows PowerShell：

powershell
$body = @{
  model = $env:SUOXIE_MODEL
  input = 'Reply with OK'
  store = $false
} | ConvertTo-Json -Compress
$body | curl.exe --fail-with-body --show-error `
  https://suoxie.codes/v1/responses `
  -H "Authorization: Bearer $env:SUOXIE_API_KEY" `
  -H "Content-Type: application/json" `
  --data-binary '@-'

macOS / Linux：

bash
curl --fail-with-body --show-error \
  https://suoxie.codes/v1/responses \
  -H "Authorization: Bearer $SUOXIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$SUOXIE_MODEL\",\"input\":\"Reply with OK\",\"store\":false}"

成功标志： HTTP 200、status 为 completed，并能在 output 中找到回复。失败时先重新执行 GET /v1/models，记录状态码、时间和实际出现的请求 ID，不要提供完整 Key。成功后立即到 Key 用量核对模型、端点、Token 和费用。

第一次失败时怎么做 ​

  1. 回到 GET /v1/models，区分认证/分组问题与请求体问题。
  2. 每次只改变一个变量；请求中断时先查用量，再决定是否重提。
  3. 按常见错误检查，仍失败再提交脱敏支持信息。

下一步 ​

直连程序继续读 Responses API；普通客户端进入 Codex、Cursor或其他对应配置页；上线前完成上线前检查。