제미나이 API 응답을 JSON으로 받는 법: 구조화 출력 설정과 데이터 검증 순서

제미나이 API 응답을 JSON으로 받으려면 프롬프트뿐 아니라 구조화 출력 설정에 JSON Schema를 전달해야 한다. 이후 응답을 파싱하고 필수 필드·자료형·업무 규칙까지 검사하면, 자동화 과정에서 생기는 데이터 오류를 줄일 수 있다.

이 글은 설정과 구현 방법을 찾는 탐색형 검색 의도에 맞춰 구성했다. 2026년 11월 18일 확인한 Google 공식 문서를 기준으로, 스키마 정의부터 API 호출과 응답 검증까지 연결한다. 예제는 설명을 위한 주문 데이터이며, 실제 거래 기록이나 성능 통계가 아니다.

📌 핵심 요약

  • Interactions API에서는 response_format에 JSON MIME 유형과 스키마를 함께 지정한다.
  • Python은 Pydantic, JavaScript는 JSON.parse와 Zod를 이용해 응답을 검사한다.
  • JSON 구조가 맞아도 주문번호·금액·원문 일치 여부는 별도로 검증해야 한다.

1. JSON 프롬프트와 API 구조화 출력의 차이 이해하기

구조화 출력은 모델의 답변이 지정된 JSON Schema를 따르도록 API에서 설정하는 기능이다. “JSON으로만 답해 줘”라는 문장도 출력 방향을 안내하지만, 애플리케이션이 기대하는 데이터 구조를 API 설정으로 전달하는 것과는 다르다.

예를 들어 주문 정보를 추출할 때는 설명 문장이 섞이는 문제뿐 아니라, 수량이 문자열로 나오거나 필수 항목이 빠지는 문제도 고려해야 한다. 따라서 프롬프트에는 추출 기준을 쓰고, 스키마에는 필드와 자료형을 정의하는 방식이 관리하기 쉽다.

확인 항목 프롬프트로 JSON 요청 구조화 출력 설정
설정 위치 자연어 지시문 API의 응답 형식 설정
필수 필드 문장으로 요청 required로 명시
자료형 출력 예시나 설명으로 안내 integer·string 등으로 정의
허용값 선택지를 문장에 기재 enum으로 제한
사실 확인 별도 검증 필요 별도 검증 필요

Google은 2025년 11월 5일 JSON Schema 지원 확대를 발표했다. 이 발표에서 Gemini 2.5 이상 모델은 스키마에 정의된 키 순서를 출력에도 유지한다고 설명했다. 다만 저장·비교 로직은 키의 위치보다 이름을 기준으로 작성하는 편이 안정적이다. (출처: Google, 「Improving Structured Outputs in the Gemini API」, 2025년 11월 5일)

제미나이 API 응답을 JSON으로 받는 법: 구조화 출력 설정과 데이터 검증 순서

2. JSON Schema와 모델·SDK 버전 먼저 정하기

아래 예제의 모델 ID는 공식 구조화 출력 문서에 제시된 gemini-4-hydrogen이다. SDK는 Python google-genai==3.4.0, JavaScript @google/genai@3.1.0을 예제 기준으로 명시한다. 각각 Google 공식 변경 기록에서 확인되는 버전이며, 이 글에서 API 실행을 검증했다는 의미는 아니다.

Python SDK 3.4.0의 공개일은 2026년 11월 16일이고, JavaScript SDK 3.1.0은 2026년 11월 10일이다. SDK의 기본 API 버전도 주요 버전에서 바뀔 수 있으므로, 패키지 잠금 파일과 모델 ID를 함께 기록해야 재현 시 차이를 추적하기 쉽다. (출처: Google 공식 Python Gen AI SDK·JavaScript Gen AI SDK 변경 기록)

검증 라이브러리는 Pydantic 2 계열과 Zod 4 계열을 사용한다. API 키는 GEMINI_API_KEY 환경변수로 전달하고, 브라우저에 배포되는 코드에 직접 넣지 않는다. JavaScript 예제는 서버의 Node.js 환경에서 실행하는 구성을 전제로 한다.

필수 필드와 값의 제약을 나누어 설계하기

예제에서는 order_id, currency, quantity를 필수 항목으로 사용한다. 통화는 KRW만 허용하고 수량은 1 이상 100 이하의 정수로 정한다. 이 숫자는 API의 공통 제한이나 실제 통계가 아니라, 예제 서비스가 정한 업무 조건이다.

  • required: 필드의 존재 여부를 지정한다. 문자열이 비어 있지 않다는 뜻까지 포함하지 않는다.
  • enum: 통화나 상태처럼 허용할 값을 나열한다.
  • minimum·maximum: 숫자의 최솟값과 최댓값을 지정한다.
  • minItems·maxItems: 주문 상품 목록 같은 배열의 길이를 제한한다.

