Creative Lab — 램프 API

원본 사진을 두 단계에 걸쳐 3D 프린팅이 가능한 램프갓으로 변환합니다: 프로토타입 단계에서는 스타일화된 무광 화이트 콘셉트 이미지를 생성하고 이를 속이 빈 3D 모델(GLB)로 변환하며, 이어서 빌드 단계에서는 해당 모델에 대해 램프 프로세서를 실행하여 프린팅 가능한 STL 부품—광원 조명 기구용 베이스 플레이트가 있는 밑면이 뚫린 램프갓과 조명 기구 마운트 자체—를 생성합니다. 두 단계는 input_task_id를 통해 연결됩니다.

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

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

램프 프로토타입 태스크 생성

참조 사진으로부터 단일 무광 화이트 컨셉 이미지를 생성하고 이를 속이 빈 3D 램프갓 모델로 변환합니다. 응답에는 컨셉 이미지(image_urls)와 3D 모델(thumbnail_url이 포함된 model_urls.glb)이 모두 포함됩니다. 반환된 태스크 ID는 빌드 엔드포인트에 input_task_id로 전달하는 값입니다. 응답 형식에 대해서는 램프 프로토타입 태스크 객체를 참고하세요.

파라미터

Name
image_url
Type
string
필수
Description
Meshy가 램프갓의 시각적 참조로 사용하는 소스 사진입니다. 현재 .jpg, .jpeg, .png, .webp 형식을 지원합니다.
이미지를 제공하는 방법에는 두 가지가 있습니다:
- 공개적으로 접근 가능한 URL: 공개 인터넷에서 접근할 수 있는 URL입니다.
- Data URI: 이미지의 base64로 인코딩된 data URI입니다. Data URI 예시: data:image/jpeg;base64,<your base64-encoded image data>.

Name
image_subject
Type
string
기본값 character
Description
스타일화 prompt를 선택하는 대상 카테고리 힌트입니다. 사용 가능한 값:
- character(기본값) — 단일 캐릭터/오브젝트 대상(피규어, 동물, 마스코트 등).
- landscape — 야외 장면/파노라마 대상(산, 도시 풍경, 숲 등).
Name
name
Type
string
Description
표시 목적의 선택적 태스크 이름입니다. 최대 100자입니다.
Name
remove_background
Type
boolean
기본값 false
Description
true로 설정하면 프로토타입 이미지가 배경이 제거된 투명 RGBA PNG로 반환되므로, 대상을 원하는 배경에 합성할 수 있습니다.

반환값

응답의 result 속성에는 새로 생성된 램프 프로토타입 태스크의 태스크 id가 포함됩니다. 태스크가 SUCCEEDED에 도달할 때까지 태스크 조회 엔드포인트를 폴링하거나 스트림을 구독한 다음, 해당 ID를 빌드 엔드포인트에 input_task_id로 전달하세요.

실패 모드

Name
400 - Bad Request
Description
요청이 허용되지 않았습니다. 일반적인 원인:
- 파라미터 누락: image_url이 필요합니다.
- 잘못된 이미지 형식: 제공된 image_url이 지원되는 형식(.jpg, .jpeg, .png, .webp)이 아닙니다.
- 이미지 크기 범위 초과: 이미지가 너무 작거나, 최대 파일 크기를 초과하거나, 최대 픽셀 수를 초과합니다.
- 접근 불가능한 URL: image_url을 다운로드할 수 없습니다(404 또는 timeout).
- 잘못된 Data URI: base64 문자열의 형식이 올바르지 않습니다.
- 콘텐츠 플래그 처리됨: 입력 이미지가 NSFW 또는 지적 재산권 moderation에 의해 플래그 처리되었습니다.
- 잘못된 image_subject: character / landscape 중 하나가 아닙니다.
Name
401 - Unauthorized
Description
인증에 실패했습니다. API 키를 확인해 주세요.
Name
402 - Payment Required
Description
이 작업을 수행하기에 크레딧이 부족합니다.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다.

Request

POST

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

# Stage 1: concept image + hollow 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 a hollow 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

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

Create a Lamp Build Task

