오류

이 가이드에서는 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. 씬 수준의 prompts를 피하세요. 건물 전체, 도시 블록, 가구로 가득 찬 실내, 또는 풍경은 모델의 처리 용량을 초과할 가능성이 높습니다. 대신 단일 객체에 집중하세요.
4. 빽빽하게 반복되는 구조를 피하세요. 비계, 와이어 메시, 격자 패턴, 또는 많은 작은 항목이 쌓인 더미 같은 대상은 흔한 트리거입니다.

model_missing_uv

이 오류는 enable_original_uv가 true로 설정된 상태에서 텍스처 적용을 위해 모델을 업로드했지만, 모델에 UV 좌표가 없을 때 발생합니다. UV 좌표는 2D 텍스처가 모델의 3D 표면에 어떻게 감기는지를 정의합니다.

해결 방법:

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

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

model_insufficient_uv

이 오류는 모델에 UV 좌표가 있지만, 고품질 텍스처링을 하기에는 UV 커버리지가 너무 작을 때 발생합니다. 이는 적절한 언랩 없이 자리표시자 UV나 접힌 UV를 생성하는 3D 도구에서 내보낸 모델에서 흔히 발생합니다.

해결 방법:

• 원본 UV 레이아웃을 보존해야 하는 경우: 3D 소프트웨어에서 모델의 UV를 다시 언랩하세요. UV 아일랜드가 작은 영역에 접히지 않고 UV 공간 전체에 적절히 펼쳐져 있는지 확인하세요.
• 특정 UV 제어가 필요하지 않은 경우: enable_original_uv를 생략하거나 false로 설정하세요. 시스템이 새 UV 레이아웃을 자동으로 생성합니다. 단점은 원래의 심 배치를 잃게 된다는 점이지만, 자동 생성된 UV는 텍스처링에 적합한 커버리지를 갖습니다.

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. 입력을 검증하세요. 제출하기 전에 입력 이미지와 모델이 형식 요구 사항을 충족하는지 확인하세요.