テキスト

Create Message

Anthropic Messages API形式を使用してメッセージを作成します

POST
/v1/messages

概要

このエンドポイントはネイティブのAnthropic Messages形式を受け入れるため、Anthropic SDKおよびそれに基づいて構築されたツールはTokenLabのベースURLでそのまま動作します。accepted_request_formatsに anthropic_messages がリストされているモデル(Claudeモデルやその他のモデル)で動作します。

messages には user および assistant のターンを保持します。システム指示はトップレベルの system フィールドに記述してください。max_tokens は必須です。system や tool などのロールを持つOpenAIスタイルのメッセージについては、Chat Completions を使用してください。

Anthropic SDK用ベースURL: https://api.tokenlab.sh (/v1 サフィックスは不要)

リクエストヘッダー

x-api-keystringheader

TokenLab APIキー。x-api-key または Authorization: Bearer <API_KEY> のいずれかを送信してください。両方を異なる値で送信した場合、TokenLabは x-api-key を優先します。

anthropic-versionstringheader

Anthropic APIバージョン。Anthropic SDKが自動的に送信します。APIを直接呼び出す場合は 2023-06-01 を使用してください。

anthropic-betastringheader

カンマ区切りのAnthropicベータ機能名。TokenLabはこのヘッダーをそのまま転送します。ベータ機能が動作するかどうかはモデルに依存します。file_id を参照するコンテンツには files-api-2025-04-14 が必要です。

リクエストボディ

サポートされているオプションパラメータ、許容値、およびデフォルト値は、選択したモデルによって異なります。サンプリング、推論、またはツールオプションを設定する前に、モデル詳細 を確認してください。

modelstring必須

anthropic_messages 形式をサポートするモデルのID。現在の機能については モデル詳細 を確認してください。

messagesarray必須

role (user または assistant) と content を持つメッセージオブジェクトの配列。最大100,000件のメッセージまで。

content はプレーンテキスト文字列、またはコンテンツブロックの配列にできます。画像を送信する場合は、画像URLやBase64文字列を直接プレーンテキストに配置するのではなく、構造化されたコンテンツブロックを使用してください。tool_use、tool_result、thinking、document などの他のネイティブブロックも、それらをサポートするモデルで受け入れられます。

コンテンツブロックの例:

  • テキストブロック: { "type": "text", "text": "この画像を説明してください" }
  • URL経由の画像ブロック: { "type": "image", "source": { "type": "url", "url": "https://example.com/image.jpg" } }
  • Base64経由の画像ブロック: { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "iVBORw0KGgoAAA..." } }
max_tokensinteger必須

生成する最大トークン数。必須: TokenLabはデフォルト値を付与しません。使用可能な最大値はモデルに依存します。モデル詳細 の max_output_tokens を参照してください。大きな値を指定すると、リクエスト実行中にTokenLabが残高から確保する金額が増加し、確保分をカバーできない残高の場合は 402 が返されます。

systemstring | array

messages 配列とは別に指定する、文字列またはテキストコンテンツブロックの配列としてのシステムプロンプト。

temperaturenumber

サンプリング温度。サポート状況、許容値、およびデフォルト値は選択したモデルに依存します。デフォルト値を使用する場合はこのフィールドを省略してください。

streambooleanデフォルト: false

レスポンスをサーバー送信イベント(SSE)のストリームとして返します。ストリーミング を参照してください。

thinkingobject

ネイティブの思考(thinking)設定。例: {"type":"enabled","budget_tokens":10000}。サポートされているモード、予算、および他のパラメータとの組み合わせは選択したモデルに依存します。手動予算を拒否することがわかっているモデルの場合、TokenLabは {"type":"enabled"} を適応型思考として実行し、budget_tokens を無視します。

toolsarray

モデルが利用可能なツール。サポート状況は選択したモデルに依存します。

tool_choiceobject

ネイティブのツール選択オブジェクト。例: {"type":"auto"}。サポートされているタイプは選択したモデルに依存します。

cache_controlobject

プロンプトキャッシュマーカー。例: {"type":"ephemeral"}。1時間のキャッシュには "ttl": "1h" を追加します。トップレベルで設定すると自動キャッシュが有効になります。system ブロック、tools、およびコンテンツブロックにも設定可能です。サポート状況はモデルに依存します。サポートしているモデルは capabilities に prompt-cache をリストしています。

top_pnumber

核サンプリング(Nucleus sampling)パラメータ。temperatureまたはtop_pのいずれかを使用し、両方は使用しないでください。サポート状況は選択したモデルに依存します。

top_kinteger

各トークンに対して上位K個の選択肢からのみサンプリングします。サポート状況は選択したモデルに依存します。

stop_sequencesarray

モデルの生成を停止させるカスタム停止シーケンス。最大8,191個まで。

metadataobject

Anthropic形式のリクエストメタデータ。user_id はエンドユーザーを識別するための不透明な識別子です。

service_tierstring

auto および standard_only のみが有効です。TokenLabはスタンダードティアのみを価格設定し、その他の値は無視します。

