lowpoly는 2026. 10. 30.에 지원 종료됩니다. 요청 오류를 피하려면 해당 날짜 전에 모델을 전환하세요.

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 생성 과정에서 삼각분할되므로, 출력물은 항상 삼각형 메시입니다.

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 또는 데이터 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을 사용하세요.

    최대 파일 크기: http 또는 https URL의 경우 400MB, data: URI의 경우 100MB입니다. 100MB를 초과하는 GLB는 Draco 압축을 사용해서는 안 됩니다.

    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을 다운로드할 수 없습니다.
    • 모델 파일이 너무 큼: model_url 파일이 400MB(http 또는 https URL) 또는 100MB(data: URI)를 초과합니다.
    • 면이 너무 많음: model_url 파일이 100MB를 초과하고 10,000,000개보다 많은 면을 가지고 있습니다. 면 수를 줄인 후 파일을 다시 전송하세요.
    • 읽을 수 없는 모델 파일: model_url 파일이 100MB를 초과하고 헤더를 읽을 수 없습니다(예: Draco 압축된 GLB).
    • 모델 헤더가 너무 복잡함: model_url 파일이 100MB를 초과하고 헤더에 확인해야 할 메시, 노드 또는 레코드가 너무 많습니다. 파일 내 객체 수를 줄인 후 다시 전송하세요.
  • 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 Unwrap 작업 조회

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

반환값

UV Unwrap Task 객체를 반환합니다.

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 언래핑 작업을 영구적으로 삭제합니다. 해당 작업과 그 결과물은 더 이상 접근할 수 없게 됩니다.

아직 PENDING 상태인 작업은 삭제되며, 생성 시점에 소모된 크레딧은 환불됩니다.

이미 IN_PROGRESS 상태인 작업은 삭제할 수 없습니다. 요청은 409 Conflict로 거부되며 작업은 계속 실행됩니다. 워커가 이미 시작한 작업의 크레딧은 환불되지 않으므로, 실행 도중에 삭제하면 크레딧과 결과물을 모두 잃게 됩니다. SUCCEEDED, FAILED 또는 CANCELED 상태가 될 때까지 기다린 후 삭제하세요.

종료 상태(SUCCEEDED, FAILED 또는 CANCELED)인 작업은 환불 없이 삭제됩니다.

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)로 구독합니다. 각 message 이벤트는 UV Unwrap Task 객체를 전달하며, 작업이 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

The UV Unwrap Task Object

  • 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
}