以下是为您翻译成日语的 API 文档。翻译过程中采用了标准的日本 IT 与开发者术语，并结合了 SEO 优化的考量（如使用常见的“APIドキュメント”、“構造化出力”、“エンドポイント”等搜索关键词），同时完全保留了您原有的 Markdown 格式。

# APIドキュメント：構造化出力の作成

## エンドポイントの概要
プロンプト（Prompt）を指定すると、モデルは1つまたは複数の予測される補完（Completion）レスポンスを返します。また、指定された JSON Schema に従って、強制的に構造化データを出力させることもサポートしています。

**公式リファレンスドキュメント**：[OpenAI Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs?api-mode=responses)

## 基本情報
- **HTTPメソッド**：`POST`
- **リクエストURL**：`https://api.codingplanx.ai/v1/chat/completions`
- **データフォーマット**：`application/json`

---

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

| パラメータ名 | 必須 | データ型 | サンプル値 | 説明 |
| :--- | :---: | :--- | :--- | :--- |
| `Content-Type` | はい | string | `application/json` | リクエストボディのデータ型を指定します |
| `Accept` | はい | string | `application/json` | クライアントが受信するデータ型を指定します |
| `Authorization`| いいえ | string | `Bearer {{YOUR_API_KEY}}` | 認証情報（クレデンシャル） |

---

## リクエストボディ (Request Body)

| パラメータ名 | 必須 | データ型 | 説明 |
| :--- | :---: | :--- | :--- |
| `model` | **はい** | string | 使用するモデルのID（例: `gpt-4.1-2025-04-14`）。 |
| `messages` | **はい** | array | これまでの会話に含まれるメッセージのリスト。 |
| ? `messages[].role` | はい | string | メッセージ送信者のロール。例: `system`, `user`, `assistant`。 |
| ? `messages[].content`| はい | string | メッセージの具体的な内容。 |
| `tools` | **はい** | array | モデルが呼び出すことができるツールのリスト。現在は関数（function）のみサポートしています。モデルが JSON 入力を生成するための関数リストを提供するために使用します。 |
| `tool_choice` | **はい** | object | モデルがどの関数を呼び出すかを制御します。`none` は呼び出さないことを、`auto` は自動選択を意味します。`{"type": "function", "function": {"name": "my_function"}}` を指定して特定の関数を強制的に呼び出すことも可能です。 |
| `temperature` | いいえ | integer | サンプリング温度（0 ～ 2 の範囲）。値が高い（例: 0.8）ほど出力がランダムになり、値が低い（例: 0.2）ほど出力が集中し、決定的になります。この値または `top_p` のいずれかを変更することをお勧めしますが、両方を同時に変更しないでください。 |
| `top_p` | いいえ | integer | ヌクレアスサンプリング（Top-p）パラメータ。0.1 の場合、確率質量の全体の上位 10% を構成するトークンのみが考慮されます。この値または `temperature` のいずれかを変更することをお勧めしますが、両方を同時に変更しないでください。 |
| `n` | いいえ | integer | 各入力メッセージに対して生成する補完の選択肢の数。デフォルトは 1 です。 |
| `stream` | いいえ | boolean | ストリーミング出力を有効にするかどうか。true の場合、Server-Sent Events (SSE) 形式でメッセージの差分（チャンク）を送信し、`data: [DONE]` で終了します。デフォルトは false です。 |
| `stop` | いいえ | string | API がトークンの生成を停止するトリガーとなる文字列（最大4つまで）。デフォルトは null です。 |
| `max_tokens` | いいえ | integer | チャット補完で生成される最大トークン数。デフォルトは inf（無限）です。 |
| `presence_penalty`| いいえ | number | 存在ペナルティ（-2.0 ～ 2.0）。正の値は、それまでにテキスト内に出現したかどうかに基づいて新しいトークンにペナルティを与え、モデルが新しいトピックについて話す可能性を高めます。 |
| `frequency_penalty`| いいえ | number | 頻度ペナルティ（-2.0 ～ 2.0）。正の値は、それまでのテキスト内での出現頻度に基づいて新しいトークンにペナルティを与え、モデルが同じ内容を繰り返す可能性を低くします。 |
| `logit_bias` | いいえ | null/object | トークンIDを関連するバイアス値（-100 ～ 100）にマッピングする JSON オブジェクトを受け入れます。補完に特定のトークンが出現する確率を調整するために使用します。 |
| `user` | いいえ | string | エンドユーザーを表す一意の識別子。乱用の監視や検出に役立ちます。 |
| `response_format` | いいえ | object | モデルが出力しなければならないデータフォーマットのオブジェクトを指定します。`{"type": "json_schema", "json_schema": {...}}` を設定することで「構造化出力」が有効になり、モデルが有効な JSON フォーマットを生成することが保証されます。 |
| `seen` | いいえ | integer | (ベータ機能) 乱数シード（Seed）を設定します。システムは決定論的なサンプリングを行うよう最善を尽くします。同じシード値とパラメータを持つリクエストを繰り返すと、同じ結果が返されるはずです。 |

