Claude APIをTypeScriptで使う方法｜Messages APIの最小実装

Claude APIをTypeScriptから使う最短ルートは、公式SDK @anthropic-ai/sdk を入れ、環境変数 ANTHROPIC_API_KEY を設定し、Messages APIの client.messages.create() を呼ぶ方法です。

Claude CodeとClaude APIは用途が異なります。Claude Codeはリポジトリ内の開発作業を支援する製品で、Claude APIは自作アプリやサーバーからモデルを呼ぶためのインターフェースです。

この記事では、型付きの最小プロジェクト、Messages API、systemとmessages、content block、エラーとrequest ID、ストリーミングへ広げる前の確認点を解説します。

情報確認日：2026年7月17日（日本時間）

結論：サーバー側TypeScriptからMessages APIを呼ぶ

claude-api-sample/
├── .gitignore
├── package-lock.json
├── package.json
├── src/
│   ├── config.ts
│   └── index.ts
└── tsconfig.json

TypeScriptプロジェクトを準備する

mkdir claude-api-sample
cd claude-api-sample
npm init -y
npm install @anthropic-ai/sdk
npm install -D typescript tsx @types/node
npm pkg set type=module
npm pkg set scripts.start="tsx src/index.ts"
npm pkg set scripts.typecheck="tsc --noEmit"

tsconfig.jsonを作ります。

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*.ts"]
}

APIキーを環境変数へ設定する

export ANTHROPIC_API_KEY="your_api_key_here"

node_modules/
.env
.env.*
!.env.example

ブラウザから直接Claude APIを呼ぶとキーが利用者へ見えるため、API呼び出しはサーバー側に置きます。秘密情報の扱いはAI APIキーの管理方法も参照してください。

Messages APIの最小コードを書く

モデル設定を分離する

src/config.tsを作ります。

export const MODEL =
  process.env.ANTHROPIC_MODEL || "claude-opus-4-8";

export const MAX_TOKENS = 300;

初期値は2026年7月17日時点の公式TypeScript SDK例を基準にしています。利用可能モデルは変わるため、環境変数で差し替えます。

messages.create()を呼ぶ

src/index.tsを作ります。

import Anthropic from "@anthropic-ai/sdk";
import { MAX_TOKENS, MODEL } from "./config.js";

if (!process.env.ANTHROPIC_API_KEY) {
  throw new Error("ANTHROPIC_API_KEY is not set");
}

const client = new Anthropic();

const message = await client.messages.create({
  model: MODEL,
  max_tokens: MAX_TOKENS,
  system:
    "あなたは初学者向けに説明するTypeScript講師です。",
  messages: [
    {
      role: "user",
      content:
        "TypeScriptの型注釈を60文字程度の日本語で説明してください。",
    },
  ],
});

const text = message.content
  .filter((block) => block.type === "text")
  .map((block) => block.text)
  .join("\n");

console.log(text);
console.log("request_id:", message._request_id);

npm run typecheck
npm start

system・messages・content blockの違い

Messages APIでは、systemロールのmessageを配列へ入れるのではなく、top-levelのsystemを使います。また、応答のcontentはtextだけとは限らないため、block typeを確認して処理します。

エラーとrequest IDを記録する

try {
  const message = await client.messages.create({
    model: MODEL,
    max_tokens: MAX_TOKENS,
    messages: [{ role: "user", content: "こんにちは" }],
  });

  console.log(message._request_id);
} catch (error) {
  if (error instanceof Anthropic.APIError) {
    console.error({
      status: error.status,
      name: error.name,
      requestId: error.request_id,
    });
  } else {
    throw error;
  }
}

request IDは、障害調査やサポート問い合わせで対象リクエストを識別する手掛かりです。利用者の本文やAPIキーをそのままログへ残さず、必要な識別子、status、処理時間、モデル、使用量を記録します。

ストリーミングへ広げる

長い応答を画面へ逐次表示する場合は、公式SDKのstreaming helperを使います。最初に非streaming版で認証、モデル、出力処理を確認してから置き換えます。

const stream = client.messages
  .stream({
    model: MODEL,
    max_tokens: 500,
    messages: [{ role: "user", content: "短い物語を書いて" }],
  })
  .on("text", (text) => process.stdout.write(text));

const finalMessage = await stream.finalMessage();
console.log("\nrequest_id:", finalMessage._request_id);

本番では切断、キャンセル、タイムアウト、途中まで表示した内容、再試行時の二重処理を設計します。

本番前チェックリスト

• APIキーをサーバー側のsecret管理へ置いた
• モデル名を設定で変更できる
• 入力長とmax_tokensへ上限を設けた
• content blockをtypeごとに処理する
• statusとrequest IDを秘密なしで記録する
• 429・5xxの再試行回数と待機を制限した
• 利用者ごとの認証、認可、予算上限を設けた
• モデル変更時に同じ評価入力を実行する

Claude Code自体の使い方を探している場合は、Claude Codeの使い方を参照してください。

まとめ

Claude APIは、公式TypeScript SDKとMessages APIから始めます。systemはtop-level、会話はmessages、応答は複数種類を持てるcontent blockとして扱います。

最小コードを型チェックした後、エラー、request ID、再試行、使用量、ストリーミングを段階的に追加してください。