Creative Lab 램프 API

사진을 두 단계에 걸쳐 3D 프린팅이 가능한 램프갓으로 변환합니다. 프로토타입 작업은 무광 화이트 컨셉 이미지를 생성하고 이를 3D 모델로 변환합니다. 프로토타입 작업의 ID를 input_task_id로 사용하는 빌드 작업은 해당 모델을 프린팅 가능한 STL 파츠로 변환합니다. 기본 조명기구 프리셋을 사용하면, 파츠는 조명기구용 베이스 플레이트가 있는 바닥이 열린 램프갓과 조명기구 마운트로 구성됩니다.

POST /openapi/creative-lab/lamp/v1/prototype
POST /openapi/creative-lab/lamp/v1/build

POST/openapi/creative-lab/lamp/v1/prototype

Lamp prototype 작업 생성하기

사진으로부터 매트 화이트 컨셉 이미지를 생성하고 이를 3D 램프갓 모델로 변환합니다. 작업은 컨셉 이미지를 image_urls에, 모델을 model_urls.glb에 반환하며, thumbnail_url에 미리보기를 제공합니다. 인쇄 가능한 부품을 만들려면 이 작업의 ID를 input_task_id로 build 엔드포인트에 전달하세요. 작업의 필드에 대해서는 The Lamp prototype task object를 참고하세요.

Request

POST

/openapi/creative-lab/lamp/v1/prototype

# Stage 1: concept image + 3D lampshade model from a source photo
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "image_subject": "character"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Prototype example

Start with a source photo. The prototype returns the concept image and the 3D model that the build stage processes.

Source cat photo used as the Creative Lab Lamp input — Prototype input

Creative Lab Lamp prototype output generated from the source photo — Prototype output

매개변수

Name
image_url
Type
string
필수
Description
램프갓의 기반이 될 사진으로, 공개 URL 또는 data URI(data:image/jpeg;base64,<your base64-encoded image data>) 형식입니다.
이미지는 최대 20MB의 JPG, JPEG, PNG, 또는 WebP 파일이어야 합니다.

Name
image_subject
Type
string
기본값 character
Description
사진 속 피사체의 종류로, Meshy가 이를 어떻게 스타일화할지를 결정합니다.
사용 가능한 값:
- character: 피규어, 동물, 마스코트 등 단일 캐릭터 또는 사물
- landscape: 산, 도시 풍경, 숲 등 야외 장면이나 파노라마
Name
name
Type
string
Description
작업의 이름으로, 최대 100자까지 가능합니다. 작업의 name 필드로 반환됩니다. 이보다 긴 이름은 400을 반환합니다.
Name
remove_background
Type
boolean
기본값 false
Description
프로토타입 이미지에서 배경을 제거할지 여부입니다. true로 설정하면 투명한 RGBA PNG가 반환되어, 피사체를 어떤 배경 위에도 배치할 수 있습니다. 또한 Meshy는 배경을 제외한 이미지로부터 3D 모델을 생성합니다. Meshy가 배경을 제거할 수 없는 경우, 배경이 포함된 이미지를 그대로 사용하며 작업은 여전히 성공합니다.

반환 값

result 필드에는 새로 생성된 prototype 작업의 ID가 담깁니다. 작업을 조회하거나 스트리밍하여 status가 SUCCEEDED가 될 때까지 기다리세요. 그런 다음 해당 ID를 input_task_id로 build 엔드포인트에 전달하세요.

실패 모드

