Structured outputs

response_format でモデルに有効な JSON を返させます。

POST/v1/chat/completions

response_format パラメータは、モデルの出力を構造化された JSON に制約します。{"type": "json_object"} はレスポンスが有効な JSON になるよう強制し、{"type": "json_schema", ...} は指定したスキーマに従って制約します。この値は OpenAI 互換プロバイダーへそのまま渡される不透明（opaque）なパススルーであり、バックエンドはスキーマ検証を行いません。

リクエスト#

パラメータ	型	必須	説明
response_format	object	任意	`{"type": "json_object"}`（有効な JSON を強制）または `{"type": "json_schema", "json_schema": {...}}`（スキーマで制約）。指定した形式はルーティング先のプロバイダーへそのまま転送されます。

{"type": "json_object"} を使うときは、メッセージ（通常はシステムプロンプト）で JSON で応答するよう明示することを推奨します。期待する JSON の形について指示がないと、出力が一貫しないことがあります。

json_object request

curl https://apirouter.pleum.ai/v1/chat/completions \
  -H "Authorization: Bearer plm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "Extract the user info. Reply with JSON only."},
      {"role": "user", "content": "Jane Doe is 31 and lives in Seoul."}
    ],
    "response_format": {"type": "json_object"}
  }'

json_schema のサポート#

json_schema のサポート可否はルーティング先のモデルによって異なります — すべてのプロバイダー・モデルがスキーマ制約付き出力に対応しているわけではありません。 PleumRouter は response_format を検証・変更せずにプロバイダーへそのまま転送するため、非対応のモデルに送るとプロバイダーがエラーを返したり、そのフィールドを無視したりする場合があります。

json_schema request body

{
  "model": "gpt-4o-mini",
  "messages": [
    {"role": "user", "content": "Jane Doe is 31 and lives in Seoul."}
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "person",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "age": {"type": "integer"},
          "city": {"type": "string"}
        },
        "required": ["name", "age", "city"],
        "additionalProperties": false
      }
    }
  }
}

Anthropic（Claude）の注意点#

response_format は Anthropic（Claude）モデル向けには変換されず、そこでは静かに無視されます。 Claude で JSON を強制するには、代わりに tools と tool_choice を使った tool calling でスキーマを定義してください。

以下のように、望む JSON の形を関数の parameters として定義し、 tool_choice でそのツールを強制します。するとモデルはスキーマに合った引数でツールを呼び出し、構造化された出力は tool_calls の arguments（JSON 文字列）に入ります。

tool calling on Claude

{
  "model": "claude-sonnet-4-6",
  "messages": [
    {"role": "user", "content": "Jane Doe is 31 and lives in Seoul."}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "save_person",
        "description": "Save the extracted person record.",
        "parameters": {
          "type": "object",
          "properties": {
            "name": {"type": "string"},
            "age": {"type": "integer"},
            "city": {"type": "string"}
          },
          "required": ["name", "age", "city"]
        }
      }
    }
  ],
  "tool_choice": {"type": "function", "function": {"name": "save_person"}}
}

レスポンス#

構造化された出力は choices[0].message.content に JSON 文字列として返されるため、使用前にパースする必要があります。正常終了時、 finish_reason は "stop" です。

200 OK

{
  "id": "chatcmpl-gpt-4o-mini-512ms",
  "object": "chat.completion",
  "model": "gpt-4o-mini",
  "provider": "openai",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\"name\":\"Jane Doe\",\"age\":31,\"city\":\"Seoul\"}"
      },
      "finish_reason": "stop"
    }
  ]
}