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

크기 조정 API

3D 모델을 미터 단위의 실제 크기로 크기 조정합니다. 높이나 가장 긴 변의 길이를 설정하거나, Meshy가 객체의 실제 높이를 추정하도록 할 수 있습니다.

POST/openapi/v1/resize

Resize 작업 생성하기

Resize 작업을 생성합니다. 작업은 백그라운드에서 실행됩니다. 작업이 일반적으로 얼마나 걸리는지는 처리 시간을 참고하세요.

Request

POST
/openapi/v1/resize
# Simple: resize to a specific height
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "resize_height": 1.8
  }'

# Advanced: resize longest side with custom origin
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.glb",
    "resize_longest_side": 2.0,
    "origin_at": "center"
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

파라미터

  • Name
    input_task_id
    Type
    string
    필수
    Description

    model_url을 보내지 않는 한 필수입니다. 3D 모델을 생성한 작업의 ID로, 예를 들어 텍스트로 3D, 이미지로 3D, 리메시, 또는 리텍스처 작업이 해당됩니다. 이 작업은 API에서 생성된 것이어야 하며 상태가 SUCCEEDED여야 합니다. Meshy는 크기가 조정된 모델을 GLB 파일로 반환합니다.

  • Name
    model_url
    Type
    string
    필수
    Description

    input_task_id를 보내지 않는 한 필수입니다. 크기를 조정할 모델로, 공개 URL 또는 data URI 형식입니다. 둘 다 보내면 Meshy는 input_task_id를 사용합니다.

    모델은 http 또는 https URL인 경우 최대 400MB, data URI인 경우 최대 100MB의 GLB, glTF, OBJ, FBX, 또는 STL 파일이어야 합니다. data URI의 경우 MIME type application/octet-stream을 사용하세요.

    100MB를 초과하는 파일은 다음 규칙도 따라야 합니다:

    • GLB, glTF, FBX, 또는 OBJ 파일은 최대 10,000,000개의 면을 가질 수 있습니다. Meshy는 면을 삼각형 단위로 계산하므로, 사각형은 2개로 계산되고, 여러 번 그려진 메시는 복사본마다 한 번씩 계산됩니다.
    • FBX 파일은 바이너리 FBX 7.1 이상이어야 합니다.
    • GLB 또는 glTF 파일은 Draco 압축을 사용하지 않아야 합니다.

    GLB, OBJ, FBX, 또는 STL 파일은 결과에서도 형식이 유지됩니다. .gltf 파일이나 data URI는 GLB로 반환됩니다.

resize_height, resize_longest_side, auto_size 중 정확히 하나를 보내세요. 아무것도 보내지 않거나 여러 개를 보내면 400이 반환됩니다.

  • Name
    resize_height
    Type
    number
    Description

    모델의 새로운 높이(미터 단위)로, 0보다 커야 합니다. 음수 값은 400을 반환합니다.

  • Name
    resize_longest_side
    Type
    number
    Description

    모델의 가장 긴 변의 새로운 길이(미터 단위)로, 0보다 커야 합니다. 음수 값은 400을 반환합니다. Meshy는 모델의 종횡비를 유지합니다.

  • Name
    auto_size
    Type
    boolean
    Description

    AI 비전으로 객체의 실제 높이를 추정하고 이를 기준으로 모델 크기를 조정할지 여부입니다. origin_at을 설정하지 않으면 Meshy는 원점을 하단에 배치합니다.

  • Name
    origin_at
    Type
    string
    기본값 bottom
    Description

    크기 조정 후 모델의 원점을 어디에 둘지 지정합니다. bottom 또는 center 중 하나입니다.

반환값

응답의 result 필드에는 새로 생성된 Resize 작업의 ID가 담깁니다.

실패 모드

  • Name
    400 - Bad Request
    Description

    요청을 실행할 수 없습니다. 오류 메시지에 발견된 문제가 표시됩니다. 예를 들면:

    • 파라미터 누락: model_url과 input_task_id 모두 전송되지 않았습니다.
    • 크기 조정 모드 누락: resize_height, resize_longest_side, auto_size 중 어느 것도 전송되지 않았습니다.
    • 상호 배타적 파라미터: 요청에 resize_height, resize_longest_side, auto_size 중 두 개 이상이 포함되어 있습니다. 하나만 보내세요.
    • 음수 크기: resize_height 또는 resize_longest_side가 음수입니다.
    • 잘못된 입력 작업: input_task_id가 모델 파일을 가진 성공한 API 작업이 아닙니다.
    • 잘못된 모델 형식: model_url 파일의 확장자가 지원되지 않습니다.
    • 접근할 수 없는 URL: Meshy가 model_url 파일을 다운로드할 수 없습니다.
    • 모델 파일이 너무 큼: model_url 파일이 http 또는 https URL인 경우 400MB를 초과하거나, data URI인 경우 100MB를 초과합니다.
    • 면이 너무 많음: model_url 파일이 100MB를 초과하며 10,000,000개보다 많은 면을 가지고 있습니다. 면 개수를 줄인 후 파일을 다시 보내세요.
    • 100MB를 초과하는 ASCII FBX: model_url 파일이 100MB를 초과하는 ASCII FBX입니다. 바이너리 FBX 또는 GLB로 보내세요.
    • 읽을 수 없는 모델 파일: model_url 파일이 100MB를 초과하며 Meshy가 헤더를 읽을 수 없습니다. 예를 들어 Draco 압축된 GLB나 glTF, 또는 7.1 이전 버전의 바이너리 FBX인 경우입니다.
    • 모델 헤더가 너무 복잡함: model_url 파일이 100MB를 초과하며, 헤더에 확인해야 할 메시, 노드, 또는 레코드가 너무 많습니다. 파일 내 객체 수를 줄인 후 다시 보내세요.

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

  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

    예를 들면:

    • 크레딧 부족: 계정에 이 작업을 수행할 충분한 크레딧이 없거나, 계정이 크레딧 한도에 도달했습니다. 크레딧 잔액을 확인한 후 다시 시도하세요.
    • 무료 플랜: 작업을 생성하려면 유료 플랜이 필요합니다. 구독 설정에서 플랜을 업그레이드한 후 다시 시도하세요.
  • 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/resize/:id