Name
400 - Bad Request
Description
요청을 실행할 수 없습니다. 예를 들면:
- image_url이 누락되었습니다.
- 이미지가 JPG, JPEG, PNG, WebP 파일이 아닙니다.
- 이미지가 너무 작거나, 20MB를 초과하거나, 최대 픽셀 수를 초과합니다.
- Meshy가 이미지를 다운로드할 수 없습니다. 예를 들어 URL이 404를 반환하거나 타임아웃이 발생한 경우입니다.
- data URI가 유효한 base64가 아닙니다.
- 이미지가 NSFW로 플래그 처리되었습니다.
- image_subject가 character 또는 landscape가 아닙니다.
오류 메시지에 어떤 문제가 발견되었는지 표시됩니다. 요청을 수정한 후 다시 보내세요.
Name
401 - Unauthorized
Description
API 키가 누락되었거나 유효하지 않습니다. Authorization 헤더를 확인하세요.
Name
402 - Payment Required
Description
다음 중 하나에 해당합니다:
- 계정에 크레딧이 충분하지 않습니다.
- API 키, 작업 공간, 또는 멤버가 크레딧 한도에 도달했습니다.
- 계정이 무료 플랜을 사용 중입니다.
크레딧과 플랜을 확인한 후 다시 시도하세요.
Name
403 - Forbidden
Description
팀에서 IP Filtering이 활성화되어 있고, Meshy가 해당 이미지를 제3자 지적 재산권 문제로 플래그 처리했습니다. 사용 권한이 있는 이미지를 보내세요.
Name
429 - Too Many Requests
Description
다음 한도 중 하나에 도달했습니다:
- 속도 제한을 초과하는 요청을 보냈습니다. 몇 초 기다린 후 다시 시도하세요. Rate limits를 참고하세요.
- 대기 중이거나 실행 중인 작업이 너무 많습니다. 일부가 완료될 때까지 기다린 후 다시 시도하세요.
- 크레딧이 남아있지 않은 무제한 플랜에서, 크레딧 없이 실행할 수 있는 작업 수에 도달했습니다. 작업이 완료되기를 기다리거나 크레딧을 추가하세요.
Name
500 - Internal Server Error
Description
Meshy에서 서버 오류가 발생했습니다. 예를 들어 이미지에 대한 지적 재산권 검사를 실행할 수 없었던 경우입니다. Meshy는 작업을 생성하지 않으며, 청구된 크레딧이 있다면 환불합니다. 요청을 다시 시도하세요.

POST/openapi/creative-lab/lamp/v1/build

Create a Lamp build task

성공한 프로토타입 작업으로부터 3D 프린팅 가능한 부품을 생성합니다. Meshy는 프로토타입의 모델을 diameter_mm까지 스케일링하고, cut_amount_percent만큼 바닥을 평평하게 자르고, thickness_mm까지 속을 비웁니다. 피팅(fixture) 프리셋을 사용하면 바닥을 열고, 피팅 홀이 있는 베이스 플레이트를 추가하며, 조명을 위한 별도의 마운트도 만듭니다. 작업의 필드에 대해서는 The Lamp build task object를 참조하세요.

Request

POST

/openapi/creative-lab/lamp/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "options": {
      "diameter_mm": 120,
      "thickness_mm": 2,
      "light_source_preset": "bambu_mh001_60mm",
      "cut_amount_percent": 30
    },
    "output": {
      "format": "stl"
    }
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}

Build example

The build task turns the prototype's 3D model into printable lampshade parts.

Creative Lab Lamp build model preview — Build model preview

매개변수

Name
input_task_id
Type
string
필수
Description
빌드할 프로토타입 작업의 ID입니다. 이는 POST /openapi/creative-lab/lamp/v1/prototype로 사용자의 계정이 생성한 작업이어야 하며, 상태는 SUCCEEDED여야 합니다.
API를 통해 생성된 사용자의 Lamp 프로토타입 작업이 아닌 ID는 404를 반환하며, 웹 앱에서 만든 프로토타입도 포함됩니다.
Name
name
Type
string
Description
작업의 이름으로, 최대 100자까지 가능합니다. 작업의 name 필드로 반환됩니다. 이름이 더 길면 400이 반환됩니다.

`options`

램프 갓(lampshade)의 형태에 대한 선택적 설정입니다. 모든 필드에는 기본값이 있으므로, 변경하고 싶은 값만 전송하면 됩니다.

