크기 조정 API

크기 조정 API를 사용하면 기존 3D 모델을 실제 크기로 조정할 수 있습니다. 정확한 높이나 최장 변 제약 조건을 지정하거나, AI가 적절한 크기를 자동으로 추정하도록 할 수 있습니다.

POST/openapi/v1/resize

크기 조정 작업 생성하기

이 엔드포인트는 새로운 크기 조정 작업을 생성합니다.

파라미터

input_task_id 또는 model_url 중 하나만 필수로 지정하면 됩니다. 둘 다 제공된 경우, input_task_id가 우선순위를 가집니다.

  • Name
    input_task_id
    Type
    string
    필수
    Description

    크기를 조정하려는 모델을 가진, 완료된 Meshy 작업의 ID입니다. 해당 작업의 상태는 SUCCEEDED여야 합니다. 출력 형식은 GLB가 됩니다.

  • Name
    model_url
    Type
    string
    필수
    Description

    3D 모델 파일을 가리키는, 공개적으로 접근 가능한 URL 또는 data URI입니다. 지원되는 형식: .glb, .gltf, .obj, .fbx, .stl. Data URI의 경우, MIME type으로 application/octet-stream을 사용하세요. 출력 형식은 입력 모델의 원본 형식을 그대로 유지합니다.

resize_height, resize_longest_side, auto_size 중 정확히 하나의 크기 조정 mode가 필수입니다. 이 세 파라미터는 상호 배타적입니다.

  • Name
    resize_height
    Type
    number
    Description

    모델의 크기를 미터 단위로 측정된 특정 높이로 조정합니다.

  • Name
    resize_longest_side
    Type
    number
    Description

    모델의 가장 긴 변이 이 값(미터 단위)과 일치하도록 크기를 조정합니다. 종횡비는 유지됩니다.

  • Name
    auto_size
    Type
    boolean
    Description

    true로 설정하면, 서비스는 AI 비전을 사용하여 물체의 실제 세계 높이를 자동으로 추정하고 그에 맞게 모델의 크기를 조정합니다. origin_at이 명시적으로 설정되지 않는 한 원점은 기본적으로 bottom이 됩니다.

  • Name
    origin_at
    Type
    string
    기본값 bottom
    Description

    크기 조정 후 원점의 위치입니다.

    사용 가능한 값: bottom, center.

반환 값

응답의 result 속성에는 새로 생성된 크기 조정 작업의 id가 포함됩니다.

실패 모드

  • 400 - Bad Request

요청이 허용되지 않았습니다. 일반적인 원인:

  • 파라미터 누락: model_url 또는 input_task_id 중 하나는 반드시 제공되어야 합니다.
  • 크기 조정 mode 누락: resize_height, resize_longest_side, auto_size 중 적어도 하나는 지정되어야 합니다.
  • 상호 배타적 파라미터: resize_height, resize_longest_side, auto_size는 함께 사용할 수 없습니다.
  • 유효하지 않은 입력 작업: input_task_id는 성공한 작업을 참조해야 합니다.
  • 유효하지 않은 모델 형식: model_url이 지원되지 않는 확장자를 가진 파일을 가리키고 있습니다.
  • 접근할 수 없는 URL: model_url을 다운로드할 수 없습니다.
  • 401 - Unauthorized

인증에 실패했습니다. API 키를 확인해 주세요.

  • 402 - Payment Required

이 작업을 수행하기에 크레딧이 부족합니다.

  • 429 - Too Many Requests

속도 제한을 초과했습니다.

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"
}
GET/openapi/v1/resize/:id

크기 조정 작업 조회

이 엔드포인트는 ID를 통해 크기 조정 작업을 조회합니다.

파라미터

  • Name
    id
    Type
    path
    Description

    조회할 크기 조정 작업의 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
}
DELETE/openapi/v1/resize/:id

크기 조정 작업 삭제

이 엔드포인트는 크기 조정 작업과 관련된 모든 모델 및 데이터를 영구적으로 삭제합니다. 이 작업은 되돌릴 수 없습니다.

경로 매개변수

  • Name
    id
    Type
    path
    Description

    삭제할 크기 조정 작업의 ID입니다.

작업 상태

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

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

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

반환값

성공 시 200 OK를 반환하며, 작업이 IN_PROGRESS 상태인 경우 409 Conflict를 반환합니다.

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 is left 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."
}
GET/openapi/v1/resize

크기 조정 작업 목록 조회

이 엔드포인트를 사용하면 크기 조정 작업 목록을 조회할 수 있습니다.

매개변수

  • Name
    page_num
    Type
    integer
    기본값 1
    Description

    페이지네이션을 위한 페이지 번호입니다.

  • Name
    page_size
    Type
    integer
    기본값 10
    Description

    페이지 크기 제한입니다. 최대 허용치는 100개입니다.

  • Name
    sort_by
    Type
    string
    Description

    정렬 기준 필드입니다. 사용 가능한 값:

    • +created_at: 생성 시간 오름차순으로 정렬합니다.
    • -created_at: 생성 시간 내림차순으로 정렬합니다.

반환값

크기 조정 작업 객체의 페이지네이션된 목록을 반환합니다.

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
  }
]
GET/openapi/v1/resize/:id/stream

크기 조정 작업 스트리밍

이 엔드포인트는 Server-Sent Events(SSE)를 사용하여 크기 조정 작업의 실시간 업데이트를 스트리밍합니다.

매개변수

  • Name
    id
    Type
    path
    Description

    스트리밍할 크기 조정 작업의 고유 식별자입니다.

반환값

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

PENDING 또는 IN_PROGRESS 상태의 작업의 경우, 응답 스트림에는 필요한 progress와 status 필드만 포함됩니다.

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
}

Resize Task 객체

Resize Task 객체는 크기 조정 작업을 나타냅니다.

Properties

  • id · string

작업의 고유 식별자입니다.

  • type · string

작업의 유형입니다. 값은 resize입니다.

  • model_urls · object

크기가 조정된 모델 파일을 다운로드할 수 있는 URL입니다. input_task_id를 사용하는 경우 출력은 항상 GLB입니다. model_url을 사용하는 경우 출력은 원본 형식을 유지합니다.

  • progress · integer

작업의 progress입니다 (0-100).

  • status · string

작업의 상태입니다. 가능한 값: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • preceding_tasks · integer

선행 작업의 수입니다. 상태가 PENDING일 때만 의미가 있습니다.

  • created_at · timestamp

작업이 생성된 시점의 타임스탬프이며, 밀리초 단위입니다.

  • started_at · timestamp

작업이 시작된 시점의 타임스탬프이며, 밀리초 단위입니다. 시작되지 않은 경우 0입니다.

  • finished_at · timestamp

작업이 완료된 시점의 타임스탬프이며, 밀리초 단위입니다. 완료되지 않은 경우 0입니다.

  • task_error · object

작업이 실패한 경우의 오류 객체입니다. 자세한 내용은 오류를 참조하세요.

  • consumed_credits · integer

이 작업에서 소비된 크레딧 수입니다 (크기 조정 작업당 1 크레딧). FAILED 작업의 경우 0을 반환합니다.