レスポンス

idstring

一意のメッセージ識別子。

typestring

常に message。

rolestring

常に assistant。

contentarray

text、thinking、tool_use などのコンテンツブロックの配列。

modelstring

レスポンスを生成したモデル。

stop_reasonstring

生成が停止した理由。end_turn、max_tokens、stop_sequence、tool_use など。モデルは refusal などの他の値を返すこともあります。

stop_sequencestring | null

生成を終了させた停止シーケンス、または null。

usageobject

input_tokens および output_tokens を含むトークン使用量。モデルがプロンプトキャッシュトークンを報告する場合、usage には cache_creation_input_tokens および cache_read_input_tokens も含まれます。

すべてのレスポンスには、request-id および X-Request-ID ヘッダーにリクエストIDが含まれます。サポートに問い合わせる際は、このIDを提示してください。

リクエスト

curl -X POST "https://api.tokenlab.sh/v1/messages" \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

レスポンス

Response
{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "model": "claude-sonnet-5",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 15,
    "output_tokens": 10
  }
}

ビジョン入力の例

ビジョンサポートを備えたClaudeモデルの場合、画像を構造化された画像ブロックとして messages[].content 内に配置します。

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "この画像を説明してください。"
        },
        {
          "type": "image",
          "source": {
            "type": "url",
            "url": "https://example.com/demo.jpg"
          }
        }
      ]
    }
  ]
}
{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "この画像を説明してください。"
        },
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ..."
          }
        }
      ]
    }
  ]
}

拡張思考(Extended Thinking)の例

reasoning 機能を持つモデルを使用してください。max_tokens と budget_tokens をモデルの制限に合わせて調整してください。モデルによっては異なる思考設定が必要な場合があります。

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh"
)

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{"role": "user", "content": "この数学の問題を解いてください..."}]
)

for block in message.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Response: {block.text}")

ストリーミング

"stream": true を設定すると、message_start、content_block_start、content_block_delta、content_block_stop、message_delta、message_stop といったAnthropicのサーバー送信イベントを受信できます。トークン使用量は message_start および message_delta で到着します。

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh"
)

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "物語を話して"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
  • モデルが動作している間、ストリームには : keep-alive のようなSSEコメント行が含まれる場合があります。SDKはこれらを無視します。
  • 失敗が発生した時点でHTTPステータスが 200 になっている可能性があります。ストリーム開始後の失敗は、以下と同じエラーボディを持つ event: error イベントとして到着します。

エラー

エラーはAnthropicのエラー形式を使用します。request_id はTokenLabのリクエストIDです。一部のエラーには code や hint などのフィールドが追加されます。

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: Required. /v1/messages follows the native Anthropic contract and does not infer a default max_tokens value."
  },
  "request_id": "req_01JEXAMPLE"
}
ステータスerror.type一般的な原因
400invalid_request_errorフィールドの欠落または無効、不明なモデル、またはMessages形式を受け入れないモデル
401authentication_errorAPIキーが欠落しているか無効
402billing_error残高がリクエストをカバーできない (error.code は insufficient_balance)。利用制限に達したAPIキーも 402 を返し、error.code は quota_exceeded、error.type は rate_limit_error となります
403permission_errorAPIキーが要求されたモデルを使用できない、またはアカウントが停止・制限されている
409conflict_error同じ Idempotency-Key での再試行。冪等性キーによる安全な再試行 を参照
413request_too_largeリクエスト入力が大きすぎる
429rate_limit_errorリクエストが多すぎる
500, 502, 503api_error または overloaded_errorリクエストを完了できなかった、または現在利用可能なルートがない。後で再試行してください
504timeout_errorリクエストがタイムアウトした

関連インターフェース

認証

BearerAuth
AuthorizationBearer <token>

APIキー認証。Dashboard > API > API KeysでAPIキーを作成または管理します。

場所: header

ヘッダー

X-TokenLab-Delivery-Policy?string

リクエストごとの配信ポリシー。APIキーおよびWorkspaceのデフォルト設定を上書きします。自動的にまず TokenLab Verified を試行し、出力、リクエストの受け入れ、または永続的なリソース作成の前に、一度だけ Official に切り替える場合があります。

指定できる値

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

同じリクエストの二重実行を防ぐためのオプションのキー。リクエストごとにUUIDなどの新しい一意の値を送信し、タイムアウト後の再試行時にも同じ値を保持してください。同じキーを使用した再試行は再実行されず、409とidempotency_replay_unavailable、またはボディが変更された場合は通常idempotency_conflictが返されます。例外として、クライアントの切断後に非ストリーミングの結果が完了した場合、24時間以内に同じキーとボディで再試行すると、その結果(最大1 MB)がヘッダーIdempotent-Replayed: trueと共に返され、二重課金は発生しません。255文字を超えるキーは無視され、そのリクエストには冪等性保護が適用されません。詳細は冪等性キーを使用した安全な再試行を参照してください。

長さ1 <= length <= 255

リクエストボディ

application/json

レスポンス

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json