오류

요청이나 작업이 실패한 이유와 다음에 무엇을 해야 하는지 알아보세요. 요청은 HTTP 오류와 함께 즉시 실패할 수 있으며, 작업은 이후에 task_error와 함께 실패할 수 있습니다.

요청 오류

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

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

작업 오류

Meshy가 생성한 작업은 실행 중에도 실패할 수 있습니다. 이 경우 status가 FAILED로 바뀌고, Meshy는 해당 크레딧을 환불하며, 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 생성에 비해 기하학적으로 너무 복잡한 대상을 설명하고 있습니다.

예를 들면:

• 과일이 가득한 상자나 쌓인 책 더미처럼 작은 물체가 빽빽하게 쌓인 경우
• 격자 구조, 비계, 철망 등 복잡하게 반복되는 패턴
• 창문과 발코니가 많은 다층 건물과 같은 복잡한 건축물
• 하나의 대상이 아니라 한 이미지에 여러 개의 별개 사물이 있는 경우

다음과 같은 입력은 너무 복잡할 가능성이 높습니다:

이 문제를 해결하려면 다음 중 하나 이상을 시도해 보세요:

• 이미지 하나당 사물 하나만 사용하세요. Meshy는 명확한 대상이 하나일 때 가장 잘 작동하므로, 여러 개의 별개 사물을 같은 이미지나 prompt에 넣지 마세요.
• 대상을 단순화하세요. 예를 들어, 수십 송이의 꽃으로 가득 찬 꽃병 대신 단순한 꽃병을 사용하세요.
• 장면은 피하세요. 건물 전체, 도시 블록, 가구가 배치된 방, 풍경 등은 너무 복잡할 가능성이 높습니다. 하나의 사물에 집중하세요.
• 빽빽하게 반복되는 구조는 피하세요. 비계, 철망, 격자, 작은 물건 더미는 흔히 문제를 일으키는 요소입니다.

model_missing_uv

enable_original_uv를 true로 설정하여 텍스처링을 위한 모델을 전송했지만, 모델에 UV 좌표가 없습니다. UV 좌표는 2D 텍스처가 3D 표면에 어떻게 입혀지는지를 정의합니다.

이를 해결하려면 다음 중 하나를 수행하세요:

• 사용자 지정 심(seam) 배치 등을 위해 모델 고유의 UV 레이아웃을 유지하려면, 3D 소프트웨어에서 모델에 UV를 추가하세요. 해당 소프트웨어의 UV 에디터에서 확인한 후, 모델을 다시 업로드하세요. STL 파일은 UV를 저장할 수 없으므로 GLB, FBX 또는 OBJ를 사용하세요.
• 자신만의 레이아웃이 필요하지 않거나 확실하지 않다면, enable_original_uv를 생략하거나 false로 설정하세요. 그러면 Meshy가 모델에 맞는 UV 레이아웃을 생성합니다. 새로운 UV는 모델을 잘 덮지만, 텍스처 심이 어디에 위치할지는 제어할 수 없습니다.

model_insufficient_uv

모델에 UV 좌표가 있지만, 텍스처를 제대로 적용하기에는 UV 공간을 차지하는 비중이 너무 적습니다. 익스포터가 제대로 된 언랩 없이 플레이스홀더 UV나 뭉쳐진 UV를 생성한 모델에서 자주 발생합니다.

이를 해결하려면 다음 중 하나를 수행하세요:

• 자신만의 UV 레이아웃을 유지하려면, 3D 소프트웨어에서 모델의 UV를 다시 언랩하세요. 아일랜드를 UV 공간의 작은 한쪽 구석이 아니라 전체에 걸쳐 고르게 펼치세요.
• 자신만의 레이아웃이 필요하지 않다면, enable_original_uv를 생략하거나 false로 설정하세요. 그러면 Meshy가 새로운 UV 레이아웃을 생성합니다. 기존 솔기(seam) 배치는 잃게 되지만, 새 UV는 텍스처를 적용하기에 충분한 공간을 차지하게 됩니다.

model_missing_texture

다색 프린트 작업의 입력 모델에 Meshy가 프린트 색상으로 분할할 수 있는 색상이 없습니다. Meshy는 모델의 색상으로 다색 3MF를 생성하므로, 단색 흰색 메시로는 작업할 것이 없습니다. 예를 들어, 텍스처가 적용된 적 없는 텍스트로 3D 또는 이미지로 3D 미리보기에는 색상이 없습니다. 프린팅 가능성 복구의 출력물이나, 텍스처를 유지하지 않은 Auto Split 작업도 마찬가지입니다.

무엇이 색상으로 간주되는지는 요청한 style에 따라 다릅니다:

• realistic은 모델의 UV를 통해 베이스 컬러 텍스처를 샘플링합니다. 단일 베이스 컬러 텍스처와, 모든 메시 부분에 UV가 필요합니다.
• cartoon은 면 단위로 색상을 평탄화합니다. 어느 부분에든 있는 베이스 컬러 텍스처 또는 버텍스별 색상(COLOR_0)을 받아들입니다.

Meshy는 두 스타일 모두에 대해 베이스 컬러 텍스처도 버텍스 색상도 없는 모델을 거부하며, cartoon이 이를 단색 프린트로 변환하도록 두지 않습니다.

Meshy는 이러한 요청 대부분을 작업을 생성하기 전에 400과 동일한 설명과 함께 거부합니다. 이 코드는 보통 Meshy가 입력을 사전에 확인할 수 없는 경우에만 받게 됩니다. 예를 들어, Meshy는 .fbx 업로드를 작업이 이를 변환한 후에만 확인합니다.

