메인 콘텐츠로 건너뛰기

오류 응답 형식

작업이 실패한 경우 (status: "failed"), 응답에는 error 객체가 포함됩니다:
{
  "id": "task-unified-1772618027-cmeisy8h",
  "object": "image.generation.task",
  "status": "failed",
  "model": "gemini-3.1-flash-image-preview",
  "progress": 0,
  "error": {
    "code": "content_policy_violation",
    "message": "Content policy violation.\nYour request was blocked by safety filters..."
  }
}
필드유형설명
error.codestring오류 코드 식별자. 아래 전체 목록 참조
error.messagestring사용자 친화적인 오류 설명 및 문제 해결 팁

오류 코드 개요

클라이언트 오류 (사용자가 수정 가능)

오류 코드설명재시도
content_policy_violation콘텐츠가 안전 정책 위반콘텐츠 수정 후 재시도
invalid_parameters잘못된 요청 매개변수매개변수 수정 후 재시도
image_processing_error이미지 처리 실패다른 이미지 사용
image_dimension_mismatch이미지 크기가 요청과 불일치이미지 크기 조정 후 재시도
request_cancelled요청이 취소됨재제출
오류 코드설명재시도
generation_failed_no_content모델이 출력 생성 실패다른 프롬프트로 재시도
service_error내부 서비스 오류자동 복구, 나중에 재시도
generation_timeout작업 처리 시간 초과나중에 재시도
resource_exhausted업스트림 리소스 일시적 고갈자동 복구, 나중에 재시도
quota_exceeded속도 제한 또는 할당량 초과빈도 줄이고 나중에 재시도
service_unavailable서비스 일시적 사용 불가자동 복구, 나중에 재시도
resource_not_found작업 ID 유효하지 않거나 만료됨작업 ID 확인
unknown_error분류되지 않은 오류지원팀 문의

오류 코드 세부 사항

content_policy_violation

콘텐츠 정책 위반

요청이 안전 필터에 의해 차단되었습니다. 이것은 가장 일반적인 오류 유형으로 다음 시나리오를 포함합니다:
일반적인 트리거:
하위 유형설명메시지 예시
사실적 인물업로드된 이미지에 실제 사람 얼굴 포함photorealistic people detected
유명인 초상유명인 또는 공인 관련celebrity detected in image
저작권/상표브랜드 로고, 상표 또는 저작권 보호 IP 관련third-party content violation
성인/NSFW누드 또는 성적 암시 콘텐츠 포함nudity detected
폭력/자해폭력적, 노골적 또는 자해 콘텐츠 포함violence content blocked
미성년자 보호미성년자 관련 민감한 콘텐츠minor content not allowed
일반 정책기타 콘텐츠 정책 위반content policy violation
피하는 방법:
  • 실제 인물 사진 업로드 피하기 — 일러스트 또는 만화 스타일 사용
  • 브랜드 로고, 상표 및 저작권 보호 IP 캐릭터 제거
  • 성인, 폭력 또는 자해 테마 피하기
  • 특정 유명인 대신 일반적인 캐릭터 설명 사용 (예: “a person”)

generation_failed_no_content

생성 실패

모델이 요청에 대한 출력을 생성할 수 없었습니다. 요청 형식은 유효했지만 처리 중에 모델이 결과를 생성하지 못했습니다.
일반적인 원인:
  • 프롬프트 품질 부족: 설명이 너무 모호하거나 모순되어 모델이 이해할 수 없음
  • 모델 능력 한계: 프롬프트가 모델의 생성 능력을 초과
  • 업스트림 서비스 문제: 기본 모델 서비스가 빈 결과를 반환
  • 보호된 콘텐츠 감지: 프롬프트 또는 참조 이미지에 워터마크 제거 또는 보호된 콘텐츠(로고, 상표 등)가 포함될 수 있음