크기 조정 작업 가져오기

ID로 크기 조정 작업을 반환합니다.

Request

GET
/openapi/v1/resize/:id
curl https://api.meshy.ai/openapi/v1/resize/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "resize",
  "model_urls": {
      "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

매개변수

  • Name
    id
    Type
    path
    Description

    생성 응답에서 받은 작업 ID입니다.

반환 값

Resize task object를 반환합니다.

DELETE/openapi/v1/resize/:id

Resize 작업 삭제

Resize 작업과 해당 모델 및 데이터를 영구적으로 삭제합니다. 삭제는 되돌릴 수 없습니다.

Request

DELETE
/openapi/v1/resize/:id
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/resize/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

경로 매개변수

  • Name
    id
    Type
    path
    Description

    삭제할 작업의 ID입니다.

작업 상태

PENDING 작업을 삭제하면 작업을 생성할 때 사용된 크레딧이 환불됩니다.

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

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

반환값

작업이 삭제되면 200 OK를, 작업이 IN_PROGRESS 상태이면 409 Conflict를 반환합니다.

GET/openapi/v1/resize

Resize 작업 목록 조회

사용자의 Resize 작업 목록을 반환합니다.

Request

GET
/openapi/v1/resize
curl https://api.meshy.ai/openapi/v1/resize?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "resize",
    "model_urls": {
      "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
    "consumed_credits": 1
  }
]

매개변수

  • Name
    page_num
    Type
    integer
    기본값 1
    Description

    반환할 페이지 번호이며, 최대 255까지 가능합니다. 더 큰 값을 사용하면 400을 반환합니다.

  • Name
    page_size
    Type
    integer
    기본값 10
    Description

    페이지당 작업 수이며, 최대 100까지 가능합니다.

  • Name
    sort_by
    Type
    string
    Description

    정렬 순서입니다.

    사용 가능한 값:

    • +created_at: 오래된 순
    • -created_at: 최신 순

반환값

Resize 작업 객체의 페이지네이션된 목록입니다.

GET/openapi/v1/resize/:id/stream

Resize 작업 스트리밍

Resize 작업의 업데이트를 Server-Sent Events (SSE)로 스트리밍합니다.

Request

GET
/openapi/v1/resize/:id/stream
curl -N https://api.meshy.ai/openapi/v1/resize/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Message event examples illustrate task progress.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "resize",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Parameters

  • Name
    id
    Type
    path
    Description

    생성 응답에서 받은 작업 ID입니다.

Returns

Resize 작업 객체의 스트림을 Server-Sent Events로 반환합니다.

각 이벤트는 Get 엔드포인트가 반환하는 것과 동일한 형태로 전체 작업 객체를 담고 있습니다. 작업이 PENDING 또는 IN_PROGRESS 상태인 동안에는 결과 필드에 아직 값이 없습니다.

Resize 작업 객체

Resize 작업 객체는 3D 모델의 크기 조정 작업 하나를 설명합니다. 여기에는 상태, progress, 그리고 작업이 성공했을 때의 모델 파일이 포함됩니다.

속성

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    작업 유형으로, 항상 resize입니다.

  • Name
    model_urls
    Type
    object
    Description

    크기가 조정된 모델 파일의 다운로드 URL입니다. input_task_id의 경우 파일은 항상 GLB입니다. model_url의 경우 GLB, OBJ, FBX 또는 STL 파일은 해당 형식을 그대로 유지하며, .gltf 파일이나 Data URI는 GLB로 반환됩니다.

  • 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이 만료되는 시간으로, 유닉스 밀리초 단위입니다. 작업이 종료되기 전까지는 0입니다.

  • Name
    texture_urls
    Type
    array
    Description

    작업이 성공했을 때 모델의 텍스처 맵에 대한 다운로드 URL입니다. 텍스처 세트마다 하나씩, 객체들의 배열로 구성됩니다. 각 객체는 base_color URL을 가지며, 추가로 metallic, roughness, normal, emission, metallic_roughness URL을 가질 수 있습니다. 작업이 성공하기 전까지는 null이며, 모델에 텍스처 맵이 없는 경우에는 빈 배열입니다.

  • Name
    task_error
    Type
    object
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

    작업에 사용된 크레딧의 수로, Resize 작업의 경우 1입니다. FAILED 작업의 경우 0입니다.