성공한 프로토타입 작업으로부터 최종 3D 프린팅용 부품을 생성합니다. 빌드는 프로토타입의 3D 모델에 대해 램프 프로세서를 실행합니다: 모델을 diameter_mm로 스케일링하고, cut_amount_percent만큼 바닥을 평평하게 자르고, thickness_mm까지 속을 비우고, 바닥을 열고 — 고정구(fixture) 프리셋이 선택된 경우 — 고정구 구멍이 있는 베이스 플레이트와 광원용 별도 마운트를 추가합니다. 응답 형태는 The Lamp Build Task Object를 참조하세요.

파라미터

Name
input_task_id
Type
string
필수
Description
동일한 OpenAPI 엔드포인트를 통해 생성된 프로토타입 작업의 작업 ID입니다. 프로토타입은 동일한 API 키로 생성되었어야 하고, SUCCEEDED 상태에 도달했어야 하며, 3D 모델을 생성했어야 합니다.
웹앱을 통해 생성된 프로토타입 작업은 허용되지 않습니다 — 빌드 엔드포인트는 POST /openapi/creative-lab/lamp/v1/prototype으로 생성된 프로토타입 작업만 허용하며, 그 외의 출처는 404로 거부합니다.
Name
name
Type
string
Description
표시용 선택적 작업 이름입니다. 최대 100자입니다.

`options`

램프갓 지오메트리에 대한 선택적 조정 파라미터입니다. 모든 필드에는 합리적인 기본값이 있습니다 — 재정의하고 싶은 항목만 전송하세요.

Name
diameter_mm
Type
number
기본값 150
Description
램프갓 바운딩 박스의 목표 최대 치수로, 밀리미터 단위입니다. 메시는 균일하게 스케일링되어 맞춰집니다. 범위: [50, 400].
Name
thickness_mm
Type
number
기본값 1
Description
속이 빈 램프갓의 벽 두께로, 밀리미터 단위입니다. 범위: (0, 10].
Name
cut_amount_percent
Type
number
기본값 1
Description
모델 높이 중 바닥에서 평평하게 잘라내는 비율로, 램프갓이 프린트 베드 위에 놓이고 고정구를 위한 개구부를 갖도록 합니다. 범위: [1, 100].
Name
light_source_preset
Type
string
기본값 bambu_mh001_60mm
Description
바닥이 어떻게 만들어지는지를 결정하는 광원 고정구 프리셋입니다. 사용 가능한 값:
- 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축 오프셋으로, 램프갓 중심 기준 밀리미터 단위입니다. light_source_preset이 none이 아닐 때만 의미가 있습니다. 범위: [-80, 80].
Name
fixture_offset_z_mm
Type
number
기본값 0
Description
베이스 플레이트 위 고정구 구멍의 Z축(깊이) 오프셋으로, 램프갓 중심 기준 밀리미터 단위입니다. light_source_preset이 none이 아닐 때만 의미가 있습니다. 범위: [-80, 80].
Name
rotate_x_deg
Type
number
기본값 0
Description
처리 전 모델에 적용되는 X축 기준 회전으로, 도(degree) 단위입니다. 세 회전은 모델 중심을 기준으로 XYZ 오일러 각으로 적용됩니다. 범위: [-360, 360].
Name
rotate_y_deg
Type
number
기본값 0
Description
처리 전 가져온 메시에 적용되는 Y축 기준 회전으로, 도(degree) 단위입니다. 범위: [-360, 360].
Name
rotate_z_deg
Type
number
기본값 0
Description
처리 전 가져온 메시에 적용되는 Z축 기준 회전으로, 도(degree) 단위입니다. 범위: [-360, 360].
Name
include_result_json
Type
boolean
기본값 false
Description
true이고 output.format이 zip인 경우, 번들 안에 램프 프로세서의 result.json(파이프라인 이름, 경고, 아티팩트 경로)을 포함합니다. output.format이 stl인 경우에는 무시됩니다.

`output`

선택적 전송 형식 선택기입니다. 기본값은 stl입니다.