수정 방법:
  • 프롬프트를 더 명확하고 구체적으로 조정
  • 다른 참조 이미지 사용 — 워터마크나 로고가 있는 이미지 피하기
  • 요청 단순화 (해상도 또는 복잡성 낮추기)
  • 단순히 재시도 — 일부 경우 재시도 시 성공

invalid_parameters

잘못된 매개변수

요청 매개변수가 모델 요구사항을 충족하지 않습니다.
일반적인 하위 유형:
하위 유형설명예시
프롬프트가 너무 긺프롬프트가 모델의 최대 길이 초과Prompt is too long
이미지 크기이미지 너비/높이 또는 화면 비율이 범위 밖image dimensions must be between 240 and 7680
파일이 너무 큼업로드 파일이 크기 제한 초과file size exceeds 10MB
지원되지 않는 형식업로드 파일 형식이 지원되지 않음unsupported file type
비디오 길이비디오 길이가 모델의 지원 범위 밖Video duration must be between 1-30 seconds
수정 방법:
  • 모델별 API 문서에서 매개변수 요구사항 확인
  • 지원 이미지 형식: JPG, PNG, WebP, GIF (HEIC, AVIF, TIFF는 미지원)
  • 이미지 크기 제한: 일반적으로 < 10MB, 일부 모델 < 30MB
  • 프롬프트를 줄이거나 긴 프롬프트를 핵심 설명으로 분할

image_processing_error

이미지 처리 실패

시스템이 입력 이미지를 처리할 수 없었습니다.
일반적인 원인:
  • 이미지 URL에 접근할 수 없음 (인증 필요, CDN 제한, 만료된 링크)
  • 이미지 형식이 지원되지 않음 (예: HEIC, AVIF)
  • 이미지 파일 손상
  • 네트워크 문제로 이미지 다운로드 실패
수정 방법:
  • 이미지 URL이 인증이나 지역 제한 없이 공개적으로 접근 가능한지 확인
  • 표준 형식 사용: JPG, PNG, WebP
  • URL 대신 파일 업로드 API 사용 시도
  • 이미지가 브라우저에서 올바르게 열리는지 확인

image_dimension_mismatch

이미지 크기 불일치

입력 이미지의 크기가 요청에 지정된 크기와 일치하지 않습니다. 이미지에서 비디오로 변환하는 시나리오에서 흔히 발생합니다.
예시:
  • aspect_ratio=1280x720 (16:9) 시 1280x720 가로 이미지 필요
  • aspect_ratio=720x1280 (9:16) 시 720x1280 세로 이미지 필요
수정 방법: 요청한 aspect_ratio 매개변수에 맞게 이미지 크기를 조정하거나, 이미지에 맞게 aspect_ratio를 변경하세요.

service_error

서비스 오류

업스트림 서비스에서 내부 문제가 발생했습니다. 일반적으로 일시적이며 시스템이 자동으로 다른 사용 가능한 경로로 전환합니다.
일반적인 원인:
  • 업스트림 모델 서비스 일시적 사용 불가
  • 서버 과부하 / 높은 트래픽
  • 유지보수 진행 중
  • 네트워크 연결 중단
수정 방법:
  • 30-60초 기다린 후 재시도 — 시스템은 보통 자동으로 복구됩니다
  • 지속될 경우 기술 지원에 문의
  • 요청을 수정할 필요 없음 — 동일한 요청을 재시도

generation_timeout

생성 시간 초과

작업이 허용된 시간 내에 완료되지 않았습니다.
일반적인 원인:
  • 시스템 부하가 높아 대기열 지연 발생
  • 작업 복잡성이 높음 (고해상도, 긴 비디오 등)
  • 업스트림 서비스 응답이 느림
수정 방법:
  • 나중에 재시도, 가급적 비수기 시간에
  • 작업 복잡성 줄이기: 해상도 낮추기, 비디오 길이 줄이기
  • 프롬프트 설명 단순화

quota_exceeded

할당량 / 속도 제한 초과

