이미지 API 오류 진단 가이드: GPT Image·Gemini·Qwen
이미지 생성 API 오류를 인증, 모델 권한, 요청 값, 할당량, 안전 차단, 시간 초과, 응답 파싱 단계로 나누어 진단합니다.
Ofox 
이미지 API 오류는 하나의 문제가 아닙니다. 인증, 모델 권한, 요청 파라미터, 할당량, 안전 정책, 공급자 용량, 클라이언트 시간 초과, 응답 파싱 중 어느 단계에서 실패했는지 먼저 찾으세요.
먼저 저장할 진단 정보
시간과 시간대:
호스트와 엔드포인트:
정확한 모델 ID:
HTTP 상태와 전체 오류 본문:
request ID와 재시도 헤더:
SDK와 버전:
생성 또는 편집:
참조 이미지 사용 여부:
크기, 품질, 형식, 배경:
처리 시간:
최소 요청에서 재현: yes/no공유하기 전에 API 키, 서명된 이미지 URL, 비공개 프롬프트와 원본 이미지를 제거하세요.
오류 코드로 실패 단계를 찾기
| 증상 | 주요 원인 | 첫 조치 |
|---|---|---|
400 / INVALID_ARGUMENT | 요청 형식 또는 미지원 기능 | 엔드포인트, 필드, 값, API 버전 수정 |
401 | 인증 정보 누락·형식 오류 | 실제 전송된 키 확인 |
403 / PERMISSION_DENIED | 프로젝트·모델 권한, 키 제한 | 계정과 전체 오류 본문 확인 |
404 / model_not_found | 모델 ID, 엔드포인트, 권한 | 오류가 지목한 리소스 확인 |
429 / RESOURCE_EXHAUSTED | RPM/IPM, 일일 한도, 지출 한도, 잔액 | 할당량 지표를 읽고 일시적일 때만 재시도 |
| 안전 차단, 이미지 없음 | 입력 또는 생성 결과 차단 | 차단 사유를 확인하고 입력 수정 |
500 / 503 | 공급자 장애 또는 용량 부족 | request ID 저장 후 제한적으로 재시도 |
504 / 연결 재설정 | 모델·게이트웨이·클라이언트 시간 제한 | 어느 구성 요소가 먼저 종료했는지 확인 |
HTTP 200이나 이미지 없음 | 응답 파싱 또는 기능 불일치 | url, b64_json, MIME, 알파 채널 확인 |
GPT Image 오류
Direct Images API인지 Responses의 image generation tool인지 기록하세요. 요청 본문은 서로 바꿔 쓸 수 없습니다. OpenAI 이미지 생성 문서와 비교합니다.
model_not_found에서는 전체 모델 ID, 호스트, 엔드포인트, 키를 소유한 프로젝트를 확인합니다. 카탈로그에 보인다는 사실만으로 모든 API 엔드포인트에서 호출 가능한 것은 아닙니다. 모델 ID·권한 진단을 따르세요.
size, quality, background, output_format은 모델별로 확인합니다. 투명 출력에는 png 또는 webp가 필요하며 jpeg는 알파 채널을 보존하지 못합니다. GPT Image 2.5 API 가이드와 투명 배경 진단을 참고하세요.
지연과 504는 클라이언트 제한 시간과 공급자 측 모델 오류를 분리해야 합니다. 처리 시간과 상태를 반환한 구성 요소를 기록합니다.
Gemini / Nano Banana 오류
GenerateContent는 HTTP 코드와 함께 gRPC 형태의 status와 details를 반환할 수 있습니다. GenerateContent 오류 표는 400, 402, 403, 404, 429, 503, 504를 구분합니다.
Interactions API에는 별도의 오류 형식이 있으며 rate_limit_exceeded, image_safety, image_prohibited_content, image_recitation, no_image 등을 사용합니다. 이 필드가 GenerateContent에도 있다고 가정하지 마세요.
429에서는 키가 속한 실제 프로젝트와 이름이 표시된 할당량 지표를 확인합니다. 무료 한도가 0이면 재시도로 해결되지 않습니다. 일시적 429, 408, 5xx만 공식 문제 해결 문서에 따라 처리합니다.
Qwen Image 오류
다음 표는 2026년 7월 23일 Ofox에서 진행한 Qwen Image 경로 테스트의 관찰 결과입니다.
| 증상 | 진단 | 조치 |
|---|---|---|
429 Requests rate limit exceeded | 체험 용량 또는 속도 제한 | 요청 직렬화, 백오프, 현재 경로 확인 |
b64_json이 None | URL 응답을 base64로 파싱 | 문서화된 두 응답 형식 처리 |
HTTP 200이나 참조 대상 없음 | 참조 이미지 필드가 무시됐을 가능성 | 결과에서 참조 일치 여부 검증 |
model_not_found | 오래되거나 사용할 수 없는 ID | 현재 카탈로그와 권한 확인 |
이 관찰은 특정 시점의 경로 테스트입니다. 모든 Alibaba 또는 게이트웨이 엔드포인트의 영구 사양으로 해석하지 마세요.
Grok Imagine, Seedream, FLUX
Grok 모델 별칭이 폐기되거나 다시 연결되면 HTTP 요청이 성공해도 결과가 바뀔 수 있습니다. 실제 제공 모델을 로그에 남기고 Grok Imagine 가이드와 마이그레이션 가이드를 확인하세요.
다른 이미지 모델은 문서의 최소 요청부터 시작합니다. 정확한 모델 ID를 사용하고 URL, base64, 비동기 task 중 무엇이 반환되는지 확인한 뒤 size, quality, reference image, edit, transparency를 하나씩 추가합니다. Ofox 이미지 API 문서를 시작점으로 사용할 수 있습니다.
재시도 판단
네트워크 중단, 일시적 408, 429, 500, 503만 횟수가 제한된 지수 백오프와 지터로 재시도합니다. 잘못된 파라미터, 키, 권한, 할당량 0, 잔액 부족, 안전 차단, 파서 오류는 원인을 수정해야 합니다.
SDK가 이미 재시도하는지도 확인하세요. 연결 종료나 시간 초과 뒤에는 작업 완료 여부가 불확실할 수 있습니다. task ID가 있으면 새 요청 전에 기존 task를 조회하고, idempotency는 해당 엔드포인트가 명시적으로 지원할 때만 사용합니다. 무조건 재시도하면 중복 이미지나 두 번째 과금 작업이 생길 수 있습니다.
관련 문제 해결 문서
| 증상 | 세부 가이드 |
|---|---|
| GPT Image 지연 또는 504 | GPT Image 2 오류 진단 |
| 투명 배경 미지원 | 투명 배경 오류 |
OpenAI model_not_found | 모델 ID·권한 진단 |
| Qwen 429 또는 URL/base64 불일치 | Qwen Image 경로 테스트 |
| 모든 공급자의 429 | 429 재시도 판단 가이드 |
출처
자주 묻는 질문
- 이미지 API 요청이 실패하면 무엇을 저장해야 하나요?
- 시간과 시간대, 호스트, 엔드포인트, 정확한 모델 ID, HTTP 상태, 비밀 정보를 제거한 전체 오류 본문, request ID, 관련 헤더, SDK와 버전, 입출력 설정, 처리 시간, 최소 요청에서 재현되는지를 저장합니다.
- 모든 429 이미지 API 오류를 재시도해야 하나요?
- 아닙니다. 일시적 속도 또는 용량 제한만 횟수가 제한된 지수 백오프와 지터로 재시도합니다. 할당량 0, 잔액 부족, 결제 비활성화는 설정이나 계정 상태를 먼저 해결해야 합니다.
- HTTP 200인데도 이미지를 사용할 수 없는 이유는 무엇인가요?
- API는 URL을 반환했지만 코드가 b64_json만 읽거나, 지원하지 않는 참조 이미지 필드가 무시되거나, 투명 채널이 없는 파일이 반환될 수 있습니다. 응답 필드와 실제 파일을 검증하세요.
- 이미지 모델을 바꾸면 오류가 해결되나요?
- 원인이 모델 기능, 접근 권한, 용량일 때만 도움이 됩니다. 누락된 키, 잘못된 엔드포인트, 비정상 요청, 파서 오류는 모델 교체로 해결되지 않습니다.
