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

UV Unwrap API

기존 3D 모델에 대한 UV 언래핑을 생성합니다. 모델에 텍스처를 입히기 전에 실행하거나, Blender, Substance Painter, Unreal과 같은 도구에서 깔끔하고 겹치지 않는 UV 레이아웃이 필요할 때 실행하세요.

출력물은 UV 화이트 모델입니다. 입력 모델과 동일한 형태를 가지며, 새로운 UV 좌표를 포함하고, 실제 텍스처는 없습니다. glTF 머티리얼 슬롯이 유효하게 유지되도록 2×2 회색 placeholder 머티리얼이 포함되며, 표준 도구에서는 텍스처가 없는 것으로 처리됩니다.

UV Unwrap은 최대 40,000개의 면을 가진 메시를 지원합니다. 더 큰 모델은 400을 반환합니다. 면 수를 줄이려면 먼저 Remesh를 실행하세요.

Meshy는 UV 생성 과정에서 쿼드 및 n각형 메시를 삼각분할하므로, 출력물은 항상 삼각형 메시입니다.

POST/openapi/v1/uv-unwrap

UV 언래핑 태스크 생성

UV 언래핑 태스크를 생성합니다.

이 태스크는 백그라운드에서 실행됩니다. 태스크가 일반적으로 얼마나 걸리는지는 처리 시간을 참고하세요.

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

파라미터

  • Name
    input_task_id
    Type
    string
    필수
    Description

    model_url을 보내지 않는 한 필수입니다. 언래핑하려는 GLB 출력을 가진 Meshy API 태스크의 ID로, 예를 들어 이미지로 3D, 텍스트로 3D, 또는 리메시 태스크가 해당됩니다. 해당 태스크는 상태가 SUCCEEDED여야 하며 GLB 파일을 생성한 것이어야 합니다.

    메시는 최대 40,000개의 면을 가질 수 있습니다. 이보다 많은 면을 가진 메시는 400을 반환합니다. 면 수를 줄이려면 먼저 리메시를 실행하세요.

  • Name
    model_url
    Type
    string
    필수
    Description

    input_task_id를 보내지 않는 한 필수입니다. 언래핑할 모델로, 공개 URL 또는 data URI 형태입니다. 둘 다 보낼 경우 Meshy는 input_task_id를 사용합니다.

    모델은 .glb 파일이어야 합니다. 다른 형식을 언래핑하려면 먼저 변환 API를 사용해 GLB로 변환하세요.

    파일은 http 또는 https URL인 경우 최대 400MB, data URI인 경우 최대 100MB까지 가능합니다. data URI의 경우 MIME type은 application/octet-stream을 사용하세요. 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 결과물을 가진 성공한 API 태스크가 아닙니다.
    • 면 수 초과: 메시가 UV 언래핑에서 허용하는 면 수를 초과합니다. 먼저 리메시를 실행하세요.
    • 잘못된 모델 형식: model_url 파일의 확장자가 지원되지 않습니다.
    • 접근 불가능한 URL: Meshy가 model_url 파일을 다운로드할 수 없습니다.
    • 모델 파일이 너무 큼: model_url 파일이 http 또는 https URL인 경우 400MB를, data URI인 경우 100MB를 초과합니다.
    • 면 수가 너무 많음: model_url 파일이 100MB를 초과하고 면 수가 10,000,000개를 초과합니다. 면 수를 줄인 후 파일을 다시 전송하세요.
    • 읽을 수 없는 모델 파일: model_url 파일이 100MB를 초과하며, Meshy가 해당 파일의 헤더를 읽을 수 없습니다. 예를 들어 Draco로 압축된 GLB인 경우입니다.
    • 모델 헤더가 너무 복잡함: model_url 파일이 100MB를 초과하며, 헤더에 검사할 메시, 노드 또는 레코드가 너무 많습니다. 파일 내 객체 수를 줄인 후 다시 전송하세요.

    요청을 수정한 후 다시 전송하세요. 오류를 참고하세요.

  • Name
    401 - Unauthorized
    Description

    API 키가 누락되었거나 유효하지 않습니다. Authorization 헤더를 확인하세요.

  • Name
    402 - Payment Required
    Description

    예를 들어:

    • 크레딧 부족: 계정에 이 태스크를 수행할 만큼의 크레딧이 없거나, 계정이 크레딧 한도에 도달했습니다. UV 언래핑 태스크는 5크레딧이 소요됩니다. 크레딧 잔액을 확인한 후 다시 시도하세요.
    • 무료 플랜: 태스크를 생성하려면 유료 플랜이 필요합니다. 구독 설정에서 플랜을 업그레이드한 후 다시 시도하세요.
  • Name
    403 - Forbidden
    Description

    input_task_id가 저부조(bas-relief) 모델이며, 이 엔드포인트는 이를 언래핑할 수 없습니다. 메시지는 This model type does not support this operation입니다. 다른 모델을 전송하세요.

  • Name
    404 - Not Found
    Description

    input_task_id가 사용자의 태스크 중 어느 것과도 일치하지 않습니다. 태스크 ID를 확인한 후 요청을 다시 전송하세요.

  • Name
    429 - Too Many Requests
    Description

    속도 제한을 초과했습니다. 잠시 기다린 후 다시 시도하세요. 속도 제한을 참고하세요.

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

UV 언래핑 작업 조회

ID를 통해 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}"

응답 예시는 UV 언래핑 작업 객체 예시를 참고하세요.

Returns

UV 언래핑 작업 객체입니다.

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

UV 언래핑 작업 삭제

UV Unwrap 작업을 결과물과 함께 영구적으로 삭제합니다. 삭제는 취소할 수 없습니다.

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

작업 상태

PENDING 상태의 작업을 삭제하면 생성 시 사용된 크레딧이 환불됩니다.

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

최종 상태(SUCCEEDED, FAILED, 또는 CANCELED)인 작업을 삭제해도 크레딧은 환불되지 않습니다.

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 언래핑 작업 스트리밍

UV 언래핑 작업의 업데이트를 Server-Sent Events(SSE)로 스트리밍합니다. 각 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 언래핑 작업 객체

UV 언래핑 작업 객체는 3D 모델의 UV 언래핑 작업 하나를 나타냅니다. 이 객체는 작업이 성공했을 때 상태, progress, 모델 파일을 담고 있습니다.

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
}
  • Name
    id
    Type
    string
    Description

    작업 ID입니다. 불투명한 문자열로 취급하고, 그 형식에 의존하지 마세요.

  • 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

    작업이 실패했을 때의 오류 세부 정보입니다. 오류를 참고하세요.

  • Name
    consumed_credits
    Type
    integer
    Description

    작업에 사용된 크레딧 수입니다. 성공한 UV 언래핑 작업은 5 크레딧이 소요됩니다. FAILED 작업의 경우 0인데, Meshy가 작업 실패 시 크레딧을 환불하기 때문입니다.