오류

이 가이드에서는 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

이 오류는 Multi-Color Print 작업의 입력 모델에 컨버터가 프린트 색상으로 분리할 수 있는 색상 정보가 전혀 없을 때 발생합니다. 다색 프린트용 3MF는 모델의 색상을 바탕으로 생성되므로, 예를 들어 한 번도 텍스처링되지 않은 텍스트로 3D 또는 이미지로 3D 프리뷰나, 복구되거나 자동 분할된 출력물처럼 단순히 흰색뿐인 메시에는 작업할 대상이 없습니다.

무엇이 색상 소스로 간주되는지는 요청한 style에 따라 달라집니다:

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

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

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

해결 방법:

• 먼저 모델에 텍스처를 적용하세요. Retexture 작업을 실행하거나, 텍스처링이 활성화된 상태로 생성한 뒤(텍스트로 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

이 오류는 작업의 처리 시간이 허용된 한도를 초과했음을 의미합니다. 이는 시스템 부하가 높거나 입력이 시간 제한 내에 처리하기에 너무 복잡할 때 발생할 수 있습니다.

해결 방법:

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

format_conversion_failed

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

해결 방법:

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

모범 사례

1. 재시도 로직을 구현하세요. timeout 및 service_unavailable 오류의 경우, 지수 백오프 재시도 로직을 구현하세요.
2. 작업 ID를 기록하세요. 디버깅 목적으로 항상 작업 ID를 기록해 두세요. 지원팀에 문의할 때 이를 포함하세요.
3. 입력값을 검증하세요. 제출 전에 입력 이미지와 모델이 형식 요구 사항을 충족하는지 확인하세요.