이를 해결하려면 모델에 맞는 옵션을 사용하세요:

• 먼저 모델에 텍스처를 적용하세요. 리텍스처를 실행하거나, 텍스트로 3D refine 작업 또는 should_texture: true가 설정된 이미지로 3D 작업으로 생성하세요. 그런 다음 해당 작업을 input_task_id로 전송하세요.
• 포토그래메트리 스캔이나 수작업으로 색칠된 메시처럼 버텍스 색상이 있는 모델의 경우, COLOR_0을 읽는 style: "cartoon"을 사용하세요.
• realistic에서 부분적으로 텍스처가 적용되었거나 여러 텍스처가 있는 모델의 경우, 모든 메시 부분에 UV와 동일한 단일 베이스 컬러 텍스처를 지정하세요. 이를 위해 나머지 부분에 텍스처를 적용하거나, 텍스처를 하나의 아틀라스로 병합하세요. style: "cartoon"으로 전환할 수도 있습니다.

textured_split_refused

keep_texture: true로 설정된 Auto Split 작업이 입력 모델의 텍스처를 파츠에 유지할 수 없는 경우입니다. 예를 들어 모델에 UV가 없거나, 텍스처에 절단으로 생성된 새 면을 위한 공간이 없는 경우입니다. Meshy는 크레딧을 환불합니다.

이를 해결하려면 keep_texture 없이, 또는 keep_texture: false로 설정하여 요청을 다시 보내세요. 그러면 각 파츠는 단색으로 반환됩니다.

invalid_input

입력이 검사를 통과하지 못했고, 더 구체적으로 해당하는 코드가 없는 경우입니다. 이유는 message에 나타납니다.

예를 들면 다음과 같습니다:

• 비어 있거나 손상된 모델 파일
• ASCII FBX 파일이나 meshopt로 압축된 GLB 파일처럼 지원되지 않는 파일 형식의 변형
• 아마추어, 카메라, 조명만 포함된 파일처럼 유효한 3D 객체가 없는 업로드된 모델
• 안전 필터를 통과하지 못한 콘텐츠

이를 해결하려면 구체적인 문제를 확인하기 위해 message를 읽어보세요. 입력 파일과 매개변수가 엔드포인트의 요구 사항을 충족하는지 확인하세요.

moderation_blocked

안전 필터가 prompt 또는 참조 이미지를 거부했습니다. 필터는 텍스트와 이미지를 함께 검사합니다.

이 문제를 해결하려면 다음 중 하나 또는 둘 다를 수행하세요:

• 선정적이거나 민감한 설명을 제거하도록 prompt를 다시 작성하세요.
• 필터가 차단할 수 있는 콘텐츠를 보여주는 참조 이미지를 변경하세요.

moderation_unavailable

유형: server_error. 콘텐츠 moderation이 일시적으로 사용할 수 없어, Meshy가 검사를 건너뛰는 대신 작업을 실패 처리했습니다. 사용자의 콘텐츠에는 문제가 없습니다.

이 문제를 해결하려면 작업을 다시 생성하세요.

timeout

작업이 서버 측 시간 제한(처리 시간 또는 대기열 대기 시간)을 초과하여 Meshy가 작업을 실패 처리하고 크레딧을 환불했습니다. 높은 부하, 또는 시간 내에 처리하기에 너무 복잡한 입력이 원인일 수 있습니다.

이는 사용자 측 코드에서 발생하는 timeout과는 다릅니다. 클라이언트가 대기를 중단했더라도 작업은 계속 실행 중일 수 있습니다. How long to wait를 참조하세요.

이 문제를 해결하려면 다음 단계를 따르세요:

1. 작업을 다시 생성하세요. timeout은 일시적인 경우가 많으며, 새로 생성한 작업은 성공할 수 있습니다.
2. 계속 실패하는 경우, 이미지나 prompt의 세부 정도를 줄이는 등 입력을 단순화하세요. 처리하기 더 어려운 입력에 대해서는 image_too_complex를 참조하세요.

queue_timeout

유형: timeout. 작업이 큐에서 너무 오래 대기하다가 시작되지 못해, Meshy가 작업을 실패 처리하고 해당 작업에 청구된 크레딧을 환불했습니다. 이 오류는 입력으로 인해 발생한 것이 아닙니다.

이 문제를 해결하려면 작업을 다시 생성하세요.

format_conversion_failed

Meshy가 모델을 생성했지만, 요청한 포맷으로 변환하는 데 실패했습니다.

이 문제를 해결하려면 다음 단계를 따르세요.

1. 작업을 다시 생성하세요.
2. 특정 포맷이 계속 실패한다면, 필요에 맞는 다른 포맷을 요청하세요.

모범 사례

• 실패한 작업은 재시도하세요. timeout, service_unavailable, 또는 server_error로 실패한 작업의 경우, 지수 백오프를 적용해 새 작업을 생성하세요.
• 요청이 timeout되었다고 해서 새 작업을 생성하지 마세요. 처음 작업이 여전히 실행 중일 수 있으므로, 다른 작업을 생성하기 전에 해당 작업이 존재하는지 확인하세요. 얼마나 기다려야 하는지를 참고하세요.
• 작업 ID를 기록하세요. 지원팀에 문의할 때 ID를 포함하세요.
• 입력값을 전송하기 전에 확인하세요. 이미지와 모델이 엔드포인트의 형식 요구사항을 충족하는지 확인하세요.
• 서버에서 API를 호출하세요. 브라우저에서 실행되는 코드는 페이지를 여는 모든 사람에게 API 키를 노출합니다.