Skip to main content
POST
2つの API を混同しないでください/v1/* は推論 API(本ドキュメント、上流をそのまま透過・ラッパーなし);/api/* は管理 API(残高/ログ照会など、レスポンスは {success, message, data})。他の箇所で /v1/messages{code, data} を返すと書いてあっても、本ドキュメントを正としてください。

認証

認証は次の2方式に対応し、いずれか一方を使用します:
string
Anthropic スタイルの認証ヘッダーAPIキー管理ページにアクセスしてAPIキーを取得してください
string
Bearer Token 認証(x-api-key との二者択一)
string
API バージョン(任意。未指定でも正常に応答します)将来 Anthropic 公式エンドポイントへ移行しやすいよう、付けておくことを推奨します:例:2025-10-01

リクエストボディ

string
デフォルト:"claude-sonnet-4-6"
必須
Model name
  • claude-opus-4-8 - Claude Opus 4.8 flagship model
  • claude-opus-4-7 - Claude Opus 4.7 flagship model
  • claude-opus-4-6 - Claude Opus 4.6 flagship model
  • claude-sonnet-4-6 - Claude Sonnet 4.6 balanced version
  • claude-opus-4-5-20251101 - Claude Opus 4.5 model
array
必須
メッセージのリストモデルが次のレスポンスを生成するためのメッセージの配列。各メッセージには rolecontent の2つのフィールドが含まれます。💡 クイック入力(Try itエリア):
  1. ”+ Add an item” をクリックしてメッセージを追加
  2. role に入力:user(ユーザーメッセージ)または assistant(AI応答、複数ターン会話用)
  3. content に入力:話したい内容
単一のユーザーメッセージ:
複数ターンの会話:
事前入力されたアシスタント応答:
integer
必須
生成する最大トークン数(必須。Anthropic 公式と同様)停止前に生成する最大トークン数。モデルはこの制限に達する前に停止する可能性があります。モデルによって最大値が異なります。最小値:1
object
Extended thinking の設定有効にすると、レスポンスの contentthinking ブロックが含まれる場合があります。推奨は標準モデル名 + 本パラメータの組み合わせです。プラットフォーム側の -thinking モデル別名に依存しない方が、公式エンドポイントへコード変更なしで移行しやすくなります。複数ターン会話で thinking ブロックを送り返す場合は、signatureそのまま戻す必要があります。そうでないと上流が拒否します。
string | array
システムプロンプトシステムプロンプトはClaudeの役割、性格、目標、指示を設定します。文字列形式:
構造化形式:
number
温度パラメータ、範囲は0~1出力のランダム性を制御:
  • 低い値(例:0.2):より決定的、保守的
  • 高い値(例:0.8):よりランダム、創造的
デフォルト:1.0
number
ニュークレアスサンプリングパラメータ、範囲は0~1ニュークレアスサンプリングを使用します。temperatureまたはtop_pのいずれかの使用を推奨します。デフォルト:1.0
integer
Top-Kサンプリング上位K個のオプションのみからサンプリングし、「ロングテール」の低確率応答を除去します。高度なユースケースにのみ推奨。
boolean
ストリーミングを有効化trueの場合、Server-Sent Events(SSE)を使用してレスポンスをストリーミングします。デフォルト:false
array
停止シーケンスモデルの生成を停止させるカスタムテキストシーケンス。最大4つのシーケンス。例:["\n\nHuman:", "\n\nAssistant:"]
object
MetadataMetadata object for the request.Includes:
  • user_id: User identifier
array
Tool definitionsList of tools the model can use to complete tasks.Function tool example:
Supported tool types:
  • Custom function tools
  • Computer use tool (computer_20241022)
  • Text editor tool (text_editor_20241022)
  • Bash tool (bash_20241022)
object
Tool choice strategyControls how the model uses tools:
  • {"type": "auto"}: Auto-decide (default)
  • {"type": "any"}: Must use a tool
  • {"type": "tool", "name": "tool_name"}: Use specific tool

Response

string
一意のメッセージ識別子例:"msg_013Zva2CMHLNnXjNJJKqJ2EF"
string
オブジェクトタイプ常に "message"
string
ロール常に "assistant"
array
コンテンツブロックの配列contenttype でブロック種別を区別します。1 回のレスポンスに複数ブロックが含まれる場合があります(例:thinking 有効時は thinking + text の 2 ブロック)。text ブロック:
tool_use ブロック:
caller は上流が追加したフィールドで、公式ドキュメントにはまだ記載されていません。パース時は無視して問題ありません。
thinking ブロック(リクエスト本体に thinking パラメータがある場合に出現):
複数ターン会話で thinking ブロックを送り返す場合は、signatureそのまま戻す必要があります。そうでないと上流が拒否します。
content[0] がテキストだと仮定しないでください。 thinking を有効にすると content[0] が thinking ブロックになることがあります。次のように走査して絞り込んでください:
string
リクエストを処理したモデル例:"claude-sonnet-4-6"
string
停止理由取りうる値:
  • end_turn: 自然終了
  • max_tokens: 最大トークン数に到達
  • stop_sequence: 停止シーケンスに到達
  • tool_use: ツールを呼び出した
string | null
トリガーされた停止シーケンス停止シーケンスにより停止した場合はその内容。それ以外は null
object | null
Anthropic の比較的新しいフィールド。通常のリクエストでは null
object
トークン使用統計(非ストリーミング時の完全構造)

Usage Examples

Basic Conversation

Multi-turn Conversation

Using System Prompts

Streaming Response

Tool Use

Vision Understanding

Base64 Image

Best Practices

1. Prompt Engineering

Clear role definition:
Structured output:

2. Error Handling

3. Token Optimization

4. Prefilling Responses

Streaming Response Handling

Python Streaming

JavaScript Streaming

プラットフォーム差異と接続時の注意

レスポンスにラッパーなし

POST /v1/messages 成功時は Anthropic message オブジェクトを直接返します{code, data} の外層はありません。公式 SDK、Claude Code、Cline などと 1:1 互換になります。

エラー形式(公式との唯一の実質的な差異)

Anthropic 公式との比較:トップレベルに "type": "error" がなく、error.typeinvalid_request_error などの意味付き型ではなく、常に apimart_error です。 接続時の推奨error.type でリトライ分岐しないでください。HTTP ステータスコード + error.code を使ってください: 障害報告時は、error.message 末尾の request id、およびレスポンスヘッダー x-oneapi-request-id を提供してください。

ストリーミング SSE

リクエストに "stream": true を付けます。イベント順序は公式と同じです: message_startcontent_block_startpingcontent_block_delta(複数回)→ content_block_stopmessage_deltamessage_stop ⚠️ ストリーミングと非ストリーミングで usage 構造が異なりますmessage_delta.usage は通常 4 つのトークンフィールドのみで、cache_creationservice_tierinference_geoありません。分けてパースするか、すべて任意として扱ってください。

未実装エンドポイント

POST /v1/messages/count_tokens未実装で 404 を返します。公式 SDK の client.messages.count_tokens() は失敗します。トークンを事前見積もりする場合はローカルで概算するか、レスポンスの usage.input_tokens を読んでください。

未知フィールドは必ず無視

本 API は上流を透過するため、Anthropic が随時フィールドを追加する可能性があります(例:stop_detailsinference_geocalleroutput_tokens_details)。厳格な schema を有効にしないでください:
  • Go:DisallowUnknownFields() を使わない
  • Pydantic:extra="forbid" にしない
  • TypeScript / Zod:.strict() ではなく .passthrough() を使う

モデル名の推奨

-thinking サフィックス付きの同名モデルはプラットフォーム拡張の別名です。推奨はサフィックスなしの標準モデル名 + リクエストボディの thinking パラメータで、公式エンドポイントへの移行が容易になります。 リクエストボディのその他のフィールドは公式と同じです:modelmessagesmax_tokens(必須)、systemtemperaturetop_ptop_kstop_sequencesstreamtoolstool_choicethinkingmetadata。セマンティクスは Anthropic Messages API に準拠します。

注意事項

  1. APIキーのセキュリティ
    • APIキーは環境変数に保存する
    • ソースコードにキーをハードコードしない
    • キーを定期的にローテーションする
  2. レート制限
    • API のレート制限に注意する
    • リトライ機構を実装する(HTTP ステータスコードに基づく)
    • 指数バックオフを使用する
  3. トークン管理
    • トークン使用量を監視する(usage を読む)
    • プロンプト長を最適化する
    • 適切な max_tokens 値を使う
    • thinking 有効時、output_tokens は thinking を既に含む。二重課金しないこと
  4. モデル選択
    • Opus: 複雑なタスク、深い思考が必要
    • Sonnet: パフォーマンスとコストのバランス
    • Haiku: 高速応答、単純なタスク
  5. コンテンツ解析
    • content を走査し type == "text" を取得する。content[0].text を固定で書かない
    • モデルが Markdown コードブロックで JSON を包んで返す場合、それはモデル出力であり API ラッパーではない(下記 FAQ 参照)
  6. コンテンツフィルタリング
    • ユーザー入力を検証する
    • 機密情報をフィルタする
    • コンテンツモデレーションを実装する

FAQ

レスポンスの content 内 text が ```json ... ``` コードブロックになっている。どう除去する?

これは API 構造の問題ではありません。text フィールドにはモデルが生成した生の内容が入ります。モデルが JSON を求められていると判断すると、Markdown コードブロックで包みます。API はモデル出力を書き換えませんし、書き換えるべきでもありません。 きれいな構造化データを得る正しい方法は次の 3 つです(推奨度の高い順):
  1. tools で構造化出力を強制する——最も確実で、input フィールドがそのままパース済みオブジェクトになります:
  1. assistant メッセージを prefill し、モデルに { から続けさせる:
  1. system prompt で「JSON のみを出力し、Markdown コードブロックを付けない」と明示する。
正規表現で code fence を剥がす方法は非推奨です——モデルがフェンスを付けない場合にパースが失敗します。