엔드포인트

구조화된 출력

response_format과 JSON Schema로 모델이 스키마에 맞는 JSON을 반환하게 하는 방법입니다. strict 옵션, 지원 모델 확인, 응답이 잘렸을 때의 처리와 오류 상황을 설명합니다. 요청 파라미터와 응답 예시도 함께 있습니다.

플레이그라운드에서 사용해 보기

구조화된 출력은 모델이 사용자가 제공한 JSON Schema와 일치하는 JSON을 반환하게 합니다. 데이터 추출, 분류, 그리고 코드가 파싱하는 모든 응답에 사용하세요. Chat completions에는 response_format을, Responses에는 text.format을 설정합니다.

요청 파라미터

파라미터	타입	설명
`response_format.type`	string	스키마로 제약된 출력은 `"json_schema"`, 자유 형식 JSON 모드는 `"json_object"`.
`response_format.json_schema.name`	string	스키마 이름.
`response_format.json_schema.strict`	boolean	`true`이면 제공자가 지원하는 경우 스키마를 정확히 강제합니다.
`response_format.json_schema.schema`	object	JSON Schema. `strict`를 쓸 때는 `additionalProperties: false`를 사용하고 모든 속성을 `required`에 나열하세요.

{
  "model": "openai/gpt-5-mini",
  "messages": [{ "role": "user", "content": "Extract: Ada Lovelace, born 1815 in London." }],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "person",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "born": { "type": "integer" },
          "city": { "type": "string" }
        },
        "required": ["name", "born", "city"],
        "additionalProperties": false
      }
    }
  }
}

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api14.com/api/v1",
  apiKey: process.env.API14_API_KEY,
});

const result = await client.chat.completions.create({
  "model": "openai/gpt-5-mini",
  "messages": [
    {
      "role": "user",
      "content": "Extract the city and country from: \"I live in Lisbon, Portugal.\""
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "place",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          },
          "country": {
            "type": "string"
          }
        },
        "required": [
          "city",
          "country"
        ],
        "additionalProperties": false
      }
    }
  }
});
console.log(JSON.parse(result.choices[0].message.content));

응답

JSON은 message.content에 문자열로 도착합니다.

{
  "id": "gen-1760000000-json1",
  "model": "openai/gpt-5-mini",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": { "role": "assistant", "content": "{\"name\":\"Ada Lovelace\",\"born\":1815,\"city\":\"London\"}" }
    }
  ],
  "usage": { "prompt_tokens": 71, "completion_tokens": 18, "total_tokens": 89, "cost": 0.0000538 }
}

SDK 헬퍼는 평소처럼 동작합니다. 예를 들어 Node에서는 Zod와 함께, Python에서는 Pydantic과 함께 client.chat.completions.parse(...)를 사용할 수 있습니다.

모델 지원

지원하는 모델을 찾으려면 모델의 supported_parameters에서 structured_outputs 또는 response_format을 확인하세요.
스키마를 지켜 주는 제공자로만 요청이 가도록 하려면 provider: { "require_parameters": true }를 추가하세요.
기본 지원이 없는 모델도 프롬프트에서 요청하면 JSON을 만들 수 있지만, 출력이 보장되지는 않습니다. 항상 검증하세요.
finish_reason이 "length"이면 JSON이 잘린 것입니다. max_tokens를 늘리세요.

오류

잘못된 스키마는 보통 제공자의 메시지가 담긴 업스트림 400을 반환합니다. 그 밖의 오류는 Chat completions와 같습니다. 오류를 참고하세요.