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（文本到3D）或参考照片（图像到3D）生成。返回的任务ID是您传递给构建endpoint的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编码数据URI。Data URI示例：data:image/jpeg;base64,<your base64-encoded image data>。

Name
image_subject
Type
string
默认值 character
Description
图像到3D路径的主题类别提示。可用值：
- character（默认）— 单个角色/对象主题（小雕像、动物、吉祥物等）。
- landscape — 户外场景/全景主题（山脉、城市景观、森林等）。
在文本到3D路径上被忽略。
Name
name
Type
string
Description
用于显示的可选任务名称。最多100个字符。
Name
remove_background
Type
boolean
默认值 false
Description
当设置为true时，原型图像将作为透明的RGBA PNG返回，背景被移除，因此您可以将主题合成到任何背景上。

响应的result属性包含新创建的灯具原型任务的任务id。轮询获取任务endpoint或订阅流直到任务达到SUCCEEDED，然后将该ID传递给构建endpoint作为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
authentication失败。请检查您的API key。
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"
}

原型示例

从源照片开始，然后生成灯具构建阶段使用的原型图像。

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

创建灯具构建任务

从成功的原型任务生成最终的3D可打印灯罩。构建在原型的概念图像上运行图像到3D的管道，然后通过灯具处理器对mesh进行后处理，使其中空、顶部平整、可选地切割底座，并且（当选择灯具预设时）为光源发出一个单独的底座盘。请参阅灯具构建任务对象以了解响应结构。

参数

Name
input_task_id
Type
string
必选
Description
通过相同的OpenAPI endpoint创建的原型任务的任务ID。原型必须使用相同的API key创建，必须达到SUCCEEDED，并且必须生成一个候选图像。
通过webapp创建的原型任务不被接受 — 构建endpoint仅接受通过POST /openapi/creative-lab/lamp/v1/prototype生成的原型任务，并拒绝任何其他来源，返回404。
Name
name
Type
string
Description
用于显示的可选任务名称。最多100个字符。

`options`

灯罩几何的可选调优参数。每个字段都有一个合理的默认值 — 仅发送您想要覆盖的字段。

Name
diameter_mm
Type
number
默认值 80
Description
灯罩包围盒的目标最大尺寸，以毫米为单位。mesh被均匀缩放以适应。范围：[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毫米的底座盘，适用于兼容的光源灯具。结果包括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
在处理之前应用于导入mesh的X轴旋转，以度为单位。范围：[-360, 360]。
Name
rotate_y_deg
Type
number
默认值 0
Description
在处理之前应用于导入mesh的Y轴旋转，以度为单位。范围：[-360, 360]。
Name
rotate_z_deg
Type
number
默认值 0
Description
在处理之前应用于导入mesh的Z轴旋转，以度为单位。范围：[-360, 360]。
Name
include_result_json
Type
boolean
默认值 false
Description
当true且output.format为zip时，将灯具处理器的result.json（包含测量的mesh指标+已解析的选项集）包含在包中。当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。轮询获取任务endpoint或订阅流直到任务达到SUCCEEDED，然后从model_urls下载工件。

失败模式

Name
400 - Bad Request
Description
请求不可接受。常见原因：
- 缺少参数：input_task_id是必需的。
- 无效的UUID：input_task_id不是有效的UUID。
- 父任务未成功：引用的原型任务尚未达到SUCCEEDED。
- 无候选：原型任务成功但未生成候选图像。
- 选项超出范围：options字段之一超出了其允许的范围或枚举集。
Name
401 - Unauthorized
Description
authentication失败。请检查您的API key。
Name
402 - Payment Required
Description
积分不足以执行此任务。
Name
404 - Not Found
Description
引用的原型任务不存在，属于不同用户，或通过webapp创建（仅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"
}

构建示例

构建任务将选定的原型图像转换为可打印的灯罩模型。

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

获取灯具任务

根据有效的任务 id 获取原型或构建任务。URL 路径必须与任务的阶段匹配——通过 /prototype/:id 获取构建任务会返回 404，反之亦然。

请参阅灯具原型任务对象和灯具构建任务对象以了解响应结构。

参数

Name
id
Type
path
Description
要获取的灯具任务的唯一标识符。

响应包含灯具任务对象。形状取决于请求的阶段。

请求

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

原型响应

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

构建响应

{
  "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路径必须与任务的阶段匹配——在/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

流式传输灯具任务

通过服务器发送事件 (SSE) 流式传输灯具任务的实时更新。URL 路径必须与任务的阶段匹配——在 /prototype/:buildId/stream 打开流会发出一个 event: error payload，包含 status_code: 404，并关闭流。

参数

Name
id
Type
path
Description
要流式传输的灯具任务的唯一标识符。

返回值

返回灯具原型或灯具构建任务对象的流作为服务器发送事件。对于 PENDING 或 IN_PROGRESS 任务，响应流将仅包含必要的 progress 和 status 字段。

请求

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

响应流

// 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 时为灯具构建任务对象。

请求

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

响应（列出原型任务）

[
  {
    "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跟踪的一个工作单元，用于从文本提示或源照片生成风格化的哑光白色概念图像。此阶段的输出通过input_task_id链接到构建阶段。

属性

Name
id
Type
string
Description
任务的唯一标识符。虽然我们使用k-可排序的UUID作为任务ID的实现细节，但您不应对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
任务的进度。如果任务尚未开始，此属性将为0。一旦任务成功完成，这将变为100。
Name
created_at
Type
timestamp
Description
任务创建时的时间戳，以毫秒为单位。
时间戳表示自1970年1月1日UTC以来经过的毫秒数，遵循 RFC 3339标准。例如，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
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草稿 + 贴图管道，然后通过灯具处理器对mesh进行后处理，以便中空、平整和（可选）切割灯具底座。

属性

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
任务的进度。如果任务尚未开始，此属性为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对象参考见Errors。
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
  可下载的包含处理器发出的每个工件的zip包的URL（lamp.stl，可选的base.stl，以及—当options.include_result_json为true时—result.json）。当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=***"
  }
}