UV 언래핑 API

UV 언래핑 API는 기존 3D 모델에 대해 고품질 UV 언래핑을 자동으로 생성합니다. 텍스처링 전 필수 단계로 사용하거나, 다운스트림 도구(Blender, Substance Painter, Unreal)를 위해 깔끔하고 겹치지 않는 UV 레이아웃이 필요할 때마다 사용하세요.

출력은 "UV 화이트 모델"입니다. 입력과 동일한 형태이지만 완전히 새로운 UV 좌표가 있으며 실제 텍스처는 없습니다(2×2 회색 플레이스홀더 머티리얼이 포함되어 glTF 머티리얼 슬롯을 유효하게 유지하며, 표준 도구는 이를 텍스처가 없는 것으로 처리합니다).

제한 사항. 자동 UV는 현재 최대 40,000개 면의 메시를 지원합니다. 더 큰 모델은 400과 함께 거부됩니다. 먼저 리메시를 실행하여 폴리곤 수를 줄이세요. 쿼드 및 n-gon 메시는 UV 생성 중에 삼각분할되므로 출력은 항상 삼각형 메시입니다.

POST/openapi/v1/uv-unwrap

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 언래핑하려면 먼저 변환 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

POST

/openapi/v1/uv-unwrap

# 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"
}

GET/openapi/v1/uv-unwrap/:id

UV 언래핑 작업 조회

이 엔드포인트는 ID로 UV 언래핑 작업의 현재 상태를 조회합니다.

반환값

UV 언래핑 작업 객체를 반환합니다.

Request

GET

/openapi/v1/uv-unwrap/:id

curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

아래의 예시 작업 객체를 참조하세요.

DELETE/openapi/v1/uv-unwrap/:id

UV 언래핑 작업 삭제

UV 언래핑 작업을 영구적으로 삭제합니다. 해당 작업과 그 출력물에 접근할 수 없게 됩니다.

Request

DELETE

/openapi/v1/uv-unwrap/:id

curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-X DELETE \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/uv-unwrap

UV 언래핑 작업 목록 조회

호출자의 UV 언래핑 작업 목록을 최신순으로 페이지네이션하여 반환합니다. 표준 페이지네이션은 page_num 및 page_size를 통해 수행됩니다.

Request

GET

/openapi/v1/uv-unwrap

curl "https://api.meshy.ai/openapi/v1/uv-unwrap?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/uv-unwrap/:id/stream

UV 언래핑 작업 스트리밍

Server-Sent Events로 작업 progress를 구독합니다. 각 message 이벤트는 UV 언래핑 작업 객체를 전달하며, 작업이 SUCCEEDED, FAILED 또는 CANCELED에 도달하면 스트림이 닫힙니다.

완료 시 지연 시간을 줄이려면 GET /openapi/v1/uv-unwrap/:id를 폴링하는 대신 이를 사용하세요.

Request

GET

/openapi/v1/uv-unwrap/:id/stream

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
작업 progress, 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
}