Skip to content
PleumRouter

Structured outputs

response_format으로 모델이 유효한 JSON을 반환하도록 강제합니다.

POST/v1/chat/completions

response_format 파라미터로 모델 출력을 구조화된 JSON으로 제약할 수 있습니다. {"type": "json_object"}는 응답이 유효한 JSON이 되도록 강제하고, {"type": "json_schema", ...}는 지정한 스키마에 맞게 제약합니다. 이 값은 OpenAI 호환 프로바이더로 그대로 전달되는 불투명(opaque) 패스스루이며, 백엔드는 스키마 검증을 수행하지 않습니다.

요청#

파라미터타입필수설명
response_formatobject선택{"type": "json_object"}(유효한 JSON 강제) 또는 {"type": "json_schema", "json_schema": {...}}(스키마 제약). 지정한 형식은 라우팅된 프로바이더로 그대로 전달됩니다.

{"type": "json_object"}를 사용할 때는 메시지(보통 시스템 프롬프트)에서 JSON으로 응답하라고 명시하는 것을 권장합니다. 모델이 어떤 JSON 형태를 내야 하는지 지시가 없으면 일관성이 떨어질 수 있습니다.

json_object request
curl https://router.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"
    }
  ]
}