요청 빈도 또는 동시성 제한을 초과했습니다.
일반적인 원인:
  • 짧은 시간에 너무 많은 요청 전송 (속도 제한)
  • 여러 작업이 동시에 처리 중 (동시성 제한)
  • 계정 할당량 고갈
수정 방법:
  • 요청 빈도 줄이기 — 요청 간 1-2초 간격 권장
  • 진행 중인 작업이 완료될 때까지 새 작업 제출 대기
  • 할당량이 고갈된 경우 결제 페이지에서 충전

resource_exhausted

리소스 고갈

업스트림 서비스의 컴퓨팅 리소스가 일시적으로 고갈되었습니다. 일반적으로 모델 사용 피크 기간에 발생합니다.
수정 방법:
  • 1-5분 기다리면 자동 복구
  • 시스템이 여러 경로 간 자동 전환 — 나중에 재시도하면 보통 성공

resource_not_found

리소스를 찾을 수 없음

요청한 작업 ID가 존재하지 않거나 만료되었습니다.
수정 방법:
  • 작업 ID 철자가 올바른지 확인
  • 작업 결과에는 만료 기간이 있음 — 만료된 작업은 조회 불가
  • ID가 정확하면 잠시 기다린 후 재시도

request_cancelled

요청 취소됨

작업이 처리 중에 취소되거나 중단되었습니다.
의도적으로 취소하지 않았다면 동일한 요청을 다시 제출하면 됩니다.

service_unavailable

서비스 사용 불가

내부 인증 또는 연결 문제가 발생했습니다. 이 오류는 자동으로 기록되며 일반적으로 빠르게 해결됩니다.
수정 방법:
  • 몇 분 기다린 후 재시도
  • 지속될 경우 작업 ID와 함께 기술 지원에 문의

unknown_error

알 수 없는 오류

분류되지 않은 오류. 시스템이 특정 오류 유형을 식별할 수 없었습니다.
수정 방법:
  • 잠시 후 재시도
  • 문제가 지속되면 전체 작업 ID와 함께 기술 지원에 문의

모범 사례

오류 처리 예시

import requests
import time

def poll_task_with_retry(task_id, api_key, max_retries=3):
    """Poll task status with automatic retry for server errors"""
    headers = {"Authorization": f"Bearer {api_key}"}

    for attempt in range(max_retries):
        resp = requests.get(
            f"https://api.evolink.ai/v1/tasks/{task_id}",
            headers=headers
        )
        data = resp.json()

        if data["status"] == "completed":
            return data["results"]

        if data["status"] == "failed":
            error = data.get("error", {})
            code = error.get("code", "unknown_error")
            message = error.get("message", "")

            # Client errors — not retryable, fix the request
            if code in [
                "content_policy_violation",
                "invalid_parameters",
                "image_processing_error",
                "image_dimension_mismatch",
            ]:
                raise Exception(f"Client error [{code}]: {message}")

            # Server errors — retryable
            if code in [
                "generation_failed_no_content",
                "service_error",
                "generation_timeout",
                "resource_exhausted",
                "quota_exceeded",
            ]:
                if attempt < max_retries - 1:
                    wait = 2 ** attempt * 5  # 5s, 10s, 20s
                    time.sleep(wait)
                    continue
                raise Exception(f"Server error [{code}]: {message}")

            raise Exception(f"Error [{code}]: {message}")

        # Task still processing
        time.sleep(3)

    raise Exception("Max polling attempts exceeded")

재시도 가능 vs 재시도 불가

요청 수정 후 재시도

  • content_policy_violation — 콘텐츠 수정
  • invalid_parameters — 매개변수 수정
  • image_processing_error — 다른 이미지 사용
  • image_dimension_mismatch — 이미지 크기 조정

직접 재시도 가능

  • generation_failed_no_content — 다른 프롬프트로 재시도
  • service_error — 대기 후 재시도
  • generation_timeout — 대기 후 재시도
  • resource_exhausted — 자동 복구
  • quota_exceeded — 빈도 줄이고 재시도