Name
format
Type
string
기본값 stl
Description
빌드에서 반환되는 아티팩트 번들입니다. 사용 가능한 값:
- stl (기본값) — model_urls.lamp_stl(고정구 프리셋이 설정된 경우 베이스 플레이트와 함께 램프갓)을 반환하며, light_source_preset이 none이 아닌 경우 model_urls.base_stl도 반환합니다.
- zip — 프로세서가 생성하는 모든 아티팩트(lamp.stl, 선택적 base.stl, 선택적 result.json)를 하나의 zip으로 패키징하여 model_urls.bundle_zip 아래로 반환합니다.

반환값

응답의 result 속성에는 새로 생성된 램프 빌드 작업의 작업 id가 포함됩니다. 작업이 SUCCEEDED에 도달할 때까지 Get a Task 엔드포인트를 폴링하거나 stream을 구독한 다음, model_urls에서 아티팩트를 다운로드하세요.

실패 모드

Name
400 - Bad Request
Description
요청이 허용되지 않았습니다. 일반적인 원인:
- 파라미터 누락: input_task_id가 필요합니다.
- 잘못된 UUID: input_task_id가 유효한 UUID가 아닙니다.
- 부모 작업 미완료: 참조된 프로토타입 작업이 아직 SUCCEEDED에 도달하지 않았습니다.
- 모델 없음: 프로토타입 작업은 성공했지만 3D 모델을 생성하지 못했습니다.
- 옵션 범위 초과: options 필드 중 하나가 허용된 범위 또는 열거값 집합을 벗어났습니다.
Name
401 - Unauthorized
Description
인증에 실패했습니다. API 키를 확인해 주세요.
Name
402 - Payment Required
Description
이 작업을 수행하기에 크레딧이 부족합니다.
Name
404 - Not Found
Description
참조된 프로토타입 작업이 존재하지 않거나, 다른 사용자에게 속해 있거나, 웹앱을 통해 생성되었습니다(API 모드 프로토타입 작업만 빌드로 연결될 수 있습니다).
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다.

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

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

램프 작업 조회하기

유효한 작업 id를 사용하여 프로토타입 또는 빌드 작업을 조회합니다. URL 경로는 작업의 단계와 일치해야 합니다 — /prototype/:id를 통해 조회한 빌드 작업은 404를 반환하며, 그 반대의 경우도 마찬가지입니다.

응답 형태에 대해서는 램프 프로토타입 작업 객체와 램프 빌드 작업 객체를 참고하세요.

매개변수

Name
id
Type
path
Description
조회할 램프 작업의 고유 식별자입니다.

반환값

응답에는 램프 작업 객체가 포함됩니다. 형태는 요청한 단계에 따라 달라집니다.

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

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

램프 작업 삭제

램프 작업을 취소합니다. 작업이 아직 PENDING 상태인 경우, 생성 시 소모된 크레딧이 환불됩니다. 이미 IN_PROGRESS 상태인 작업은 환불 없이 취소됩니다 (작업자가 이미 리소스를 소모하고 있을 수 있습니다). 이미 최종 상태(SUCCEEDED, FAILED, CANCELED)에 도달한 작업은 취소할 수 없습니다.

URL 경로는 작업의 단계와 일치해야 합니다 — /prototype/:buildId에서 DELETE는 404를 반환합니다.

경로 매개변수

Name
id
Type
path
Description
취소할 램프 작업의 고유 식별자입니다.

반환 값

성공 시 204 No Content를 빈 본문과 함께 반환합니다.

실패 모드

Name
400 - Bad Request
Description
작업이 이미 최종 상태에 있으며 취소할 수 없습니다.
Name
404 - Not Found
Description
작업이 존재하지 않거나, 다른 사용자에게 속하거나, 단계가 URL 경로와 일치하지 않습니다.

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).

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

램프 작업 스트리밍

Server-Sent Events(SSE)를 통해 램프 작업의 실시간 업데이트를 스트리밍합니다. URL 경로는 반드시 작업의 단계와 일치해야 하며, /prototype/:buildId/stream에서 스트림을 열면 status_code: 404가 포함된 단일 event: error 페이로드를 전송한 후 스트림을 닫습니다.

매개변수

Name
id
Type
path
Description
스트리밍할 램프 작업의 고유 식별자입니다.

반환값