누락과 빈 값도 구분해야 한다. “반드시 존재하되 확인되지 않으면 null”과 “확인되지 않으면 필드를 생략”은 서로 다른 계약이다. 원문에 없는 값을 억지로 채우지 않도록, 실제 서비스에서는 미확인 값의 표현과 처리 경로를 먼저 정하는 것이 좋다.

3. Python으로 구조화 출력 요청하고 Pydantic 검증하기

Python 구현은 모델 정의 → 스키마 생성 → API 호출 → 응답 검증 순서로 읽으면 된다. 아래 코드는 공식 문서의 Interactions API 호출 형태를 바탕으로 주문 추출에 맞게 구성한 예제다.

# 설치: pip install "google-genai==3.4.0" "pydantic>=2,<3"
import os
from typing import Literal
from google import genai
from pydantic import BaseModel, ConfigDict, Field, ValidationError

class Order(BaseModel):
    model_config = ConfigDict(extra="forbid", strict=True)

    order_id: str
    currency: Literal["KRW"]
    quantity: int = Field(ge=1, le=100)

source_text = "주문번호 ORD-2026-001, 통화 KRW, 수량 2개"
known_order_ids = {"ORD-2026-001"}

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input=(
        "다음 원문에서 주문 정보를 추출하세요. "
        "주문번호를 임의로 수정하지 마세요.\n" + source_text
    ),
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Order.model_json_schema(),
    },
)

raw = interaction.output_text
if not raw:
    raise ValueError("검증할 응답 텍스트가 없습니다.")

try:
    order = Order.model_validate_json(raw)
except ValidationError as exc:
    raise ValueError("JSON 파싱 또는 스키마 검증 실패") from exc

if order.order_id not in known_order_ids:
    raise ValueError("업무 검증 실패: 등록되지 않은 주문번호")

print(order.model_dump())

model_json_schema()는 API에 전달할 스키마를 만들고, model_validate_json()은 반환된 JSON 문자열을 검사한다. 엄격한 자료형 검사를 설정했으므로 문자열 형태의 수량을 정상 정수로 조용히 바꾸는 동작도 피할 수 있다.

마지막 주문번호 검사는 별도의 업무 검증이다. 주문번호가 문자열이라는 사실만으로 실제 존재하는 주문임을 알 수는 없다. 운영 환경에서는 예제의 집합을 주문 데이터베이스 조회로 바꾸고, 로그인한 계정이 해당 주문에 접근할 권한이 있는지도 확인해야 한다.

4. JavaScript에서 JSON.parse와 Zod 검증 연결하기

JavaScript에서는 응답 문자열을 객체로 바꾸는 단계와 객체 구조를 검사하는 단계를 구분한다. JSON.parse()가 성공해도 필수 필드 누락이나 잘못된 자료형이 남을 수 있으므로, 이어서 Zod의 parse()를 호출한다.

// 설치: npm install @google/genai@3.1.0 zod@4
// 서버의 .mjs 파일에서 실행
import { GoogleGenAI } from "@google/genai";
import * as z from "zod";

const orderSchema = z.strictObject({
  order_id: z.string(),
  currency: z.enum(["KRW"]),
  quantity: z.number().int().min(1).max(100),
});
const jsonSchema = z.toJSONSchema(orderSchema);
const knownOrderIds = new Set(["ORD-2026-001"]);

const client = new GoogleGenAI({
  apiKey: process.env.GEMINI_API_KEY,
});

const interaction = await client.interactions.create({
  model: "gemini-4-hydrogen",
  input: "다음 주문 정보를 추출하세요: 주문번호 ORD-2026-001, 통화 KRW, 수량 2개",
  response_format: {
    type: "text",
    mime_type: "application/json",
    schema: jsonSchema,
  },
});

const raw = interaction.output_text;
if (!raw) {
  throw new Error("검증할 응답 텍스트가 없습니다.");
}

let parsed;
try {
  parsed = JSON.parse(raw);
} catch {
  throw new Error("JSON 문법 검증 실패");
}

const result = orderSchema.parse(parsed);

if (!knownOrderIds.has(result.order_id)) {
  throw new Error("업무 검증 실패: 등록되지 않은 주문번호");
}

console.log(result);

이 예제는 Zod 정의에서 요청용 JSON Schema를 생성해 두 정의가 달라질 여지를 줄였다. 다만 스키마 변환에 성공했다는 사실이 모든 제약을 API가 강제한다는 뜻은 아니다. API 지원 범위와 애플리케이션 검증 범위를 따로 확인해야 한다.