Name
diameter_mm
Type
number
기본값 150
Description
램프 갓의 최대 치수 크기이며, 밀리미터 단위로 50에서 400까지입니다. Meshy는 모델을 균등하게 스케일링하여 맞춥니다. 0은 기본값을 사용하며, 범위를 벗어난 다른 값은 400을 반환합니다.
Name
thickness_mm
Type
number
기본값 1
Description
램프 갓의 벽 두께이며, 밀리미터 단위로 최대 10까지입니다. 0은 기본값을 사용하며, 음수 값이나 10을 초과하는 값은 400을 반환합니다.
Name
cut_amount_percent
Type
number
기본값 1
Description
모델 높이 중 바닥에서 평평하게 자를 비율로, 1에서 100까지입니다. 평평한 바닥은 램프 갓이 프린트 베드 위에 놓일 수 있게 하고 피팅을 위한 공간을 남겨둡니다. 범위를 벗어난 값은 400을 반환합니다.
Name
light_source_preset
Type
string
기본값 bambu_mh001_60mm
Description
조명 피팅 프리셋이며, Meshy가 바닥을 만드는 방식을 설정합니다.
사용 가능한 값:
- bambu_mh001_60mm: 60mm 피팅 홀이 있는 베이스 플레이트가 포함된, 바닥이 열린 램프 갓으로, 둘 다 model_urls.lamp_stl에 있으며, 피팅 마운트는 model_urls.base_stl에 있습니다
- none: model_urls.lamp_stl에 밀폐된 단일 램프 갓이며, model_urls.base_stl은 없습니다
Name
fixture_offset_x_mm
Type
number
기본값 0
Description
램프 갓의 중심에서 X축을 따라 피팅 홀을 이동할 거리이며, 밀리미터 단위로 -80에서 80까지입니다. light_source_preset이 none이 아닐 때만 적용됩니다.
Name
fixture_offset_z_mm
Type
number
기본값 0
Description
램프 갓의 중심에서 Z축(깊이)을 따라 피팅 홀을 이동할 거리이며, 밀리미터 단위로 -80에서 80까지입니다. light_source_preset이 none이 아닐 때만 적용됩니다.
Name
rotate_x_deg
Type
number
기본값 0
Description
Meshy가 모델을 처리하기 전에 적용할 X축 기준 회전이며, 도(degree) 단위로 -360에서 360까지입니다. Meshy는 모델 중심을 기준으로 XYZ 오일러 각도로 세 가지 회전을 적용합니다.
Name
rotate_y_deg
Type
number
기본값 0
Description
Meshy가 모델을 처리하기 전에 적용할 Y축 기준 회전이며, 도(degree) 단위로 -360에서 360까지입니다.
Name
rotate_z_deg
Type
number
기본값 0
Description
Meshy가 모델을 처리하기 전에 적용할 Z축 기준 회전이며, 도(degree) 단위로 -360에서 360까지입니다.
Name
include_result_json
Type
boolean
기본값 false
Description
zip 번들에 result.json 파일을 추가할지 여부이며, 실행된 파이프라인의 이름, 경고, 파일 경로가 포함됩니다. output.format이 zip으로 설정되어 있어야 합니다. stl과 함께 true로 설정하면 400이 반환됩니다.

`output`

선택 사항입니다. 빌드가 반환하는 파일을 설정합니다.

Name
format
Type
string
기본값 stl
Description
빌드가 반환하는 파일입니다.
사용 가능한 값:
- stl: model_urls.lamp_stl은 피팅 프리셋이 있을 때 베이스 플레이트가 포함된 램프 갓이며, light_source_preset이 none이 아닐 때 model_urls.base_stl이 함께 제공됩니다
- zip: model_urls.bundle_zip에 하나의 zip 파일이 있으며, lamp.stl과, 해당하는 경우 base.stl 및 result.json이 포함됩니다

반환 값

result 필드에는 새 빌드 작업의 ID가 들어 있습니다. status가 SUCCEEDED가 될 때까지 작업을 가져오거나 스트리밍하세요. 그런 다음 model_urls에서 파일을 다운로드하세요.

실패 모드

