오류

이 가이드에서는 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는 커버리지에 최적화되어 있지만, 텍스처 솔기(seam)가 배치되는 위치를 제어할 수는 없습니다.

model_insufficient_uv

이 오류는 모델에 UV 좌표가 있지만 UV 커버리지가 너무 작아 품질 좋은 텍스처링이 불가능할 때 발생합니다. 이는 제대로 된 언랩(unwrap) 없이 플레이스홀더 또는 축소된 UV를 생성하는 3D 도구로 내보낸 모델에서 흔히 발생합니다.

해결 방법:

• 원본 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를 수정하세요.
• 안전 필터를 유발할 수 있는 내용을 담고 있다면 참조 이미지를 조정하세요.

timeout

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

이는 사용자 자신의 코드에서 발생하는 timeout과는 다릅니다. 클라이언트가 대기를 중단했더라도 작업은 여전히 실행 중일 수 있습니다. Task Lifecycle을 참고하세요.

해결 방법:

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

format_conversion_failed

이 오류는 생성된 3D 모델을 요청한 출력 형식으로 변환할 수 없을 때 발생합니다. 모델 생성은 성공했지만 변환 단계에서 실패한 경우입니다.

해결 방법:

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

모범 사례

1. 재시도 로직을 구현하세요. 작업이 timeout, service_unavailable 또는 server_error 오류로 실패하면 지수 백오프를 적용해 다시 생성하세요. 만약 요청 자체가 타임아웃된 경우라면 새 작업을 생성하지 말고, 먼저 기존 작업을 확인하세요(작업 생명주기 참조).
2. 작업 ID를 기록하세요. 디버깅을 위해 항상 작업 ID를 기록해 두세요. 지원팀에 문의할 때 이를 포함해 주세요.
3. 입력 값을 검증하세요. 제출하기 전에 입력 이미지와 모델이 형식 요구사항을 충족하는지 확인하세요.