Python과 JavaScript 예제의 호출·검증 순서는 Google 공식 구조화 출력 문서를 따른다. 업무 검증과 엄격한 타입 설정은 예제 서비스의 요구에 맞춰 추가한 구현이다. (출처: Google AI for Developers, 「Structured outputs」, 2026년 11월 18일 확인)

5. JSON 형식 검사 이후 업무 규칙까지 검증하는 순서

형식 검증은 데이터를 읽을 수 있는지 확인하고, 업무 검증은 그 데이터를 사용해도 되는지 판단한다. 수량이 2라는 정수로 반환됐어도 원문 수량이 20이었다면 추출 결과는 잘못됐다. 구조화 출력을 도입할 때 가장 놓치기 쉬운 지점이 바로 이 차이다.

  1. 응답 상태 확인: 요청 성공 여부와 응답 텍스트 존재 여부를 확인한다. 중단되거나 비어 있는 결과를 정상 주문으로 넘기지 않는다.
  2. JSON 문법 검사: 문자열을 파싱한다. 스트리밍이라면 전체 객체가 완성된 뒤 최종 검증한다.
  3. 스키마 검사: 필수 필드, 자료형, 허용값, 숫자 범위와 추가 필드를 확인한다.
  4. 원문 대조: 주문번호·통화·수량이 입력 내용과 일치하는지 검사한다.
  5. 업무 규칙 검사: 주문 존재 여부, 처리 가능한 상태, 사용자 권한과 재고 조건을 조회한다.
  6. 저장 또는 보류: 모든 검사를 통과한 결과만 저장하고, 실패한 결과는 오류 유형에 맞게 분리한다.

실무 설계 관점에서는 모델에게 합계까지 계산하게 하는 것보다, 모델은 상품과 수량을 추출하고 애플리케이션이 가격표를 조회해 합계를 계산하도록 역할을 나누는 편이 검증하기 쉽다. 계산 규칙을 코드로 고정하면 가격 변경이나 반올림 기준도 일관되게 적용할 수 있다.

운영 지표 역시 “JSON 파싱 성공률” 하나로 끝내지 않는 것이 좋다. 스키마 통과 비율과 원문 대조 통과 비율을 따로 기록하면 형식 문제와 추출 정확도 문제를 구분할 수 있다. Google 문서에서 확인되지 않은 보편적인 정확도나 개선율을 가정하지 말고, 실제 입력을 대표하는 평가 데이터로 측정해야 한다.

6. 지원하지 않는 JSON Schema와 오류 처리 점검하기

Google의 구조화 출력은 JSON Schema 전체를 지원하지 않는다. 확인 시점의 공식 문서는 minLength, maxLength, uniqueItems 같은 일부 제약이 서버의 생성 제약으로 적용되지 않고 무시될 수 있다고 설명한다. 반면 배열 길이의 minItems와 maxItems는 적용 대상으로 구분한다. (출처: Google AI for Developers, 「Structured outputs」의 제한 사항)

또한 매우 크거나 깊은 스키마는 요청 단계에서 거부될 수 있다. 이런 경우 동일한 요청을 반복하기보다 중첩 구조를 평평하게 만들고, 불필요한 필드와 복잡한 분기를 줄이는 쪽으로 수정한다. 검증 실패를 없애기 위해 필요한 필드를 무작정 선택 사항으로 바꾸면 데이터 계약 자체가 느슨해질 수 있다.

💡 참고: 기존 generate_content 예제의 response_mime_type·response_json_schema와 이 글의 Interactions API response_format은 호출 방식이 다르다. 코드 일부를 섞기 전에 사용 중인 메서드와 SDK 버전을 먼저 확인해야 한다.

오류 처리는 원인에 따라 나눈다. 인증 실패는 키와 권한을, 스키마 거부는 요청 구조를, 일시적인 통신 장애는 재시도 정책을 점검한다. 의미가 잘못된 응답에는 재추출 횟수 제한이나 수동 검토 경로를 두고, 검증되지 않은 값을 그대로 저장하지 않는다.

  • 모델 ID와 실제 설치된 SDK 버전이 배포 기록에 남아 있는가?
  • 요청 스키마와 응답 검증기가 같은 필드 계약을 사용하는가?
  • 필수 항목 누락, 범위 밖 수량, 미등록 주문번호를 각각 처리하는가?
  • 스키마 통과 후에도 원문과 데이터베이스를 대조하는가?
  • 오류 기록에 API 키나 불필요한 개인정보가 포함되지 않는가?

제미나이 API의 JSON 응답을 안정적으로 활용하는 출발점은 작은 스키마와 명확한 검증 순서다. 구조화 출력으로 데이터 형태를 정하고, Pydantic 또는 Zod로 응답을 검사한 다음, 업무 데이터와 대조한 결과만 다음 처리 단계로 넘기면 된다.