Cloud AI エンジニア入門ガイド
Go back

12. Claudeの開発者向け入口

自社のアプリやサービスの中でClaudeを動かしたいとき、入口になるのがClaude APIです。

コード例が出てきます。プログラミングをしない人は、開発者はこういう単位で使っている、料金はこう決まる、という部分だけ拾って読み飛ばして構いません。

この章の全体像として、1つの窓口、ツール利用、コストの決まり方、呼ぶ場所の4つを番号順に並べ、料金の決まり方と抑えるための手立てが分かるようになることを示した図

シリーズ目次 ／ 前章: 11. コーディングツール Claude Code とは ／ 次章: 13. Claudeの安全性設計

Table of contents

Open Table of contents

この章のねらい

中心にあるのは1つのエンドポイント

Claude APIの基本は驚くほど単純です。POST /v1/messages という1つの入り口に、ほぼすべてが集まっています。ツール利用も、構造化された出力も、思考の設定も、この1つのリクエストの中で指定します。

アプリからClaude APIへ送信し、応答を受け取る流れと、ツール利用が挟まる場合の往復を示した図

やりとりの単位はメッセージの配列です。APIは状態を持たないので、会話の履歴は毎回すべて送り直します。会話を覚えているように見えるのは、アプリ側が履歴を保持して送っているからです。

最小のコード例

公式SDKはPython、TypeScript、Java、Go、Ruby、C#、PHPが提供されています。ここではPythonの例を示します。

import anthropic

client = anthropic.Anthropic()  # APIキーは環境変数から読み込まれる

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    system="あなたは技術文書の校正者です。",
    messages=[
        {"role": "user", "content": "次の文章を校正してください。……"}
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

主要なパラメータの意味は次のとおりです。

パラメータ意味
model使うモデルのID（第2章）
max_tokens応答として書ける最大トークン数
system会話全体に効く指示。役割や制約を書く
messagesこれまでのやりとり。user と assistant が交互に並ぶ
output_config.effortどこまで手間をかけるか（第4章）

応答は複数のブロックに分かれて返ってきます。文章のブロック、思考のブロック、ツール利用のブロック。type を確認してから中身を取り出してください。

Important

APIキーはコードへ直接書かず、環境変数か秘密情報の管理サービスから読み込んでください。リポジトリへ誤ってコミットしたキーは、公開された時点で無効化するしかありません。

長い出力はストリーミングで

max_tokens を大きくした場合、応答が返ってくるまでの時間が長くなり、通信が途中で切れることがあります。公式SDKでは max_tokens が21,333を超えるとストリーミングが求められるため、長い出力を想定するならストリーミング（生成された端から少しずつ受け取る方式）を使います。

チャットUIで文字が少しずつ現れるのも同じ仕組みです。

2つの受け取り方を並べると、違いがはっきりします。

上段にリクエストから応答まで何も返らない待ち時間が続く方式、下段に生成された端から少しずつ届くストリーミングを並べた対比図

ツール利用：外の世界とつなぐ

ツール利用（tool use）は、モデルに自分では実行できない処理を依頼させる仕組みです。

流れは次のとおりです。

  1. アプリ側が「使える関数の一覧」（名前・説明・引数の形式）をリクエストに含める
  2. モデルが必要と判断すると、「この関数をこの引数で呼びたい」という応答を返す
  3. アプリ側が実際にその関数を実行する
  4. 実行結果を会話へ追加して、もう一度リクエストを送る
  5. モデルが結果を踏まえた最終的な答えを書く

天気を答えるチャットボットなら、2でモデルが get_weather(location="東京") を要求し、3でアプリが気象APIを叩き、4で結果を返す。そういう流れです。

どこまでがモデルの仕事で、どこからがアプリの仕事か。ここに注目してください。

関数一覧の提示、モデルによる呼び出し要求、アプリでの実行、結果の追加、最終回答という5段階を縦に並べ、実際に実行するのはアプリ側であることを示した図

このループを繰り返すと、第10章・第11章で見たエージェントになります。実際、AnthropicはSDK側にこのループを自動で回す仕組みや、サーバー側で完結するツール（Web検索、コード実行など）も用意しています。

Note

ツールの説明文（description）は、モデルがそのツールを使うかどうかの判断材料になります。何をするツールかだけでなく、どんなときに呼ぶべきかまで書くと呼び出しの精度が上がります。プロンプトの書き方（第6章）と同じです。

コストの考え方

料金は入力トークン数と出力トークン数で決まります。出力のほうが単価が高いのが一般的です（第2章の表を参照）。

コストを下げる主な手段は3つあります。

手段効果使いどころ
モデルを下げる単価が下がる単純な分類・変換にHaiku系を使う
プロンプトキャッシュ繰り返し送る部分の費用を大幅に削減長い共通指示や資料を毎回送る場合
バッチ処理標準価格の50%で処理即時性が不要な大量処理

いちばん効くのがプロンプトキャッシュです。毎回同じ内容から始まるリクエストなら、共通部分をキャッシュしておくだけで2回目以降の読み込み費用が大きく下がります。

料金の決まり方と、下げるための3つの手立てを並べると次のとおりです。

入力と出力のトークン数で決まる料金に対し、モデルを下げる、プロンプトキャッシュ、バッチ処理という3つの手段を並べた図

キャッシュは、指定したブレークポイントまでの接頭辞が一致する範囲で使われます。ブレークポイントより前のブロックを変更すると、そこから後ろのキャッシュは無効になりますが、前段に別のブレークポイントがあれば、その一致部分まで一律に失われるわけではありません。現在時刻やリクエストIDのような変動要素は後ろへ置き、変わらないものを前にまとめる設計が基本です。

Tip

実装したら、応答に含まれる使用量の情報でキャッシュが効いているかを必ず確認してください。キャッシュ読み取りのトークン数が常にゼロなら、どこかに変動要素が紛れ込んでいます。

その他の窓口

Messages API以外にも、いくつかの補助的な入り口があります。

名前用途
Token Counting送る前にトークン数を数える
Files大きなファイルを一度アップロードし、複数回参照する
Message Batches大量のリクエストをまとめて非同期に処理する
Models利用可能なモデルと、その仕様・対応機能を取得する

また、開発者向けの管理画面（Console）でプロンプトを試作したり、ant というコマンドラインツールからAPIを直接叩いたりもできます。

どこから呼ぶか

Claude APIは、Anthropicが直接提供する窓口のほかに、主要なクラウド経由でも利用できます。

提供形態特徴
Claude API（Anthropic直接）すべての機能が最も早く使える
Claude Platform on AWSAnthropicが運用する、AWS基盤経由の窓口
Amazon BedrockAWSが運用。モデルIDに接頭辞が付く
Google CloudGoogle Cloudの認証基盤で利用する
Microsoft FoundryMicrosoftのマーケットプレイス経由で課金される

既存のクラウド契約や、データの所在に関する要件で選ぶことになります。ただし機能の提供状況はプラットフォームで差があります。使いたい機能が対応しているかは先に確認してください。

要点

参考資料

シリーズ目次 ／ 前章: 11. コーディングツール Claude Code とは ／ 次章: 13. Claudeの安全性設計

Share this post:
Share this post on FacebookShare this post on Xはてなブックマークに追加LINEでこの記事を共有する
Previous Post
13. Claudeの安全性設計
Next Post
11. コーディングツール Claude Code とは