コアガイド
Structured Outputs & Tool Calling
JSONの返却や、アプリケーション内でのモデルによる関数呼び出し
Structured output(構造化出力)は、モデルに対してJSON形式での回答を求めるものです。Tool calling(ツール呼び出し)は、アプリケーションが実行する関数をモデルにリクエストさせるものです。利用可能なフィールドはAPIフォーマットやモデルによって異なるため、会話全体を通して一つのフォーマットを維持し、モデルが生成したすべての値をアプリケーション側で検証してください。
APIフォーマットの選択
| ニーズ | API | フィールド |
|---|---|---|
| ポータブルなJSONオブジェクトのレスポンス | /v1/chat/completions | response_format: {"type": "json_object"} |
| OpenAI互換の関数呼び出し | /v1/chat/completions | tools: [{ "type": "function", "function": ... }] |
| OpenAIレスポンスツール | /v1/responses | レスポンスの tools、tool_choice、および text フィールド |
| Claudeネイティブのツール使用または思考 | /v1/messages | Anthropic Messagesツールスキーマ |
| Gemini関数宣言または組み込みツール | /v1beta/models/:model:generateContent | Geminiネイティブの 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は関数名と引数を返します。アプリケーション側でそれを実行してください:
- メッセージとツール定義を送信します。
- モデルのレスポンスから
tool_calls、function_call、Anthropicのtool_use、またはGeminiの関数呼び出しパーツを読み取ります。 - 自身のバックエンドでツールを実行します。
- ツール結果を同じAPIフォーマットで追加します。
- モデルが最終的な回答を返すまで会話を継続します。
ツール呼び出しと最終的な回答が完了するまで、同じ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リファレンス
| トピック | リファレンス |
|---|---|
| マルチフォーマットAPI | Multi-Format API |
| チャット完了の作成 | Chat Completion の作成 |
| レスポンスの作成 | レスポンスの作成 |
| メッセージの作成 | Create Message |
| Geminiコンテンツの生成 | Generate Gemini Content |