コアガイド

Structured Outputs & Tool Calling

JSONの返却や、アプリケーション内でのモデルによる関数呼び出し

Structured output(構造化出力)は、モデルに対してJSON形式での回答を求めるものです。Tool calling(ツール呼び出し)は、アプリケーションが実行する関数をモデルにリクエストさせるものです。利用可能なフィールドはAPIフォーマットやモデルによって異なるため、会話全体を通して一つのフォーマットを維持し、モデルが生成したすべての値をアプリケーション側で検証してください。

APIフォーマットの選択

ニーズAPIフィールド
ポータブルなJSONオブジェクトのレスポンス/v1/chat/completionsresponse_format: {"type": "json_object"}
OpenAI互換の関数呼び出し/v1/chat/completionstools: [{ "type": "function", "function": ... }]
OpenAIレスポンスツール/v1/responsesレスポンスの tools、tool_choice、および text フィールド
Claudeネイティブのツール使用または思考/v1/messagesAnthropic Messagesツールスキーマ
Gemini関数宣言または組み込みツール/v1beta/models/:model:generateContentGeminiネイティブの tools およびコンテンツパーツ

組み込みツールは、それらをドキュメント化しているAPIフォーマットでのみ使用してください。TokenLabは、これらのツールをフォーマット間で変換することはありません。

JSONモード

多くのチャットモデルで動作するJSONオブジェクトが必要な場合は、Chat CompletionsのJSONモードを使用してください:

{
  "model": "gpt-5.6-terra",
  "messages": [
    {
      "role": "user",
      "content": "Return a JSON object with city and weather."
    }
  ],
  "response_format": { "type": "json_object" }
}

JSONモードをサポートするモデルは、GET /v1/models の capabilities に json-mode がリストされています。Chat Completionsは text および json_object を受け付けます。json_schema および strict はモデルやフォーマット固有のものです。選択したモデルがサポートを明記している場合にのみ使用してください。

返されたJSONは、必ずサーバー側で解析および検証を行ってください。JSONモードは、アプリケーションレベルのスキーマ検証の代わりにはなりません。

ツール呼び出しの完了

TokenLabは関数名と引数を返します。アプリケーション側でそれを実行してください:

  1. メッセージとツール定義を送信します。
  2. モデルのレスポンスから tool_calls、function_call、Anthropicの tool_use、またはGeminiの関数呼び出しパーツを読み取ります。
  3. 自身のバックエンドでツールを実行します。
  4. ツール結果を同じAPIフォーマットで追加します。
  5. モデルが最終的な回答を返すまで会話を継続します。

ツール呼び出しと最終的な回答が完了するまで、同じAPIフォーマットを維持してください。4つのフォーマットは、それぞれツール状態の表現方法が異なります。

Chat Completionsの例

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {
        "role": "user",
        "content": "Extract name and email as JSON. If needed, look up the customer."
      }
    ],
    "response_format": { "type": "json_object" },
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_customer",
          "description": "Look up a customer by email",
          "parameters": {
            "type": "object",
            "properties": {
              "email": { "type": "string" }
            },
            "required": ["email"]
          }
        }
      }
    ]
  }'

有用なスキーマの作成

  • スキーマは小さく、明示的に保ってください。ネストが深い巨大なスキーマはトークンを消費し、信頼性を低下させます。
  • プロダクトの動作に不可欠な値には、必須フィールド(required fields)を優先してください。
  • UIやバックエンドが依存する固定セットには、enumを使用してください。
  • モデルが形状を理解するのに苦労する場合は、プロンプト内に例を含めてください。
  • フィールドがサポートされていない場合は、削除するか、そのフィールドをドキュメント化しているAPIフォーマットを使用してください。

ツール実行前の注意点

  • APIフォーマット、モデル、ツール名、スキーマのフィールド名を記録してください。
  • 副作用を伴う処理を実行する前に、ツール引数を検証してください。
  • ツール実行前に、独自の権限チェックを適用してください。
  • クライアントの再試行によって同じツール呼び出しが繰り返される可能性があるため、ツール実行は冪等(べきとう)にしてください。
  • ツールによって返された機密情報を、モデルから見えるメッセージにログ出力しないでください。

APIリファレンス

トピックリファレンス
マルチフォーマットAPIMulti-Format API
チャット完了の作成Chat Completion の作成
レスポンスの作成レスポンスの作成
メッセージの作成Create Message
Geminiコンテンツの生成Generate Gemini Content

このページの内容