오류

이 가이드에서는 Meshy API를 사용하는 도중 문제가 발생했을 때 어떤 일이 일어나는지에 대해 설명합니다.

요청 오류

이러한 오류는 API 요청이 거부될 때 즉시 반환됩니다. 무엇이 잘못되었는지 파악하려면 HTTP 상태 코드와 message 필드를 확인하세요.

{
  "message": "Invalid model file extension: .3dm"
}

작업 오류

이 오류는 작업이 생성되어 처리 중인 이후에 발생합니다. 오류 세부 정보는 작업 응답의 task_error 객체를 확인하세요.

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "invalid_input",
    "code": "image_too_complex",
    "message": "The uploaded image is too complex for 3D generation.",
    "doc_url": "https://docs.meshy.ai/en/api/errors#image-too-complex"
  }
}

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "server_error",
    "message": "An internal error occurred. Please retry."
  }
}

오류 유형

type 필드는 실패의 큰 범주를 알려줍니다. 이를 사용하여 재시도 전략을 결정하세요.

오류 코드

code 필드가 존재하면 특정하고 조치 가능한 문제를 식별합니다. 아래는 각 오류 코드에 대한 전체 참조입니다.

image_too_complex

이 오류는 입력 이미지 또는 prompt가 3D 생성 모델이 처리하기에 기하학적으로 너무 복잡한 피사체를 설명할 때 발생합니다.

일반적인 예시는 다음과 같습니다:

• 작은 물체들이 빽빽하게 쌓인 더미 (예: 과일로 가득 찬 상자, 책 더미)
• 복잡하게 반복되는 패턴 (예: 격자 구조, 비계, 철망 메시)
• 복잡한 건물 구조 (예: 창문과 발코니가 많은 다층 건물)
• 하나의 피사체가 아닌 여러 개의 별개 객체가 포함된 이미지

너무 복잡할 가능성이 높은 입력 예시:

해결 방법:

1. 이미지당 하나의 객체만 사용하세요. 모델은 명확한 피사체 하나일 때 가장 잘 작동합니다. 같은 이미지나 prompt에 여러 개의 별개 객체를 포함하지 마세요.
2. 피사체를 단순화하세요. 세부 묘사의 수준을 줄이세요. 예를 들어, 수십 송이의 꽃으로 가득 찬 꽃병 대신 단순한 꽃병을 사용하세요.
3. 씬 단위의 prompt를 피하세요. 건물 전체, 도시 블록, 가구로 가득 찬 실내, 또는 풍경은 모델의 처리 용량을 초과할 가능성이 높습니다. 대신 단일 객체에 집중하세요.
4. 촘촘하게 반복되는 구조를 피하세요. 비계, 철망 메시, 격자 패턴, 또는 작은 물체가 많이 쌓인 더미와 같은 피사체는 흔히 문제를 일으키는 요인입니다.

model_missing_uv

이 오류는 enable_original_uv가 true로 설정된 상태에서 텍스처링할 모델을 업로드했지만, 모델에 UV 좌표가 없는 경우에 발생합니다. UV 좌표는 2D 텍스처가 모델의 3D 표면에 매핑되는 방식을 정의합니다.

해결 방법:

올바른 해결 방법은 enable_original_uv를 true로 설정한 이유에 따라 달라집니다:

• 모델의 원본 UV 레이아웃을 유지해야 하는 경우 (예: 정밀한 텍스처 매핑을 위한 커스텀 심(seam) 배치): 모델에 유효한 UV 좌표가 있어야 합니다. 업로드하기 전에 사용 중인 3D 소프트웨어의 UV 에디터에서 UV가 존재하는지 확인하세요. STL 파일은 UV 데이터를 저장할 수 없으므로, 대신 GLB, FBX 또는 OBJ를 사용하세요.
• 특정 UV 제어가 필요하지 않은 경우 (또는 확실하지 않은 경우): enable_original_uv를 생략하거나 false로 설정하세요. 시스템이 모델에 대한 UV 레이아웃을 자동으로 생성합니다. 자동 생성된 UV는 커버리지에 최적화되어 있지만, 텍스처 심의 위치를 직접 제어할 수는 없습니다.

