UV Unwrap API
UV Unwrap API는 기존 3D 모델에 대해 고품질 UV 언래핑을 자동으로 생성합니다. 텍스처링 이전의 필수 단계로 사용하거나, 다운스트림 도구(Blender, Substance Painter, Unreal)에서 사용할 깔끔하고 겹치지 않는 UV 레이아웃이 필요할 때 언제든 사용할 수 있습니다.
출력물은 "UV 화이트 모델"입니다 — 입력물과 동일한 형태이지만 완전히 새로운 UV 좌표를 가지며 실제 텍스처는 없습니다(glTF 머티리얼 슬롯을 유효하게 유지하기 위해 2×2 회색 플레이스홀더 머티리얼이 포함되며, 표준 도구에서는 이를 텍스처가 적용되지 않은 것으로 처리합니다).
제한 사항. Auto UV는 현재 최대 40,000개 면까지의 메시를 지원합니다 — 이보다 큰 모델은 400으로 거부되므로, 먼저 리메시를 실행하여 폴리곤 수를 줄이세요. 쿼드 및 n각형 메시는 UV 생성 과정에서 삼각화되므로, 출력물은 항상 삼각형 메시입니다.
UV 언래핑 작업 생성
이 엔드포인트는 새로운 UV 언래핑 작업을 생성합니다.
파라미터
input_task_id 또는 model_url 중 정확히 하나가 필요합니다. 둘 다 제공되면 input_task_id가 우선순위를 가집니다.
- Name
- input_task_id
- Type
- string
- 필수
- Description
UV 언래핑을 수행하려는 GLB 출력물을 가진, 완료된 Meshy API 작업의 ID입니다(예: 이미지로 3D, 텍스트로 3D, 또는 리메시 결과). 소스 작업의 상태는
SUCCEEDED이어야 하며 GLB 파일을 생성했어야 합니다.소스 메시가 40,000면의 면 수 상한을 초과하면 요청이
400으로 거부되며, 먼저 리메시를 실행하여 폴리곤 수를 줄여야 합니다.
- Name
- model_url
- Type
- string
- 필수
- Description
공개적으로 접근 가능한 URL 또는 data URI를 통해 3D 모델을 직접 제공합니다.
.glb만 지원됩니다 — API는 glTF 바이너리를 읽으며 다른 형식은 파싱하지 않습니다. 다른 형식(.fbx,.obj,.stl,.gltf)의 모델을 UV 언래핑하려면, 먼저 Convert API를 통해.glb로 변환한 다음, 결과 작업 ID를input_task_id로 전달하거나 그 GLB 출력 URL을 여기에 전달하세요.Data URI의 경우, MIME type
application/octet-stream을 사용하세요.input_task_id와 동일한 40,000면 상한이 적용됩니다. 크기가 초과된 메시는400으로 거부됩니다 — 먼저 리메시를 실행하세요.
반환값
응답의 result 속성에는 새로 생성된 UV 언래핑 작업의 id가 포함됩니다.
실패 모드
- Name
400 - Bad Request- Description
요청이 허용되지 않았습니다. 일반적인 원인:
- 파라미터 누락:
input_task_id또는model_url중 하나는 반드시 제공되어야 합니다. - 잘못된 입력 작업:
input_task_id는 GLB 결과를 가진 성공한 작업을 참조해야 합니다. - 면 수 초과: 소스 메시의 면 수가 UV 언래핑 상한을 초과합니다. 먼저 리메시를 실행하세요.
- 잘못된 모델 형식:
model_url이 지원되지 않는 확장자를 가진 파일을 가리킵니다. - 접근 불가능한 URL:
model_url을 다운로드할 수 없습니다.
- 파라미터 누락:
- Name
401 - Unauthorized- Description
인증에 실패했습니다. API 키를 확인하세요.
- Name
402 - Payment Required- Description
이 작업을 수행하기에 크레딧이 부족합니다. UV 언래핑은 호출당 5크레딧이 소요됩니다.
- Name
404 - Not Found- Description
해당 기능이 귀하의 계정에서 활성화되어 있지 않습니다. UV 언래핑은 출시 과정에서 Statsig 플래그에 의해 제한되어 있습니다 — 접근 권한이 필요하면 Meshy 지원팀에 문의하세요.
- Name
429 - Too Many Requests- Description
속도 제한을 초과했습니다.
Request
# Chain from an existing Meshy task
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input_task_id": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}'
# Or from a publicly accessible model URL
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"model_url": "https://example.com/path/to/model.glb"
}'
Response
{
"result": "019361c6-9b34-7b23-bef2-d0107c4d92e2"
}
UV 언래핑 작업 조회
Request
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
아래의 예시 작업 객체를 참고하세요.
UV 언래핑 작업 삭제
UV 언래핑 작업을 영구적으로 삭제합니다. 해당 작업과 그 출력물은 더 이상 접근할 수 없게 됩니다.
아직 PENDING 상태인 작업은 삭제되며, 생성 시 소모된 크레딧이 환불됩니다.
이미 IN_PROGRESS 상태인 작업은 삭제할 수 없습니다. 요청은 409 Conflict로 거부되며 작업은 계속 실행됩니다.
워커가 이미 시작한 작업에 대한 크레딧은 환불되지 않으므로, 실행 도중에 삭제하면 크레딧과 결과물을 모두 잃게 됩니다.
SUCCEEDED, FAILED 또는 CANCELED 상태가 될 때까지 기다린 후 삭제하세요.
종료 상태(SUCCEEDED, FAILED 또는 CANCELED)인 작업은 환불 없이 삭제됩니다.
Request
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-X DELETE \
-H "Authorization: Bearer ${YOUR_API_KEY}"
UV 언래핑 작업 목록 조회
호출자의 UV 언래핑 작업 목록을 최신순으로 페이지네이션하여 반환합니다. page_num 및 page_size를 통한 표준 페이지네이션입니다.
Request
curl "https://api.meshy.ai/openapi/v1/uv-unwrap?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"
UV 언래핑 작업 스트리밍하기
작업 진행 상황을 Server-Sent Events로 구독합니다. 각 message 이벤트는 UV Unwrap Task object를 포함하며, 작업이 SUCCEEDED, FAILED, 또는 CANCELED 상태에 도달하면 스트림이 닫힙니다.
완료 시 지연 시간을 줄이려면 GET /openapi/v1/uv-unwrap/:id를 폴링하는 대신 이 방법을 사용하세요.
Request
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-N
UV 언래핑 태스크 객체
- Name
- id
- Type
- string
- Description
태스크의 고유 식별자입니다.
- Name
- type
- Type
- string
- Description
항상
uv-unwrap입니다.
- Name
- model_urls
- Type
- object
- Description
생성된 UV 화이트 모델의 사전 서명된 다운로드 URL입니다. UV 언래핑은 항상 단일
glb항목을 반환합니다 — 출력은 입력 지오메트리를 유지하고, 새로운 UV 좌표로 교체하며, 텍스처 대신 기본 회색 머티리얼을 사용합니다.
- Name
- thumbnail_url
- Type
- string
- Description
UV 화이트 모델의 PNG 미리보기에 대한 사전 서명된 URL입니다.
- Name
- progress
- Type
- integer
- Description
태스크 진행률로,
0부터100까지입니다.
- Name
- status
- Type
- string
- Description
PENDING,IN_PROGRESS,SUCCEEDED,FAILED,CANCELED중 하나입니다.
- Name
- preceding_tasks
- Type
- integer
- Description
이 태스크보다 앞서 대기 중인 태스크 수입니다. 상태가
PENDING일 때 존재합니다.
- Name
- created_at
- Type
- timestamp
- Description
태스크 생성 시각의 타임스탬프이며, 밀리초 단위입니다.
- Name
- started_at
- Type
- timestamp
- Description
처리가 시작된 시각의 타임스탬프이며, 밀리초 단위입니다. 시작되기 전까지는
0입니다.
- Name
- finished_at
- Type
- timestamp
- Description
완료 시각의 타임스탬프이며, 밀리초 단위입니다. 완료되기 전까지는
0입니다.
- Name
- expires_at
- Type
- timestamp
- Description
서명된 다운로드 URL이 만료되는 시각의 타임스탬프이며, 밀리초 단위입니다.
- Name
- task_error
- Type
- object
- Description
실패한 태스크에 대한 오류 세부 정보입니다. 전체
task_error객체 참조는 오류를 참고하세요.
- Name
- consumed_credits
- Type
- integer
- Description
이 태스크에서 소비된 크레딧입니다.
FAILED태스크의 경우0을 반환합니다(실패 시 크레딧은 환불됩니다). UV 언래핑은 성공 시 5 크레딧이 청구됩니다.
Example UV Unwrap Task Object
{
"id": "019361c6-9b34-7b23-bef2-d0107c4d92e2",
"type": "uv-unwrap",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/preview.png?Expires=***",
"progress": 100,
"status": "SUCCEEDED",
"preceding_tasks": 0,
"created_at": 1716579120000,
"started_at": 1716579122000,
"finished_at": 1716579180000,
"expires_at": 1716665580000,
"task_error": {
"message": ""
},
"consumed_credits": 5
}