Nano Banana 오류 해결

파라미터 허용 값은 Nano Banana 이미지 생성과 크기를 참고하십시오.

증상별로 찾기

400 Request contains an invalid argument

{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT"
  }
}

이 오류는 어떤 파라미터가 문제인지 알려 주지 않습니다. 실측 결과 다음 경우 모두 이 오류가 반환되었습니다.

확인 방법: 먼저 imageConfig를 제거하고 다시 시도하십시오. 정상적으로 생성되면 비율이나 해상도가 원인이므로, 항목을 하나씩 다시 추가하며 원인을 찾으십시오.

비율 또는 해상도 불일치

먼저 출력 이미지의 실제 너비와 높이를 확인한 다음 아래 표와 대조하십시오.

올바른 작성법:

{
  "contents": [{ "parts": [{ "text": "..." }] }],
  "generationConfig": {
    "responseModalities": ["IMAGE"],
    "imageConfig": { "aspectRatio": "9:16", "imageSize": "2K" }
  }
}

imageConfig / image_config, aspectRatio / aspect_ratio는 두 가지 표기 모두 인식됩니다. 실측 결과 image_config: { aspect_ratio: "9:16" }으로 768×1376이 올바르게 출력되었습니다.

응답에 이미지가 없음

Cherry Studio, LobeHub 등의 클라이언트에서 사용할 때는 채팅 모델이 아닌 이미지 생성 모델로 추가하십시오.

410 model_deprecated

{
  "error": {
    "message": "Model 'google/gemini-3-pro-image-preview' is deprecated and no longer accepts requests; please switch to an active model",
    "type": "model_deprecated",
    "code": 410
  }
}

-preview로 끝나는 이전 ID는 지원이 종료되었으므로 정식 버전 ID로 바꾸십시오.

네이티브 API 경로의 모델 ID에는 google/ 접두사를 붙여도 되고 생략해도 되며, 실측 결과 둘 다 정상적으로 호출되었습니다.

편집 결과가 원본 이미지와 무관함

참고 이미지가 읽혔는지 확인하는 방법: 네이티브 API에서는 usageMetadata.promptTokensDetails에 IMAGE 항목이 있는지, OpenAI 호환 API에서는 usage.input_tokens_details.image_tokens를 확인하십시오. 실측 결과 1024×1024 참고 이미지 한 장이 1,120 토큰으로 계산되었습니다.

안전 차단

요청이 안전 정책에 의해 차단되면 응답에 이미지가 포함되지 않으며, 원인은 finishReason 또는 promptFeedback.blockReason에 기록됩니다. 각 값의 의미는 다음과 같습니다(Google 공식 정의 기준).

코드에서 응답에 항상 이미지가 있다고 가정하지 마십시오. 먼저 candidates가 있는지, finishReason이 STOP인지 확인한 뒤 inlineData를 읽으십시오. 각 필드의 정의는 Gemini API · FinishReason 을 참고하십시오.

타임아웃, 504, 524

API는 동기 방식이며, 실측 결과 1K는 약 5~20초, 4K는 약 30초가 걸렸고 혼잡 시간대에는 더 오래 걸립니다. 흔히 쓰이는 60초 기본 타임아웃으로는 부족합니다.

• 클라이언트 타임아웃을 300초 이상으로 설정하십시오.
• Nginx, Vercel, Cloudflare 등 중간 프록시의 타임아웃 설정을 확인하십시오. 기본값은 대개 60~100초에 불과합니다.
• 4K PNG는 약 16 MB이며 응답 본문은 20 MB를 넘습니다. 프록시가 큰 응답을 잘라내지 않는지 확인하십시오.

클라이언트가 먼저 연결을 끊어도 요청은 과금됩니다.

기타 오류

기술 지원에 문의할 때는 응답의 request_id와 전체 오류 메시지를 함께 보내 주십시오.

자주 묻는 질문