Creative Lab — 램프 API

텍스트 prompt 또는 원본 사진을 3D 프린트 가능한 램프 갓으로 두 단계에 걸쳐 변환합니다. 프로토타입은 스타일화된 무광 흰색 콘셉트 이미지를 생성한 다음, 빌드는 해당 콘셉트 이미지를 속이 빈 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

램프 프로토타입 작업 생성

램프 갓을 위한 단일 무광 흰색 콘셉트 이미지를 생성합니다 — 텍스트 prompt(text-to-3D) 또는 참조 사진(image-to-3D)에서 생성할 수 있습니다. 반환된 작업 ID는 빌드 엔드포인트에 input_task_id로 전달하는 값입니다. 응답 형태는 램프 프로토타입 작업 객체를 참조하세요.

파라미터

text 또는 image_url 중 정확히 하나가 필수입니다. 둘 다 전달하거나, 둘 다 전달하지 않으면 400이 반환됩니다.

  • Name
    text
    Type
    string
    필수
    Description

    원하는 램프 갓 주제를 설명하는 텍스트 prompt입니다. image_url이 생략된 경우 필수입니다. 최대 800자입니다.

  • Name
    image_url
    Type
    string
    필수
    Description

    Meshy가 램프 갓의 시각적 참조로 사용하는 원본 사진입니다. text가 생략된 경우 필수입니다. 현재 .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

    image-to-3D 경로에 대한 주제 카테고리 힌트입니다. 사용 가능한 값:

    • character (기본값) — 단일 캐릭터 / 객체 주제(피규어, 동물, 마스코트 등).
    • landscape — 야외 씬 / 파노라마 주제(산, 도시 경관, 숲 등).

    text-to-3D 경로에서는 무시됩니다.

  • Name
    name
    Type
    string
    Description

    표시 목적의 선택적 작업 이름입니다. 최대 100자입니다.

반환값

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

실패 모드

  • Name
    400 - Bad Request
    Description

    요청을 수락할 수 없습니다. 일반적인 원인:

    • 누락된 파라미터: text 또는 image_url 중 정확히 하나가 필요합니다.
    • 둘 다 제공됨: text와 image_url을 모두 전달하면 거부됩니다 — 둘은 상호 배타적입니다.
    • 잘못된 이미지 형식: 제공된 image_url이 지원되는 형식(.jpg, .jpeg, .png, .webp)이 아닙니다.
    • 이미지 크기가 범위를 벗어남: 이미지가 너무 작거나, 최대 파일 크기를 초과하거나, 최대 픽셀 수를 초과합니다.
    • 접근할 수 없는 URL: image_url을 다운로드할 수 없습니다(404 또는 timeout).
    • 잘못된 Data URI: base64 문자열 형식이 올바르지 않습니다.
    • 플래그된 콘텐츠: 입력 이미지가 NSFW 또는 지적 재산권 moderation에 의해 플래그되었습니다.
    • 텍스트가 너무 김: text가 800자를 초과합니다.
    • 잘못된 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 (image-to-3D): generate a matte-white lampshade concept image
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"
  }'

# Stage 1 (text-to-3D): generate from a text prompt
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 '{
    "text": "a stylized owl perched on a tree branch under moonlight"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
Prototype example
Start with a source photo, then generate the prototype image used by the lamp build stage.
Creative Lab 램프 입력으로 사용된 원본 고양이 사진
Prototype input
원본 사진에서 생성된 Creative Lab 램프 프로토타입 출력
Prototype output
POST/openapi/creative-lab/lamp/v1/build

램프 빌드 작업 생성

성공한 프로토타입 작업에서 최종 3D 프린트 가능한 램프갓을 생성합니다. 빌드는 프로토타입의 콘셉트 이미지에 이미지-투-3D 파이프라인을 실행한 다음, 램프 프로세서를 통해 메시를 후처리하여 속을 비우고, 상단을 평평하게 만들며, 선택적으로 베이스를 자르고, (픽스처 프리셋이 선택된 경우) 광원용 별도 베이스 디스크를 내보냅니다. 응답 형식은 램프 빌드 작업 객체를 참조하세요.

파라미터

  • Name
    input_task_id
    Type
    string
    필수
    Description

    이 동일한 OpenAPI 엔드포인트를 통해 생성된 프로토타입 작업의 작업 ID입니다. 프로토타입은 동일한 API 키로 생성되어야 하며, SUCCEEDED에 도달해야 하고, 정확히 하나의 후보 이미지를 생성해야 합니다.

    웹앱을 통해 생성된 프로토타입 작업은 허용되지 않습니다 — 빌드 엔드포인트는 POST /openapi/creative-lab/lamp/v1/prototype에서 생성된 프로토타입 작업만 허용하며, 그 외 소스는 404로 거부합니다.

  • Name
    name
    Type
    string
    Description

    표시 목적의 선택적 작업 이름입니다. 최대 100자입니다.

