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 必須

生成するトークン数の上限。思考も含みます。

• 必ず明示的に指定してください。省略または 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 でオンとオフを切り替えます。思考トークンは max_tokens に含まれ、出力トークンとして課金されます。

指定できる値：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 から始め、自分のワークロードで 1 段階下げた場合と上げた場合を比べてください。

指定できる値：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" }