model_insufficient_uv

이 오류는 모델에 UV 좌표가 있지만 UV 커버리지가 너무 작아 품질 좋은 텍스처링이 어려운 경우 발생합니다. 이는 3D 도구에서 내보낸 모델이 적절한 언래핑 없이 플레이스홀더 또는 축소된 UV를 생성하는 경우 흔히 발생합니다.

해결 방법:

• 원본 UV 레이아웃을 유지해야 하는 경우: 3D 소프트웨어에서 모델의 UV를 다시 언래핑하세요. UV 아일랜드가 작은 영역에 뭉쳐있지 않고 UV 공간 전체에 제대로 펼쳐지도록 하세요.
• 특정 UV 제어가 필요하지 않은 경우: enable_original_uv를 생략하거나 false로 설정하세요. 시스템이 자동으로 새 UV 레이아웃을 생성합니다. 이 경우 원본 솔기(seam) 배치를 잃게 되지만, 자동 생성된 UV는 텍스처링에 적합한 커버리지를 가지게 됩니다.

model_missing_texture

이 오류는 다색 프린트 작업의 입력 모델에 변환기가 프린트 색상으로 분리할 수 있는 색상 정보가 전혀 없을 때 발생합니다. 다색 3MF는 모델의 색상을 기반으로 생성되므로, 예를 들어 텍스처가 입혀진 적 없는 텍스트로 3D 또는 이미지로 3D 프리뷰나, 복구 / 자동 분할 출력물처럼 단순한 흰색 메시에는 사용할 수 있는 재료가 없습니다.

색상 소스로 인정되는 것은 요청한 style에 따라 달라집니다:

• realistic은 모델의 UV를 통해 베이스 컬러 텍스처를 샘플링하므로, 모든 메시 부분에 UV 좌표가 포함된 단일 베이스 컬러 텍스처가 필요합니다.
• cartoon은 면 단위로 색상을 단순화하며, 어느 부분에든 베이스 컬러 텍스처가 있거나 또는 정점별 색상(COLOR_0)이 있으면 받아들입니다.

베이스 컬러 텍스처도 정점 색상도 없는 모델은 두 스타일 모두에서 거부됩니다. cartoon의 경우 그렇지 않으면 단색 프린트로 "성공"해 버리기 때문입니다.

대부분의 요청은 작업이 생성되기 전에 거부되며(400 Bad Request와 동일한 설명과 함께), 따라서 입력을 사전에 검사할 수 없었던 경우에만 이 코드를 보게 되는 것이 일반적입니다 — 예를 들어 .fbx 업로드는 작업이 이를 정규화한 이후에 검사됩니다.

해결 방법:

• 먼저 모델에 텍스처를 입히세요. 모델에 대해 리텍스처 작업을 실행하거나, 텍스처링이 활성화된 상태로 생성(텍스트로 3D refine 작업, 또는 should_texture: true인 이미지로 3D 작업)한 뒤, 해당 작업을 input_task_id로 전달하세요.
• 정점 색상이 있는 모델(포토그래메트리 스캔, 수작업으로 색칠한 메시): COLOR_0을 읽는 style: "cartoon"을 요청하세요.
• realistic 환경에서 부분적으로 텍스처가 입혀졌거나 다중 텍스처인 모델: 모든 메시 부분에 UV와 동일한 단일 베이스 컬러 텍스처가 필요합니다. 나머지 부분에 텍스처를 입히거나 텍스처들을 하나의 아틀라스로 병합하거나, style: "cartoon"으로 전환하세요.

invalid_input

입력값이 유효성 검사를 통과하지 못했지만 더 구체적인 코드가 적용되지 않을 때 사용되는 기본 오류 코드입니다. message 필드에는 실패의 구체적인 원인이 담겨 있습니다.

일반적인 원인은 다음과 같습니다:

