Claude Messages

x-api-key string 必需

你的 BeatAPI 密钥。也接受 Authorization: Bearer <BEATAPI_API_KEY>。

model string 必需

准确的模型 ID。

可选值：claude-fable-5-1, claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5

• 仍可调用的旧 ID（claude-opus-5、claude-sonnet-5、claude-haiku-4-5-20251001）见旧型号。
• 用你的密钥调用 GET /v1/models，确认该密钥已开通哪些模型。

max_tokens integer 必需

生成 token 数的上限，包含思考。

• 请始终显式传入。缺省或为 0 时会套用一个默认上限，这个默认值可能比你预期的小。
• 接受的最大值是 1,073,741,823，更大的值返回 400 bad_request。请保持在上表中该模型的最大输出以内。
• max_tokens 还用来估算请求需要的余额。过大的值即使实际输出很短，也可能被 402 insufficient_credits 拒绝。按实际需要设置。

messages object[] 必需

对话内容，最早的消息在前。每条消息有 role（user 或 assistant）和 content。content 可以是字符串，也可以是内容块数组。

• 常用的块类型：text、image（base64 或 URL 来源）、tool_use（在 assistant 消息里）和 tool_result（在 user 消息里）。
• messages 为空或缺失会返回 400 bad_request。

示例

[
  {
    "role": "user",
    "content": [
      { "type": "text", "text": "What is in this image?" },
      { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "<base64>" } }
    ]
  }
]

system string | object[] 可选

系统提示词。可以是字符串，也可以是 text 块数组。在块上加 cache_control，可以缓存一段较长且稳定的前缀。

示例

[
  {
    "type": "text",
    "text": "<long, stable instructions>",
    "cache_control": { "type": "ephemeral" }
  }
]

stream boolean 可选默认值: false

以服务端推送事件的形式返回答案。见下文的流式输出一节。

默认值：false

stop_sequences string[] 可选

遇到这些自定义字符串就停止生成。此时响应里 stop_reason 为 "stop_sequence"。

tools object[] 可选

模型可以调用的工具。每个工具有 name、description 和 input_schema（JSON Schema）。模型调用工具时，响应里 stop_reason 为 "tool_use"；运行工具后，在下一条消息的 tool_result 块里返回结果。

示例

[
  {
    "name": "get_weather",
    "description": "Get the current weather for a city.",
    "input_schema": {
      "type": "object",
      "properties": { "city": { "type": "string" } },
      "required": ["city"]
    }
  }
]

tool_choice object 可选

是否以及如何必须使用 tools。

可选值：{"type":"auto"}, {"type":"any"}, {"type":"tool","name":"..."}, {"type":"none"}

• auto 由模型决定，any 强制使用某个工具，tool 强制使用指定名称的工具，none 禁止使用工具。

示例

{ "type": "auto" }
{ "type": "tool", "name": "get_weather" }

thinking object 可选

扩展思考。用 type 打开或关闭。思考 token 计入 max_tokens，并按输出 token 计费。

可选值：adaptive, enabled, disabled

• thinking.type 取上面的值之一。enabled 需要同时传 thinking.budget_tokens（整数，至少 1,024，且小于 max_tokens）。
• thinking.display 取 summarized 或 omitted。较新的模型除非你要求 summarized，否则可能不返回思考文本。
• 自适应思考的深度用 output_config.effort 设置。

各模型说明

• claude-fable-5-1：用 {"type":"adaptive"}，深度用 output_config.effort 设置；budget_tokens 会被拒绝。
• claude-opus-5-5：用 {"type":"adaptive"}，深度用 output_config.effort 设置；budget_tokens 会被拒绝。
• claude-sonnet-5-5：用 {"type":"adaptive"}，深度用 output_config.effort 设置；budget_tokens 会被拒绝。

示例

{
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "high" }
}

output_config.effort string 可选

模型的推理强度。建议从 high 开始，再在你自己的负载上评估低一档和高一档的效果。

可选值：low, medium, high, xhigh, max

cache_control object 可选

提示缓存。放在 system、messages 或 tools 的块上，缓存到该块为止的全部内容；也可以放在请求顶层。ttl 取 5m（默认）或 1h。

可选值：{"type":"ephemeral"}

• 缓存读取、5 分钟缓存写入和 1 小时缓存写入分别计量；命中缓存的前缀按缓存读取收费，不按新输入收费。
• 命中情况见 usage.cache_read_input_tokens 和 usage.cache_creation_input_tokens。

示例

{ "type": "ephemeral" }
{ "type": "ephemeral", "ttl": "1h" }