公式 Function Calling API ドキュメント

本APIエンドポイントは、チャット補完（Chat Completion）を作成するために使用されます。メッセージのリストとオプションのツールリスト（Functions）を提供することで、モデルはテキスト応答を生成したり、外部関数を呼び出すための特定の JSON スキーマに準拠したパラメータを生成したりできます。

1. エンドポイント情報

エンドポイント URL: https://api.codingplanx.ai/v1/chat/completions
HTTP メソッド: POST
Content-Type: application/json
認証方式: Authorization: Bearer {{YOUR_API_KEY}}

2. リクエストパラメータ

2.1 リクエストヘッダー (Headers)

パラメータ名	データ型	必須	例	説明
Content-Type	string	はい	`application/json`	`application/json` に固定
Accept	string	はい	`application/json`	`application/json` に固定することを推奨
Authorization	string	はい	`Bearer sk-xxxxxx`	API キー認証

2.2 リクエストボディ (Body)

パラメータ名	データ型	必須	デフォルト値	説明
model	string	はい	-	使用するモデル ID（例：`gpt-4o`、`gpt-3.5-turbo` など）。
messages	array	はい	-	これまでの会話のメッセージリスト。各オブジェクトには `role` ("system", "user", "assistant", "tool") と `content` が含まれます。
tools	array	はい	-	モデルが呼び出せるツールリスト。現在は `type: "function"` のみサポート。関数名、説明、およびパラメータの定義に使用します。
tool_choice	object/str	いいえ	`auto`	モデルがどの関数を呼び出すかを制御します。`none`: 呼び出さない、`auto`: 自動選択、`{"type": "function", "function": {"name": "xxx"}}`: 特定の関数を強制的に呼び出す。
temperature	number	いいえ	1	サンプリング温度 (0〜2)。高いほどランダムになり、低いほど決定的になります。
top_p	number	いいえ	1	核サンプリング (Nucleus sampling) の確率。
n	integer	いいえ	1	入力メッセージごとに生成されるチャット補完の選択肢の数。
stream	boolean	いいえ	false	ストリーミング転送を行うかどうか。`true` に設定した場合、トークンはサーバー送信イベント (SSE) として送信されます。
stop	string/array	いいえ	null	API がトークンの生成を停止するストップシーケンス。
max_tokens	integer	いいえ	inf	生成する最大トークン数。
presence_penalty	number	いいえ	0	-2.0 から 2.0 の間の数値。モデルが新しいトピックについて話す可能性を高めます。
frequency_penalty	number	いいえ	0	-2.0 から 2.0 の間の数値。モデルが同じ内容を繰り返す可能性を低くします。
response_format	object	いいえ	-	出力フォーマットを指定します。`{"type": "json_object"}` を指定すると JSON モードが有効になります。
seed	integer	いいえ	-	指定した場合、システムは可能な限り決定論的なサンプリングを行い、同じシードとパラメータによるリクエストが同じ結果を返すように努めます。
user	string	いいえ	-	エンドユーザーを表す一意の識別子。乱用の監視に使用されます。

3. リクエスト例

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": "今日の北京の天気はどうですか？"
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "指定された場所の現在の天気を取得する",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "都市名、例：北京市"
                        },
                        "unit": {
                            "type": "string",
                            "enum": ["celsius", "fahrenheit"]
                        }
                    },
                    "required": ["location"]
                }
            }
        }
    ],
    "tool_choice": "auto",
    "temperature": 0.8
}

4. レスポンスパラメータ

4.1 レスポンスボディの構造

パラメータ名	データ型	説明
id	string	このリクエストの一意の識別子。
object	string	オブジェクトタイプ。通常は `chat.completion` です。
created	integer	Unix タイムスタンプ（秒）。
choices	array	生成されたレスポンスのリストを含みます。
└ message	object	`role`、`content`、および `tool_calls` (ある場合) を含みます。
└ finish_reason	string	停止理由。`stop` (自然停止)、`length` (max_tokens に到達)、`tool_calls` (ツールの呼び出しが必要)。
usage	object	トークン消費状況：`prompt_tokens`、`completion_tokens`、`total_tokens`。

4.2 レスポンス例 (通常のテキスト)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "今日の北京は晴れで、気温は25度です。"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

5. FAQ (よくある質問)

Q1: Function Calling (ツール呼び出し) とは何ですか？ A: これはモデルに外部機能を呼び出す能力を持たせる方法です。モデルが直接コードを実行するのではなく、あなたの説明に基づいて、関数名と必要なパラメータを含む JSON オブジェクトを生成します。あなたはこの JSON を抽出し、自身のローカル環境またはサーバーで関数を実行し、その結果をモデルに返す必要があります。

Q2: tools を設定したのに、モデルが tool_calls を返さないのはなぜですか？ A: 以下の理由が考えられます：

モデルが、ユーザーの質問にはその関数を呼び出す必要がないと判断した。
関数の説明 (description) が不明確で、モデルが意図をマッチングできなかった。
tool_choice が明示的に none に設定されている。
モデルの能力制限（ツール呼び出しをサポートする gpt-4o や gpt-3.5-turbo などのモデルの使用を優先して推奨します）。

Q3: 特定の関数を強制的に呼び出させるにはどうすればよいですか？ A: tool_choice を特定のオブジェクトに設定できます。例： "tool_choice": {"type": "function", "function": {"name": "get_current_weather"}}。これにより、モデルが不要だと判断した場合でも、その関数のパラメータ生成を試みます。

Q4: finish_reason が length の場合、どうすればよいですか？ A: 生成されたレスポンスが max_tokens の制限、またはモデルのコンテキストウィンドウの制限を超えたことを意味します。max_tokens パラメータを大きくするか、messages の履歴を短くしてみてください。

Q5: JSON モード (JSON Mode) を使用する際の注意事項は何ですか？ A: response_format: { "type": "json_object" } を設定する場合、必ず System または User メッセージ内で、JSON 形式で出力するようにモデルに明示的に指示する必要があります（例：「JSON 形式で返答してください」を含める）。そうしないと、モデルが空白を出力する無限ループに陥る可能性があります。

Q6: 複数のツール呼び出しを処理するにはどうすればよいですか？ A: 1 回のリクエストで、モデルが同時に複数のツール呼び出しを生成する場合があります（例：北京と上海の天気を同時に照会する）。choices[0].message.tool_calls 配列を反復処理 (ループ) し、それぞれの呼び出しに対応するローカルロジックを実行する必要があります。