### リクエスト例 (Request Example)

```json
{
  "model": "gpt-4.1-2025-04-14",
  "messages": [
    {
      "role": "system",
      "content": "Determine if the user input violates specific guidelines and explain if they do."
    },
    {
      "role": "user",
      "content": "How do I prepare for a job interview?"
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "content_compliance",
      "description": "Determines if content is violating specific moderation rules",
      "schema": {
        "type": "object",
        "properties": {
          "is_violating": {
            "type": "boolean",
            "description": "Indicates if the content is violating guidelines"
          },
          "category": {
            "type": ["string", "null"],
            "description": "Type of violation, if the content is violating guidelines. Null otherwise.",
            "enum": ["violence", "sexual", "self_harm"]
          },
          "explanation_if_violating": {
            "type": ["string", "null"],
            "description": "Explanation of why the content is violating"
          }
        },
        "required": ["is_violating", "category", "explanation_if_violating"],
        "additionalProperties": false
      },
      "strict": true
    }
  }
}

---

レスポンスボディ (Response Body)

レスポンス例 (Response Example)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\r
\r
Hello there, how may I assist you today?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

---

よくある質問 (FAQ)

1. response_format とは何か？モデルに厳密な JSON を出力させるにはどうすればよいか？

response_format パラメータを使用すると、モデルに対して特定のフォーマットでデータを返すよう要求できます。「構造化出力」を使用する場合は、{"type": "json_schema"} を設定し、その内部で独自の JSON Schema を定義した上で、strict: true を有効にする必要があります。これにより、コード内で追加のエラー処理や JSON パースのフォールバックを行うことなく、モデルが定義したフィールドとデータ型に従って 100% 準拠した内容を出力することが保証されます。

2. 出力された JSON が途中で途切れている（切り捨てられている）のはなぜか？

レスポンスデータ内で choices[0].finish_reason の値が length になっている場合、生成されたテキストが max_tokens の制限に達したか、モデルの最大コンテキスト長の制限を超えたことを意味します。リクエスト時に max_tokens パラメータの値を大きくすることをお勧めします。

3. temperature と top_p パラメータの違いは何か？どちらを調整すべきか？

どちらもモデルの出力のランダム性を制御するためのパラメータです：

• temperature: モデルの出力確率分布をスケーリングします。値が低いほど出力は厳密で決定的になり、値が高いほど出力はより発散的（創造的）になります。
• top_p (ヌクレアスサンプリング): 累積確率が p に達する上位の頻出語彙からのみモデルが選択するように制限します。 公式の推奨事項: どちらか一方のパラメータのみを調整し、temperature と top_p を同時に変更しないでください。

4. stream: true を有効にするとどうなるか？

stream: true を設定すると、API は回答全体が生成されるのを待たずに、タイプライターのようにデータをリアルタイムでストリーミングして返します。返されるデータのフォーマットは Server-Sent Events (SSE) になります。クライアント側はデータストリームをリッスンし、終了を示す [DONE] フラグを受け取るまで delta.content を結合し続ける必要があります。

5. 同じプロンプトを呼び出すたびに、完全に同じ回答を得るにはどうすればよいか？

大規模言語モデル（LLM）にはランダム性がありますが、特定の seen (Seed) パラメータを渡し、temperature を 0 に設定することで、最大限の決定論的な出力（同じ結果）を実現できます。もしレスポンス内の system_fingerprint が変更されている場合、バックエンドのモデル設定に微調整（アップデート等）があったことを意味し、その場合は Seed が同じでも結果に微妙な差異が生じる可能性があります。