Claude Messages

x-api-key string Required

Your BeatAPI key. Authorization: Bearer <BEATAPI_API_KEY> is also accepted.

model string Required

The exact model ID.

Allowed values: claude-fable-5-1, claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5

• Older IDs that still work (claude-opus-5, claude-sonnet-5, claude-haiku-4-5-20251001) are on Legacy models.
• Call GET /v1/models with your key to confirm which models are enabled for it.

max_tokens integer Required

Upper bound on the generated tokens, thinking included.

• Always send it. If it is missing or 0, a default limit is applied, and that default may be lower than you expect.
• The largest accepted value is 1,073,741,823; a larger value is 400 bad_request. Keep it at or below the max output of the model in the table above.
• max_tokens is also used to estimate how much balance a request needs. A very large value can be refused with 402 insufficient_credits even when the real output would be small. Set it to what you need.

messages object[] Required

The conversation, oldest message first. Each message has a role (user or assistant) and content. content is a string, or an array of content blocks.

• Block types you will use: text, image (base64 or URL source), tool_use (in an assistant message), and tool_result (in a user message).
• An empty or missing messages array is 400 bad_request.

Example

[
  {
    "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[] Optional

System prompt. A string, or an array of text blocks. Put cache_control on a block to cache a long, stable prefix.

Example

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

stream boolean OptionalDefault: false

Return the answer as server-sent events. See the Streaming section below.

Default: false

stop_sequences string[] Optional

Custom strings that stop generation. The response then has stop_reason: "stop_sequence".

tools object[] Optional

Tools the model may call. Each has a name, a description and an input_schema (JSON Schema). When the model calls one, the answer has stop_reason: "tool_use"; run the tool and return the result in a following tool_result block.

Example

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

tool_choice object Optional

Whether and how the model must use tools.

Allowed values: {"type":"auto"}, {"type":"any"}, {"type":"tool","name":"..."}, {"type":"none"}

• auto lets the model decide, any forces some tool, tool forces the named tool, none forbids tools.

Example

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

thinking object Optional

Extended thinking. Set type to turn it on or off. Thinking tokens count toward max_tokens and are billed as output tokens.

Allowed values: adaptive, enabled, disabled

• thinking.type is one of the values above. enabled takes thinking.budget_tokens (an integer of at least 1,024, below max_tokens).
• thinking.display is summarized or omitted. Newer models may return no thinking text unless you ask for summarized.
• Set the depth of adaptive thinking with output_config.effort.

Per model

• claude-fable-5-1: Use {"type":"adaptive"} and set depth with output_config.effort; budget_tokens is rejected.
• claude-opus-5-5: Use {"type":"adaptive"} and set depth with output_config.effort; budget_tokens is rejected.
• claude-sonnet-5-5: Use {"type":"adaptive"} and set depth with output_config.effort; budget_tokens is rejected.

Example

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

output_config.effort string Optional

How much reasoning the model does. Start with high, then evaluate one level lower and higher on your own workload.

Allowed values: low, medium, high, xhigh, max

cache_control object Optional

Prompt caching. Put it on a system, messages or tools block to cache everything up to that block, or at the top level of the request. ttl is 5m (default) or 1h.

Allowed values: {"type":"ephemeral"}

• Cache reads, 5-minute cache writes and 1-hour cache writes are metered separately; a cached prefix is charged as a cache read, not as fresh input.
• The cache hit counts are in usage.cache_read_input_tokens and usage.cache_creation_input_tokens.

Example

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