options

램프갓 지오메트리를 위한 선택적 튜닝 파라미터입니다. 모든 필드에는 합리적인 기본값이 있습니다 — 재정의하려는 항목만 보내세요.

  • Name
    diameter_mm
    Type
    number
    기본값 80
    Description

    램프갓 바운딩 박스의 목표 최대 치수(밀리미터)입니다. 메시가 맞도록 균일하게 스케일링됩니다. 범위: [50, 400].

  • Name
    thickness_mm
    Type
    number
    기본값 1.5
    Description

    속이 빈 램프갓의 벽 두께(밀리미터)입니다. 범위: (0, 10].

  • Name
    cut_amount_percent
    Type
    number
    기본값 35
    Description

    프린트가 베드 위에 놓일 수 있도록 상단에서 평평하게 만들 램프갓 높이의 비율입니다. 범위: [1, 100].

  • Name
    light_source_preset
    Type
    string
    기본값 bambu_mh001_60mm
    Description

    램프갓과 함께 베이스 디스크를 내보낼지 여부(및 어떤 디스크인지)를 결정하는 광원 픽스처 프리셋입니다. 사용 가능한 값:

    • bambu_mh001_60mm (기본값) — 호환되는 광원 픽스처에 맞는 60 mm 베이스 디스크를 내보냅니다. 결과에는 model_urls.base_stl이 포함됩니다.
    • none — 픽스처 없음, 베이스 디스크 없음. 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축 오프셋(밀리미터)입니다. 범위: [-80, 80].

  • Name
    rotate_x_deg
    Type
    number
    기본값 0
    Description

    처리 전에 가져온 메시에 적용되는 X축 주위 회전(도)입니다. 범위: [-360, 360].

  • Name
    rotate_y_deg
    Type
    number
    기본값 0
    Description

    처리 전에 가져온 메시에 적용되는 Y축 주위 회전(도)입니다. 범위: [-360, 360].

  • Name
    rotate_z_deg
    Type
    number
    기본값 0
    Description

    처리 전에 가져온 메시에 적용되는 Z축 주위 회전(도)입니다. 범위: [-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에 도달할 때까지 작업 가져오기 엔드포인트를 폴링하거나 스트림을 구독한 다음, model_urls에서 아티팩트를 다운로드하세요.

실패 모드

  • Name
    400 - Bad Request
    Description

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

    • 누락된 파라미터: input_task_id는 필수입니다.
    • 잘못된 UUID: input_task_id가 유효한 UUID가 아닙니다.
    • 상위 작업이 성공하지 않음: 참조된 프로토타입 작업이 아직 SUCCEEDED에 도달하지 않았습니다.
    • 후보 없음: 프로토타입 작업은 성공했지만 후보 이미지를 생성하지 않았습니다.
    • 옵션이 범위를 벗어남: options 필드 중 하나가 허용 범위 또는 enum 세트를 벗어났습니다.
  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

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

  • Name
    404 - Not Found
    Description

    참조된 프로토타입 작업이 존재하지 않거나, 다른 사용자에게 속해 있거나, 웹앱을 통해 생성되었습니다(API mode 프로토타입 작업만 빌드로 체이닝됩니다).

  • 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 selected prototype image into a printable lampshade model.
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": 6,
  "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": 30,
  "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 경로는 작업의 단계와 일치해야 합니다 — DELETE를 /prototype/:buildId에 요청하면 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로 반환합니다. 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": 30,
  "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": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

램프 프로토타입 작업 객체

램프 프로토타입 작업 객체는 Meshy가 추적하는 작업 단위로, 텍스트 prompt 또는 원본 사진에서 스타일화된 매트 화이트 콘셉트 이미지를 생성합니다. 이 단계의 출력은 input_task_id를 통해 빌드 단계로 연결됩니다.

속성

  • Name
    id
    Type
    string
    Description

    작업의 고유 식별자입니다. 구현 세부 사항으로 작업 id에 k-sortable 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

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

    타임스탬프는 1970년 1월 1일 UTC 이후 경과한 밀리초 수를 나타내며, RFC 3339 표준을 따릅니다. 예를 들어, 2023년 9월 1일 금요일 오후 12:00:00 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
    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": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

램프 빌드 작업 객체

램프 빌드 작업 객체는 Meshy가 성공한 프로토타입 작업으로부터 최종 3D 프린팅 가능한 램프셰이드를 생성하기 위해 추적하는 작업 단위입니다. 빌드는 프로토타입의 콘셉트 이미지에 대해 이미지-투-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입니다. 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": 30,
  "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=***"
  }
}