UV 언래핑 API
UV 언래핑 API는 기존 3D 모델에 대해 고품질의 UV 언래핑을 자동으로 생성합니다. 텍스처링 전에 필수 단계로 사용하거나, 다운스트림 도구(Blender, Substance Painter, Unreal)를 위해 깨끗하고 겹치지 않는 UV 레이아웃이 필요할 때마다 사용하세요.
출력은 "UV 화이트 모델"입니다 — 입력과 동일한 형태이지만 새로운 UV 좌표와 실제 텍스처가 없는 상태입니다 (2×2 회색 플레이스홀더 머티리얼이 포함되어 glTF 머티리얼 슬롯을 유효하게 유지합니다; 표준 도구는 이를 텍스처가 없는 것으로 처리합니다).
제한 사항. 자동 UV는 현재 최대 40,000 면의 메시를 지원합니다 — 더 큰 모델은 400 오류와 함께 거부됩니다; 폴리곤 수를 줄이기 위해 먼저 리메시를 실행하세요. 쿼드 및 n-각형 메시는 UV 생성 중에 삼각형화되므로 출력은 항상 삼각형 메시입니다.
UV 언래핑 작업 생성
이 엔드포인트는 새로운 UV 언래핑 작업을 생성합니다.
파라미터
input_task_id 또는 model_url 중 하나는 반드시 필요합니다. 둘 다 제공된 경우, input_task_id가 우선합니다.
- Name
- input_task_id
- Type
- string
- 필수
- Description
UV 언래핑을 원하는 완료된 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 언래핑하려면 먼저 변환 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 언래핑 작업을 영구적으로 삭제합니다. 작업과 그 출력물은 접근할 수 없게 됩니다.
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)로 작업 progress를 구독합니다. 각 message 이벤트는 UV 언래핑 작업 객체를 포함하며, 작업이 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
}