오류

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

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