Server-Sent Events로 Lamp Prototype 또는 Lamp Build 작업 객체의 스트림을 반환합니다. PENDING 또는 IN_PROGRESS 상태의 작업의 경우, 응답 스트림에는 필요한 progress 및 status 필드만 포함됩니다.

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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=***"
  }
}

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

램프 작업 목록 조회

단일 스테이지에 대한 램프 작업의 페이지네이션된 목록을 조회합니다. URL 경로가 스테이지를 선택합니다 — /prototype은 프로토타입 작업을 반환하고, /build는 빌드 작업을 반환합니다. 다른 스테이지의 작업은 어느 응답에도 포함되지 않습니다.

경로 매개변수

Name
stage
Type
path
필수
Description
prototype 또는 build 중 하나입니다. 이 컬렉션은 URL과 스테이지가 일치하는 작업만 반환합니다 — /prototype을 조회하면 빌드 작업은 절대 반환되지 않으며, 그 반대도 마찬가지입니다.

쿼리 매개변수

Name
page_num
Type
integer
기본값 1
Description
페이지네이션을 위한 페이지 번호입니다.
Name
page_size
Type
integer
기본값 10
Description
페이지 크기 제한입니다. 최대 허용 값은 50개 항목입니다.
Name
sort_by
Type
string
기본값 -created_at
Description
정렬 기준 필드입니다. 사용 가능한 값:
- +created_at: 생성 시간 오름차순으로 정렬합니다.
- -created_at: 생성 시간 내림차순으로 정렬합니다.

반환값

스테이지별 작업 객체의 페이지네이션된 목록을 반환합니다 — /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=***"
    ]
  }
]

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

램프 프로토타입 태스크 객체는 원본 사진으로부터 스타일화된 매트 화이트 컨셉 이미지를 생성하고 이를 속이 빈 3D 모델로 변환하는 작업을 Meshy가 추적하기 위한 작업 단위입니다. 이 단계의 출력은 input_task_id를 통해 빌드 단계로 연결됩니다.

속성

Name
id
Type
string
Description
태스크의 고유 식별자입니다. 구현 세부 사항으로는 태스크 id에 k-정렬 가능한 UUID를 사용하지만, id의 형식에 대해 어떠한 가정도 하지 않아야 합니다.
Name
type
Type
string
Description
태스크의 유형입니다. 값은 creative-lab-lamp-prototype입니다.
Name
name
Type
string
Description
태스크가 생성될 때 제공된 태스크 이름입니다. 이름이 제공되지 않은 경우 빈 문자열입니다.
Name
status
Type
string
Description
태스크의 상태입니다. 가능한 값은 PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED 중 하나입니다.
Name
progress
Type
integer
Description
태스크의 progress입니다. 태스크가 아직 시작되지 않은 경우 이 속성은 0입니다. 태스크가 성공하면 100이 됩니다.
Name
created_at
Type
timestamp
Description
태스크가 생성된 시각의 타임스탬프이며, 밀리초 단위입니다.
타임스탬프는 RFC 3339 표준을 따라 1970년 1월 1일 UTC 이후 경과된 밀리초 수를 나타냅니다. 예를 들어, 2023년 9월 1일 금요일 12:00:00 PM GMT는 1693569600000으로 표현됩니다. 이는 Meshy API의 모든 타임스탬프에 적용됩니다.
Name
started_at
Type
timestamp
Description
태스크가 시작된 시각의 타임스탬프이며, 밀리초 단위입니다. 태스크가 아직 시작되지 않은 경우 이 속성은 0입니다.
Name
finished_at
Type
timestamp
Description
태스크가 완료된 시각의 타임스탬프이며, 밀리초 단위입니다. 태스크가 아직 완료되지 않은 경우 이 속성은 0입니다.
Name
expires_at
Type
timestamp
Description
태스크 결과가 만료되는 시각의 타임스탬프이며, 밀리초 단위입니다.
Name
preceding_tasks
Type
integer
Description
선행 태스크의 개수입니다.
이 필드의 값은 태스크 상태가 PENDING일 때만 의미가 있습니다.
Name
task_error
Type
object
Description
실패한 태스크에 대한 오류 세부 정보입니다. 전체 task_error 객체 참조는 오류를 참고하세요.
Name
consumed_credits
Type
integer
Description
이 태스크에서 소비된 크레딧 수입니다. 태스크 상태가 PENDING, IN_PROGRESS, SUCCEEDED일 때 존재합니다. FAILED 태스크의 경우 0을 반환합니다(실패 시 크레딧은 환불됩니다).
Name
model_urls
Type
object
Description
컨셉 이미지로부터 생성된 3D 모델의 다운로드 가능한 URL입니다. 태스크가 성공하면 존재하며, 그 전에는 {}입니다.
- Name
  glb
  Type
  string
  Description
  속이 빈 매트 화이트 램프갓 모델의 GLB 형식 다운로드 가능한 URL입니다. 이는 빌드 단계에서 처리하는 모델입니다.
