사용 필드 및 출력 설명

​

전체 응답 구조

{
  "candidates":    [ ... ],          // generation results (image/text parts)
  "usageMetadata": { ... },          // token usage
  "modelVersion":  "gemini-3-pro-image",
  "responseId":    "..."
}

​

생성이 성공한 경우

"candidates": [{
  "content": {
    "role": "model",
    "parts": [
      { "inlineData": { "mimeType": "image/jpeg", "data": "<base64>" } }
    ]
  },
  "finishReason": "STOP",
  "index": 0
}]

​

안전 정책에 의해 차단된 경우

"candidates": [{
  "content": { "parts": null },        // ⚠️ parts is null, not an empty array
  "finishReason": "IMAGE_SAFETY",      // or NO_IMAGE / PROHIBITED_CONTENT
  "finishMessage": "Unable to show the generated image. ...",  // only present in some cases
  "index": 0
}]

• 테스트에서 세 가지 finishReason 값이 관찰되었습니다: IMAGE_SAFETY(출력 이미지가 정책을 위반함), PROHIBITED_CONTENT(금지된 사용 정책이 발동되었으며, 설명용 finishMessage가 함께 제공됨), 그리고 NO_IMAGE(이미지가 생성되지 않으며, 보통 몇 초 내에 반환됨).
• 거부 설명은 finishMessage 필드에 있습니다 — parts 내부의 텍스트 part로는 나타나지 않습니다.
• 파싱 코드는 parts가 null인 경우를 처리해야 하며, 그렇지 않으면 차단된 응답에서 크래시가 발생합니다.

​

usageMetadata 필드 의미

"usageMetadata": {
  "promptTokenCount": 615,          // total input tokens (text + input images)
  "candidatesTokenCount": 2478,     // total output tokens (images + internal generation tokens)
  "thoughtsTokenCount": 208,        // thinking (reasoning) tokens
  "totalTokenCount": 3301,          // total billed amount for this request
  "promptTokensDetails":     [ { "modality": "TEXT",  "tokenCount": 99 },
                               { "modality": "IMAGE", "tokenCount": 516 } ],
  "candidatesTokensDetails": [ { "modality": "IMAGE", "tokenCount": 2240 } ]
}

​

이상처럼 보이는 세 가지 동작

​

동작 1: candidatesTokenCount ≠ candidatesTokensDetails의 합 — 정상적이고 불가피합니다

​

동작 2: totalTokenCount ≠ prompt + candidates + thoughts — 이미지 출력이 없는 응답에서만

• 성공한 생성에서는 방정식이 엄격히 성립합니다(49/49): total = promptTokenCount + candidatesTokenCount + thoughtsTokenCount.
• 안전 차단된 응답(이미지 출력 없음)에서는 방정식이 절대 성립하지 않습니다(6/6), 고정 패턴은 다음과 같습니다:

candidatesTokenCount == thoughtsTokenCount     // thinking tokens are written into both fields
totalTokenCount == promptTokenCount + thoughtsTokenCount   // total counts them once — this is correct

​

동작 3: output tokens가 가끔 6000+에 도달함 — thinking process의 여러 이미지 파트 때문입니다

​

thinkingLevel이 tokens에 미치는 영향

​

추론 수준이 tokens에 미치는 영향

• high는 추론 tokens와 지연 시간만 증가시키며 — image tokens는 그대로 유지됩니다 (이미지당 여전히 1120입니다).
• thinkingLevel를 gemini-3-pro-image에 전달해도 오류는 발생하지 않지만, 측정 가능한 효과는 없습니다 — 추론 tokens는 기본 범위에 머뭅니다.
• 테스트에서 includeThoughts: true는 응답 구조도 과금도 바꾸지 않았습니다; Google은 추론 과정을 보든 보지 않든 추론 tokens가 기본적으로 과금된다고 명시합니다.
• Google은 또한 “최소 추론이라고 해서 모델이 아예 추론을 하지 않는다는 뜻은 아닙니다”라고 설명합니다 — minimal에서는 usage가 별도의 thoughtsTokenCount field를 더 이상 표시하지 않습니다.

​

이미지 모델의 추론 tokens가 텍스트 모델과 다른 점

• 텍스트 추론 모델: 추론 출력은 텍스트입니다; thoughtsTokenCount는 수천에 이를 수 있으며 output-token 가격으로 과금됩니다. 공식적으로는 API가 thought summaries만 반환하더라도 모델이 생성한 전체 내부 사고를 기준으로 과금이 산정됩니다(출처: ai.google.dev/gemini-api/docs/thinking의 과금 섹션).
• 이미지 추론 모델: 추론은 두 종류의 출력을 생성합니다 — thoughtsTokenCount에 계산되는 소량의 텍스트 추론(측정 결과: Pro에서는 최대 400, Flash에서는 high에서 약 800)과, 각 1120/2000 tokens로 과금되는 일반 중간 초안 이미지가 candidatesTokenCount에 반환됩니다. 따라서 이미지 모델에서의 “추론 비용”은 주로 image parts의 수로 드러나며, thoughtsTokenCount field에는 크게 나타나지 않습니다(위의 동작 3 참조).

​

두 가지 API 패러다임

​

파싱 및 정산 모범 사례

data = resp.json()
cand = (data.get("candidates") or [{}])[0]
parts = (cand.get("content") or {}).get("parts") or []   # handles parts=null

images = [p["inlineData"]["data"] for p in parts if "inlineData" in p]
if images:
    final_image = images[-1]                  # last one is the final version
else:
    reason = cand.get("finishReason")         # IMAGE_SAFETY / NO_IMAGE / PROHIBITED_CONTENT
    message = cand.get("finishMessage", "")   # may be empty

1. totalTokenCount와 과금을 정산합니다 (거절 응답에도 정확합니다); 세 개의 필드를 직접 합산하거나 세부 항목을 합산해서 검증하지 마십시오.
2. 파트를 순회하십시오 — 단일 이미지를 가정하지 마십시오; 이미지별 비즈니스 로직은 실제 inlineData 파트 수를 기준으로 해야 합니다.
3. 차단된 응답은 parts = null + HTTP 200으로 처리하고, finishReason에 따라 분기하십시오.
4. 단순 편집은 약 2225초가 걸립니다. 복잡한 작업(다중 이미지 응답)은 35142초가 걸리며, 이미지가 많을수록 더 오래 걸립니다. 클라이언트 타임아웃은 5분 이상으로 설정하십시오(프록시 계층이 있으면 그 시간도 포함).

​

관련 문서