AI Knowledge

Claude API 入門 — Messages API の基本

Anthropic SDK を使った最初のリクエストから、システムプロンプト、ストリーミング、思考（thinking）、プロンプトキャッシュ、エラー処理までの要点。

公開 読了 約6分
#Claude#API#TypeScript#SDK#開発

#概要

Claude の機能はほぼすべて POST /v1/messages（Messages API）に集約されている。ツール利用、構造化出力、画像入力、思考機能はすべてこの1エンドポイントのパラメータ。

  • 公式 SDK: Python、TypeScript、Java、Go、Ruby、C#、PHP
  • 認証: 環境変数 ANTHROPIC_API_KEY（または ant auth login によるプロファイル）

#セットアップ（TypeScript）

npm install @anthropic-ai/sdk
export ANTHROPIC_API_KEY=sk-ant-...

#最初のリクエスト

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic(); // 環境変数から認証情報を読む

const response = await client.messages.create({
  model: "claude-opus-5",
  max_tokens: 16000,
  system: "あなたは簡潔に答えるアシスタントです。",
  messages: [{ role: "user", content: "日本で一番高い山は？" }],
});

for (const block of response.content) {
  if (block.type === "text") console.log(block.text);
}

ポイント:

  • content は ブロックの配列（text / tool_use / thinking など）。type で分岐する
  • max_tokens は出力上限。小さすぎると途中で切れる（stop_reason: "max_tokens"）
  • API は ステートレス。会話を続けるには履歴をすべて送り直す

#会話履歴

const messages: Anthropic.MessageParam[] = [
  { role: "user", content: "私の名前は山田です。" },
  { role: "assistant", content: "山田さん、はじめまして。" },
  { role: "user", content: "私の名前は？" },
];

#ストリーミング

長い出力や高い max_tokens を使うときはストリーミングにする（タイムアウト回避と体感速度の改善）。

const stream = client.messages.stream({
  model: "claude-opus-5",
  max_tokens: 64000,
  messages: [{ role: "user", content: "TypeScriptの型システムを解説して" }],
});

stream.on("text", (text) => process.stdout.write(text));
const final = await stream.finalMessage();
console.log("\n", final.usage);

#思考（thinking）と effort

最近のモデルは回答前に思考する。adaptive を指定すると必要に応じて思考の深さをモデルが判断する。深さは output_config.effort で調整。

const response = await client.messages.create({
  model: "claude-opus-5",
  max_tokens: 16000,
  thinking: { type: "adaptive", display: "summarized" },
  output_config: { effort: "high" }, // low | medium | high | xhigh | max
  messages: [{ role: "user", content: "この設計のトレードオフを分析して…" }],
});

メモ

旧来の budget_tokens 指定は新しいモデルではエラーになる。thinking: { type: "adaptive" } + effort に置き換える。

#プロンプトキャッシュ

同じ前置き（長いシステムプロンプト、資料、ツール定義）を繰り返し送る場合、キャッシュで入力コストを大幅に下げられる。前方一致 なので、変わらない内容を先頭に、変わる内容を後ろに置く。

const response = await client.messages.create({
  model: "claude-opus-5",
  max_tokens: 16000,
  system: [
    {
      type: "text",
      text: longDocument, // 変わらない大きな資料
      cache_control: { type: "ephemeral" },
    },
  ],
  messages: [{ role: "user", content: "要点を3つ挙げて" }],
});

console.log(response.usage.cache_read_input_tokens); // 2回目以降にここが増えていれば効いている

#構造化出力（JSON）

後続処理で使う場合は、プロンプトで「JSONで返して」と頼むより、output_config.format で JSON Schema を指定する方が確実。SDK の messages.parse() はスキーマ検証まで行ってくれる。

#エラー処理

SDK の型付き例外を使い、リトライすべきもの（429、5xx、ネットワーク）とそうでないもの（400、404）を分ける。

try {
  await client.messages.create({ /* ... */ });
} catch (err) {
  if (err instanceof Anthropic.RateLimitError) {
    // 待って再試行
  } else if (err instanceof Anthropic.BadRequestError) {
    // リクエストを修正
  } else if (err instanceof Anthropic.APIError) {
    console.error(err.status, err.message);
  }
}

SDK は既定で2回自動リトライする。

#stop_reason を必ず見る

値意味
end_turn正常終了
max_tokens上限で切れた → max_tokens を増やすかストリーミング
tool_useツール呼び出し要求 → 実行して結果を返す
refusal安全上の理由で拒否 → stop_details を確認

#コストの見方

  • usage.input_tokens / output_tokens / cache_read_input_tokens で毎回確認
  • 出力は入力より単価が高い
  • 即時性不要な大量処理は バッチAPI（割引）を使う

#まとめ

  • すべては Messages API。content はブロック配列、API はステートレス
  • 長い出力はストリーミング、難しいタスクは thinking + effort
  • 繰り返す前置きはキャッシュ、後続処理は構造化出力
  • stop_reason と usage を常にログに残す

関連記事