Name
400 - Bad Request
Description
요청을 실행할 수 없습니다. 예를 들어:
- input_task_id가 누락되었거나 유효한 작업 ID가 아닙니다.
- 프로토타입 작업의 상태가 SUCCEEDED가 아닙니다. 아직 실행 중이라면 기다렸다가 다시 시도하세요. 실패했거나 취소되었다면 새 프로토타입 작업을 생성하세요.
- 프로토타입 작업은 성공했지만 3D 모델이 없습니다. 새 프로토타입 작업을 생성하세요.
- options 필드가 범위를 벗어났거나 사용 가능한 값이 아닙니다.
- output.format이 stl 또는 zip이 아니거나, include_result_json이 zip 없이 true로 설정되어 있습니다.
오류 메시지는 어떤 문제가 발견되었는지 알려줍니다.
Name
401 - Unauthorized
Description
API 키가 누락되었거나 유효하지 않습니다. Authorization 헤더를 확인하세요.
Name
402 - Payment Required
Description
다음 중 하나가 해당합니다:
- 계정에 크레딧이 충분하지 않습니다.
- API 키, 작업 공간, 또는 구성원이 크레딧 한도에 도달했습니다.
- 계정이 무료 플랜을 사용 중입니다.
크레딧과 플랜을 확인한 후 다시 시도하세요.
Name
404 - Not Found
Description
input_task_id가 사용자의 계정이 API로 생성한 어떤 Lamp 프로토타입 작업과도 일치하지 않습니다. 웹 앱에서 만든 프로토타입도 404를 반환합니다. 프로토타입 생성 응답의 result ID를 전송하세요.
Name
429 - Too Many Requests
Description
다음 제한 중 하나에 도달했습니다:
- 속도 제한이 허용하는 것보다 많은 요청을 보냈습니다. 몇 초 기다린 후 다시 시도하세요. Rate limits를 참조하세요.
- 대기 중이거나 실행 중인 작업이 너무 많습니다. 일부가 완료될 때까지 기다린 후 다시 시도하세요.
- 크레딧이 남아 있지 않은 무제한 플랜에서, 크레딧 없이 실행할 수 있는 작업 수에 도달했습니다. 작업이 완료되기를 기다리거나 크레딧을 추가하세요.

GET/openapi/creative-lab/lamp/v1/(prototype|build)/:id

Lamp 작업 가져오기

prototype 또는 build 작업을 반환합니다. 경로는 작업의 단계와 일치해야 합니다. /prototype/:id를 통해 요청된 build 작업은 404를 반환하며, /build/:id를 통해 요청된 prototype 작업도 마찬가지입니다.

필드에 대해서는 Lamp prototype 작업 객체와 Lamp build 작업 객체를 참조하세요.

Request

GET

/openapi/creative-lab/lamp/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-lamp-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-lamp-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "lamp_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/lamp.stl?Expires=***",
    "base_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/base.stl?Expires=***"
  }
}

매개변수

Name
id
Type
path
Description
생성 응답에서 받은 작업 ID입니다.

반환값

경로의 단계에 맞는 prototype 작업 객체 또는 build 작업 객체입니다.

실패 모드

Name
400 - Bad Request
Description
id가 유효한 작업 ID가 아닙니다. 생성 응답의 result ID를 보내세요.
Name
403 - Forbidden
Description
팀에서 IP Filtering이 켜져 있고, Meshy가 prototype 작업의 이미지를 제3자 지적 재산권 문제로 표시했습니다. build 작업과 Enterprise 플랜의 팀에는 이 오류가 발생하지 않습니다. 사용 권한이 있는 이미지로 prototype 작업을 생성하세요.
Name
404 - Not Found
Description
이 ID를 가진 Lamp 작업이 계정에 없거나, 작업의 단계가 경로와 일치하지 않습니다. ID를 확인하고 작업에 맞게 /prototype 또는 /build를 사용하세요.
Name
500 - Internal Server Error
Description
Meshy가 지적 재산권 검사를 실행하지 못했습니다. 요청을 재시도하세요.

DELETE/openapi/creative-lab/lamp/v1/(prototype|build)/:id

Lamp 작업 삭제

Lamp 작업을 취소합니다. PENDING 작업을 취소하면 크레딧이 환불됩니다. IN_PROGRESS 작업은 이미 워커가 작업을 시작했기 때문에 환불 없이 취소됩니다. 최종 상태(SUCCEEDED, FAILED, 또는 CANCELED)인 작업은 취소할 수 없습니다.