Name
thumbnail_url
Type
string
Description
3D 모델의 렌더링된 미리보기에 대한 다운로드 가능한 URL입니다. 태스크가 성공하기 전까지는 빈 문자열입니다.
Name
image_urls
Type
array of strings
Description
이 프로토타입 태스크에서 생성된 컨셉 이미지 후보들에 대한 다운로드 가능한 URL입니다. 현재 API는 항상 정확히 하나의 후보를 반환하지만, 향후 개정에서 호환성을 깨뜨리지 않고 여러 후보를 노출할 수 있도록 이 필드는 배열로 되어 있습니다.

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=***"
  ]
}

램프 빌드 태스크 오브젝트

램프 빌드 태스크 오브젝트는 성공한 프로토타입 태스크로부터 3D 프린팅이 가능한 최종 램프갓을 생성하기 위해 Meshy가 추적하는 작업 단위입니다. 빌드는 프로토타입의 3D 모델에 램프 프로세서를 실행하여 내부를 비우고, 바닥을 평평하게 펴서 개방하며, (픽스처 프리셋이 있는 경우) 베이스 플레이트와 픽스처 마운트를 추가합니다.

속성

Name
id
Type
string
Description
태스크의 고유 식별자입니다.
Name
type
Type
string
Description
태스크의 유형입니다. 값은 creative-lab-lamp-build입니다.
Name
name
Type
string
Description
태스크 생성 시 제공된 태스크 이름입니다. 이름이 제공되지 않은 경우 빈 문자열입니다.
Name
status
Type
string
Description
태스크의 상태입니다. 가능한 값은 PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED 중 하나입니다.
Name
progress
Type
integer
Description
태스크의 progress입니다. 태스크가 아직 시작되지 않은 경우 이 속성은 0입니다. 태스크가 성공하면 100이 됩니다.
Name
created_at
Type
timestamp
Description
태스크가 생성된 시점의 타임스탬프(밀리초)입니다.
Name
started_at
Type
timestamp
Description
태스크가 시작된 시점의 타임스탬프(밀리초)입니다.
Name
finished_at
Type
timestamp
Description
태스크가 종료된 시점의 타임스탬프(밀리초)입니다.
Name
expires_at
Type
timestamp
Description
태스크 결과가 만료되는 시점의 타임스탬프(밀리초)입니다.
Name
preceding_tasks
Type
integer
Description
선행 태스크의 개수입니다. 상태가 PENDING일 때만 의미가 있습니다.
Name
task_error
Type
object
Description
실패한 태스크에 대한 오류 상세 정보입니다. task_error 오브젝트의 전체 참조는 오류를 참고하세요.
Name
consumed_credits
Type
integer
Description
이 태스크에서 소비된 크레딧 수입니다. FAILED 태스크의 경우 0을 반환합니다(실패 시 크레딧은 환불됩니다).
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이 아니었던 경우에 존재합니다. 픽스처 프리셋이 none이었던 경우에는 생략됩니다.
- Name
  bundle_zip
  Type
  string
  Description
  프로세서가 생성하는 모든 산출물(lamp.stl, 선택적으로 base.stl, 그리고 options.include_result_json이 true인 경우 result.json)을 담은 zip 번들에 대한 다운로드 가능한 URL입니다. output.format이 zip이었던 경우에 존재합니다. bundle_zip이 존재하는 경우 lamp_stl / base_stl은 생략됩니다.

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