概览

端点

所有端点都位于同一个 base URL 之下，并通过 HTTPS 提供服务。

https://api.shannon-ai.com

产生文本的三个端点连接到相同的模型。请选择与你的代码已在使用的格式相符的那一个。

请求基础

• 每个 POST 的请求体都是一个 JSON 对象，最大 32 MiB。
• API 不认识的字段不会引起错误，也没有任何效果。为其他提供方编写的请求不会因多出一个字段而失败。
• 已知字段的 JSON 类型有误，或缺少必需字段，会得到 422。请求体不是有效的 JSON 会得到 400。
• model 是模型与定价中的 id 之一。大小写无关。

回复是 JSON；如果请求将 stream 设为 true，则是服务器发送事件（server-sent events）流。每个端点以各自的格式作答。每个回复都带有标头 x-request-id。

请求要通过的检查

请求在模型运行之前，会按固定顺序检查。第一个失败的检查就会给出答复，因此 401 还不能说明请求体的任何情况。

错误结构

错误是一个 JSON 对象，其 error 包含 type 和 message。/v1/messages 按 Anthropic SDK 期望的方式包装它；其他所有路径使用 OpenAI 的结构。

{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

• 请读取 type 和 message。code 和 param 只出现在部分错误中：请将它们视为可选。param 始终为 null。
• 流开始之后，状态码已经是 200。此后的失败会以流内错误帧的形式到达。
• 每个错误回复都带有 x-request-id 请求头。

错误处理

账单与余额

• 每个账户只有一份余额，聊天和 API 共用：先消耗当日计划额度，再消耗已购买的信用额度。API 没有自己的配额。
• 请求会预留其输出预算（max_tokens，默认 4,096），然后按实际用掉的 tokens、以模型的价格计费。
• 每个回复都在 usage 中报告其 token 计数。密钥与用量页面显示余额以及每个请求的花费。
• 每个请求一视同仁。对请求速率的唯一限制是限流保护：每个账户每分钟 120 个请求。并行发送的请求会排队等待。

限制与余额 模型与定价 密钥与用量

取决于模型的字段

所有模型接受相同的请求。少数字段只对部分模型生效；表中注明了适用范围。各端点页面列出了每个字段。

Chat Completions

从 OpenAI SDK 迁移

• 将 base URL 设为 https://api.shannon-ai.com/v1，并将密钥设为你的 Shannon 密钥。这样 Chat Completions 和 Responses 调用就能直接配合 SDK 使用。
• model 必须是 Shannon id。其他提供方的模型名称（如 gpt-4o）会得到 400 和 unknown model。
• 推理内容放在单独的字段中：与 content 并列的 reasoning_content，在消息和流的 delta 中皆然。
• 流的最后一个数据块始终携带 usage，同时带有 finish_reason。
• 流中的工具调用会作为一个数据块到达，其中包含完整的 arguments 字符串。
• 回复只有一个 choice。
• 上表中没有的 OpenAI API 路径（如 /v1/embeddings）会得到 404。

从 Anthropic SDK 迁移

• 将 base URL 设为 https://api.shannon-ai.com（不带 /v1），并将密钥设为你的 Shannon 密钥。SDK 会以 x-api-key 发送它。
• model 必须是 Shannon id。
• 在此 API 上，max_tokens 是可选的。默认值为 4,096。
• 回复包含类型为 thinking、text 和 tool_use 的内容块。第一个块并不总是文本：请按 type 选取块。
• stop_reason 为 end_turn 或 tool_use。Shannon 模型的流也可能以 max_tokens 结束。
• anthropic-version 和 anthropic-beta 会被接受，因此 SDK 无需修改即可工作。请求并不需要它们。
• /v1/messages 上的错误具有 Anthropic 的结构：{"type": "error", "error": {…}}。

使用这些格式的编程工具，设置方法相同：base URL、密钥，以及作为模型的 Shannon id。 CLI 编程工具