경로는 작업의 단계와 일치해야 합니다. 예를 들어, 빌드 작업의 ID로 /prototype/:id에 DELETE를 호출하면 404가 반환됩니다.

Request

DELETE

/openapi/creative-lab/lamp/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/lamp/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).

경로 매개변수

Name
id
Type
path
Description
취소할 작업의 ID입니다.

반환값

빈 본문과 함께 204 No Content가 반환됩니다.

실패 모드

Name
400 - Bad Request
Description
다음 중 하나에 해당합니다:
- id가 유효한 작업 ID가 아닙니다. 생성 응답에서 받은 result ID를 보내세요.
- 작업이 이미 최종 상태(SUCCEEDED, FAILED, 또는 CANCELED)이므로 취소할 수 없습니다.
Name
404 - Not Found
Description
이 ID를 가진 Lamp 작업이 사용자의 계정에 없거나, 작업의 단계가 경로와 일치하지 않습니다. ID를 확인하고 작업에 맞게 /prototype 또는 /build를 사용하세요.

GET/openapi/creative-lab/lamp/v1/(prototype|build)/:id/stream

램프 작업 스트리밍

램프 작업의 업데이트를 서버 전송 이벤트(SSE)로 스트리밍합니다. 경로는 작업의 단계와 일치해야 합니다. 일치하지 않는 경우, 예를 들어 build 작업의 ID로 /prototype/:id/stream을 호출하면, 스트림은 status_code: 404와 함께 하나의 error 이벤트를 전송하고 닫힙니다.

Request

GET

/openapi/creative-lab/lamp/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream

curl -N https://api.meshy.ai/openapi/creative-lab/lamp/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (wrong stage or task not found)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object; fields not yet populated are null / empty.
// The following PENDING frame is shortened to the fields that change.
event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-lamp-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "lamp_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/lamp.stl?Expires=***",
    "base_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/base.stl?Expires=***"
  }
}

매개변수

Name
id
Type
path
Description
생성 응답에서의 작업 ID입니다.

반환값

prototype 또는 build 작업 객체의 스트림입니다. 각 이벤트는 램프 작업 가져오기가 반환하는 것과 동일한 전체 작업 객체를 포함합니다. 작업이 PENDING 또는 IN_PROGRESS 상태인 동안에는 출력 필드가 여전히 비어 있으며(null, [], 또는 {}), finished_at은 null입니다.

IP 필터링이 작업 결과를 차단하는 경우, 스트림은 그 자리에 get 요청이 반환했을 status_code와 함께 하나의 error 이벤트를 전송합니다.

GET/openapi/creative-lab/lamp/v1/(prototype|build)

Lamp 작업 목록 조회

한 단계(stage)에 해당하는 Lamp 작업을 한 번에 한 페이지씩 반환합니다. 경로(path)가 단계를 선택합니다. /prototype은 프로토타입 작업만 반환하고, /build는 빌드 작업만 반환합니다.

Request

GET

/openapi/creative-lab/lamp/v1/prototype

# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-lamp-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123486000,
    "expires_at": 1729382686000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 30,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

경로 매개변수

Name
stage
Type
path
필수
Description
조회할 단계로, prototype 또는 build입니다.

쿼리 매개변수

Name
page_num
Type
integer
기본값 1
Description
반환할 페이지로, 1부터 255까지입니다. 0은 첫 번째 페이지를 반환합니다. 0에서 255 범위를 벗어난 값은 400을 반환합니다.
Name
page_size
Type
integer
기본값 10
Description
페이지당 작업 수로, 최대 100까지입니다. 101에서 255 사이의 값은 100개의 작업을 반환하며, 0은 기본값을 사용합니다. 0에서 255 범위를 벗어난 값은 400을 반환합니다.
Name
sort_by
Type
string
기본값 -created_at
Description
정렬 순서입니다.
사용 가능한 값:
- -created_at: 최신순
- +created_at: 오래된순

반환값

경로의 단계와 일치하는 prototype 작업 객체 또는 build 작업 객체의 배열입니다.

램프 프로토타입 태스크 객체