• 비어 있거나 손상된 모델 파일
• 지원되지 않는 파일 형식 변형(예: ASCII FBX 파일, meshopt로 압축된 GLB)
• 업로드한 모델에서 유효한 3D 객체를 찾을 수 없음(예: 파일에 아마추어, 카메라 또는 조명만 포함된 경우)
• 안전성 필터를 통과하지 못한 콘텐츠

해결 방법: 무엇이 잘못되었는지 자세히 알아보려면 message 필드를 확인하세요. 입력 파일과 매개변수가 엔드포인트의 요구 사항과 일치하는지 확인하세요.

moderation_blocked

이 오류는 prompt 또는 참조 이미지가 AI 안전 필터에 의해 거부될 때 발생합니다. 필터는 텍스트 prompt와 참조 이미지를 함께 평가합니다.

해결 방법:

• 선정적이거나 민감한 표현을 제거하도록 텍스트 prompt를 수정하세요.
• 안전 필터를 유발할 수 있는 내용을 담고 있다면 참조 이미지를 조정하세요.

moderation_unavailable

이 오류는 콘텐츠 moderation이 일시적으로 사용할 수 없어, 검사 없이 작업을 실행하는 대신 작업이 실패 처리될 때 발생합니다. 콘텐츠 자체에는 문제가 없습니다. 이 오류의 type은 server_error입니다.

해결 방법: 작업을 다시 생성하세요.

timeout

이 오류는 작업이 처리 또는 대기열 대기에 대한 서버 측 시간 제한을 초과했음을 의미하며, 이로 인해 작업이 실패하고 크레딧이 환불되었습니다. 이는 시스템 부하가 높거나 입력이 너무 복잡하여 시간 제한 내에 처리할 수 없을 때 발생할 수 있습니다.

이는 사용자 측 코드에서 발생하는 timeout과는 다릅니다. 클라이언트가 대기를 중단했더라도 작업은 계속 실행 중입니다. Task Lifecycle을 참고하세요.

해결 방법:

1. 작업을 다시 생성하세요. timeout은 일시적인 경우가 많으며, 새로운 작업은 성공할 수 있습니다.
2. 입력을 단순화하세요. 재시도가 계속 실패한다면 입력이 너무 복잡할 수 있습니다. 이미지나 prompt의 세부 수준을 줄여보세요. 처리하기 어려운 입력 유형에 대한 안내는 image_too_complex를 참고하세요.

queue_timeout

이 에러는 작업이 큐에서 너무 오래 대기하다가 시작되지 못해 실패했음을 의미하며, 이로 인해 차감된 크레딧은 모두 반환됩니다. 입력값으로 인해 발생한 문제가 아닙니다. type은 timeout입니다.

해결 방법: 작업을 다시 생성하세요.

format_conversion_failed

이 에러는 생성된 3D 모델을 요청한 출력 형식으로 변환하지 못했을 때 발생합니다. 모델 생성 자체는 성공했지만 변환 단계에서 실패한 경우입니다.

해결 방법:

1. 요청을 재시도하세요.
2. 다른 출력 형식을 시도하세요. 특정 형식에서 계속 실패한다면 필요에 맞는 다른 형식으로 전환하세요.

모범 사례

1. 재시도 로직을 구현하세요. 작업이 timeout, service_unavailable 또는 server_error 오류로 실패하면 지수 백오프(exponential backoff)를 적용하여 다시 생성하세요. 대신 요청 자체가 timeout된 경우에는 새 작업을 생성하지 말고, 기존 작업을 먼저 확인하세요(작업 수명 주기 참조).
2. 작업 ID를 기록하세요. 디버깅 목적으로 항상 작업 ID를 기록하세요. 지원팀에 문의할 때 이를 포함하세요.
3. 입력값을 검증하세요. 제출하기 전에 입력 이미지와 모델이 형식 요구사항을 충족하는지 확인하세요.
4. 서버에서 API를 호출하세요. 브라우저에서 실행되는 코드는 페이지를 여는 모든 사람에게 API 키를 노출시킵니다.