크기 조정 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. 출력 형식은 입력 모델의 원래 형식을 유지합니다.

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

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입니다.

반환값

성공 시 200 OK를 반환합니다.

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

// Returns 200 Ok on success.

GET/openapi/v1/resize

크기 조정 작업 목록 조회

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

매개변수

Name
page_num
Type
integer
기본값 1
Description
페이지네이션을 위한 페이지 번호입니다.

Name
page_size
Type
integer
기본값 10
Description
페이지 크기 제한입니다. 허용되는 최대값은 50개 항목입니다.

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
}

크기 조정 작업 객체

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

속성

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을 반환합니다.