프로토타입 태스크는 사진으로부터 무광 흰색 콘셉트 이미지를 생성하고 이를 3D 모델로 변환합니다. 인쇄 가능한 부품을 만들려면 해당 태스크의 ID를 input_task_id로 build 엔드포인트에 전달하세요.

속성

Example Lamp Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-lamp-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Name
id
Type
string
Description
태스크 ID입니다. 이 값의 형식에 의존하지 마세요.
Name
type
Type
string
Description
태스크 유형으로, 항상 creative-lab-lamp-prototype입니다.
Name
name
Type
string
Description
태스크를 생성할 때 전송한 name이며, 보내지 않았다면 ""입니다.
Name
status
Type
string
Description
태스크의 상태입니다.
사용 가능한 값:
- PENDING: 대기열에서 대기 중
- IN_PROGRESS: 결과 생성 중
- SUCCEEDED: 최종 상태이며, 결과 포함
- FAILED: 최종 상태이며, 사유는 task_error에 있음
- CANCELED: 최종 상태이며, 결과 없음
Name
progress
Type
integer
Description
작업이 완료된 비율로, 0부터 100까지입니다. 태스크가 시작되기 전까지는 0이며 성공하면 100입니다.
Name
created_at
Type
timestamp
Description
태스크가 생성된 시간으로, 유닉스 밀리초 단위입니다.
Name
started_at
Type
timestamp
Description
워커가 태스크를 시작한 시간으로, 유닉스 밀리초 단위입니다. 그 전까지는 null입니다.
Name
finished_at
Type
timestamp
Description
태스크가 최종 상태에 도달한 시간으로, 유닉스 밀리초 단위입니다. 그 전까지는 null입니다.
Name
expires_at
Type
timestamp
Description
태스크 결과가 만료되는 시간으로, 유닉스 밀리초 단위입니다. finished_at 이후 3일이며, 태스크가 완료되기 전까지는 created_at 이후 3일입니다. API 결과를 무기한 보관하는 Enterprise 계정의 경우에는 약 100년 후입니다. 에셋 보존을 참고하세요.
Name
preceding_tasks
Type
integer
Description
태스크가 PENDING 상태일 때 대기열에서의 위치입니다. 1은 다음 차례로 시작됨을 의미합니다. 태스크가 대기열을 벗어나면 0이 되며, 목록 결과에서는 항상 0입니다.
Name
task_error
Type
object
Description
태스크가 실패한 이유입니다. status가 FAILED가 아니면 null입니다. 오류를 참고하세요.
Name
consumed_credits
Type
integer
Description
환불 이후 태스크에 청구된 크레딧 수입니다. 오류를 반환하는 요청에는 요금이 청구되지 않습니다. 실패한 태스크는 Meshy가 환불하므로 0입니다. 취소는 태스크가 PENDING 상태인 동안에만 환불됩니다. Meshy가 청구 내역을 읽을 수 없는 경우, get 또는 스트림 응답에서는 이 필드가 생략되며, 목록 요청은 500을 반환합니다. 이 경우 요청을 다시 시도하세요.
Name
model_urls
Type
object
Description
콘셉트 이미지로부터 생성된 3D 모델의 다운로드 URL입니다. 태스크가 성공하기 전까지는 {}입니다.
- Name
  glb
  Type
  string
  Description
  GLB 파일 형태의 램프갓 모델 다운로드 URL입니다. build 단계에서 이 모델을 인쇄 가능한 부품으로 변환합니다.
Name
thumbnail_url
Type
string
Description
3D 모델의 미리보기 이미지 다운로드 URL입니다. 태스크가 성공하기 전까지는 ""입니다.
Name
image_urls
Type
array of strings
Description
콘셉트 이미지의 다운로드 URL입니다. 태스크가 성공한 후에는 배열에 URL이 하나 있으며, 그 전까지는 비어 있습니다.

램프 빌드 작업 객체

빌드 작업은 성공한 프로토타입 작업의 3D 모델을 인쇄 가능한 램프 갓 부품으로 변환합니다. Meshy는 모델을 속이 비도록 만들고 바닥을 평평하게 자릅니다. 픽스처 프리셋을 사용하면 바닥도 열고 베이스 플레이트와 픽스처 마운트를 추가합니다.

속성

Example Lamp Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-lamp-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "lamp_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/lamp.stl?Expires=***",
    "base_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/base.stl?Expires=***"
  }
}

Name
id
Type
string
Description
작업 ID입니다. 이 값의 형식에 의존하지 마세요.
Name
type
Type
string
Description
작업 유형이며, 항상 creative-lab-lamp-build입니다.
Name
name
Type
string
Description
작업을 생성할 때 보낸 name이며, 보내지 않았다면 ""입니다.
Name
status
Type
string
Description
작업의 상태입니다.
사용 가능한 값:
- PENDING: 대기열에서 대기 중
- IN_PROGRESS: 결과를 생성하는 중
- SUCCEEDED: 최종 상태이며, 결과 포함
- FAILED: 최종 상태이며, 사유는 task_error에 있음
- CANCELED: 최종 상태이며, 결과 없음
Name
progress
Type
integer
Description
작업 완료 비율로, 0에서 100까지입니다. 작업이 시작되기 전까지는 0이고, 성공하면 100입니다.
Name
created_at
Type
timestamp
Description
작업이 생성된 시각으로, 유닉스 밀리초 단위입니다.
Name
started_at
Type
timestamp
Description
워커가 작업을 시작한 시각으로, 유닉스 밀리초 단위입니다. 시작 전까지는 null입니다.
Name
finished_at
Type
timestamp
Description
작업이 최종 상태에 도달한 시각으로, 유닉스 밀리초 단위입니다. 도달 전까지는 null입니다.
Name
expires_at
Type
timestamp
Description
작업 결과가 만료되는 시각으로, 유닉스 밀리초 단위입니다. finished_at 이후 3일이며, 작업이 끝나기 전까지는 created_at 이후 3일입니다. API 결과를 무기한 보관하는 Enterprise 계정의 경우, 약 100년 뒤입니다. 에셋 보존을 참고하세요.
Name
preceding_tasks
Type
integer
Description
작업이 PENDING 상태인 동안 대기열에서의 위치입니다. 1은 다음 차례로 시작됨을 의미합니다. 작업이 대기열을 벗어나면 0이며, 목록 결과에서는 항상 0입니다.
Name
task_error
Type
object
Description
작업이 실패한 이유입니다. status가 FAILED가 아니면 null입니다. 오류를 참고하세요.
Name
consumed_credits
Type
integer
Description
환불을 반영한 후 작업에 부과된 크레딧 수입니다. 오류를 반환하는 요청에는 요금이 부과되지 않습니다. 실패한 작업은 Meshy가 환불하므로 0입니다. 취소는 작업이 PENDING 상태인 동안에만 환불됩니다. Meshy가 요금을 읽을 수 없는 경우, get 또는 스트림 응답에서는 이 필드가 생략되고, 목록 요청은 500을 반환합니다. 이 경우 요청을 다시 시도하세요.
Name
model_urls
Type
object
Description
인쇄 가능한 파일의 다운로드 URL입니다. 어떤 키가 나타나는지는 output.format과 options.light_source_preset에 따라 달라집니다.
- Name
  lamp_stl
  Type
  string
  Description
  lamp.stl의 다운로드 URL입니다. 픽스처 프리셋을 사용하면, 픽스처 구멍이 있는 베이스 플레이트와 함께 바닥이 열린 램프 갓입니다. options.light_source_preset이 none으로 설정되면, 단일 밀봉 램프 갓입니다. output.format이 stl일 때 제공됩니다.
- Name
  base_stl
  Type
  string
  Description
  조명 픽스처용 마운트인 base.stl의 다운로드 URL입니다. output.format이 stl이고 options.light_source_preset이 none이 아닐 때 제공됩니다.
- Name
  bundle_zip
  Type
  string
  Description
  lamp.stl과, 해당하는 경우 base.stl 및 result.json이 포함된 zip 파일의 다운로드 URL입니다. output.format이 zip일 때 제공되며, 이 경우 lamp_stl과 base_stl은 생략됩니다.