Creative Lab — 灯具 API
分两个阶段将一张源照片变成可 3D 打印的灯罩:prototype(原型)阶段会生成一张风格化的哑光白概念图,并将其转换为空心 3D 模型(GLB);随后 build(构建)阶段会在该模型上运行灯具处理器,生成可打印的 STL 部件——一个底部开口、带有光源灯具底座的灯罩,以及灯具固定件本身。这两个阶段通过 input_task_id 关联。
POST /openapi/creative-lab/lamp/v1/prototypePOST /openapi/creative-lab/lamp/v1/build
创建灯具原型任务
根据参考照片生成一张单色哑光白概念图,并将其转换为一个中空的 3D 灯罩模型。响应中同时包含概念图(image_urls)和 3D 模型(model_urls.glb 及其 thumbnail_url)。返回的任务 ID 即是您在调用构建 endpoint 时需要传入的 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。请轮询获取任务 endpoint 或订阅流式接口,直到任务状态变为 SUCCEEDED,然后将该 ID 作为 input_task_id 传递给构建 endpoint。
失败模式
- 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
authentication 失败。请检查您的 API key。
- Name
402 - Payment Required- Description
credits 不足,无法执行此任务。
- Name
429 - Too Many Requests- Description
您已超出速率限制。
Request
# 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"
}


创建灯具构建任务
从一个成功的原型任务生成最终的可 3D 打印部件。
构建过程会在原型的 3D 模型上运行灯具处理器:将模型缩放到
diameter_mm,按 cut_amount_percent 削平底部,
以 thickness_mm 进行空心化处理,打开底部,并且——当选择了
fixture 预设时——添加带有 fixture 孔的底板以及一个独立的
光源安装座。响应结构请参阅
灯具构建任务对象。
参数
- Name
- input_task_id
- Type
- string
- 必选
- Description
通过此相同 OpenAPI endpoint 创建的原型任务的任务 ID。该原型必须使用相同的 API key 创建,必须已达到
SUCCEEDED状态,且必须已生成 3D 模型。通过网页应用创建的原型任务不被接受——构建 endpoint 仅接受由
POST /openapi/creative-lab/lamp/v1/prototype生成的原型任务,并会以404拒绝任何其他来源。
- Name
- name
- Type
- string
- Description
用于显示的可选任务名称。最多 100 个字符。
options
灯罩 geometry 的可选调优 参数。每个字段都有合理的默认值——只需发送你想覆盖的字段。
- Name
- diameter_mm
- Type
- number
- 默认值 150
- Description
灯罩包围盒的目标最大尺寸,单位为毫米。mesh 会被统一缩放以适配该尺寸。范围:
[50, 400]。
- Name
- thickness_mm
- Type
- number
- 默认值 1
- Description
空心灯罩的壁厚,单位为毫米。范围:
(0, 10]。
- Name
- cut_amount_percent
- Type
- number
- 默认值 1
- Description
底部被削平的模型高度百分比,以便灯罩能平放在打印床上,并为 fixture 留出开口。范围:
[1, 100]。
- Name
- light_source_preset
- Type
- string
- 默认值 bambu_mh001_60mm
- Description
决定底部构建方式的光源 fixture 预设。可用值:
bambu_mh001_60mm(默认)——开底灯罩加上带有 60 mm fixture 孔的底板,两者都在model_urls.lamp_stl中,fixture 安装座则作为model_urls.base_stl。none—— 单个密封灯罩,位于model_urls.lamp_stl中;此时省略model_urls.base_stl。
- Name
- fixture_offset_x_mm
- Type
- number
- 默认值 0
- Description
底板上 fixture 孔相对于灯罩中心的 X 轴偏移量,单位为毫米。仅当
light_source_preset≠none时有意义。范围:[-80, 80]。
- Name
- fixture_offset_z_mm
- Type
- number
- 默认值 0
- Description
底板上 fixture 孔相对于灯罩中心的 Z 轴(深度)偏移量,单位为毫米。仅当
light_source_preset≠none时有意义。范围:[-80, 80]。
- Name
- rotate_x_deg
- Type
- number
- 默认值 0
- Description
处理前对模型施加的绕 X 轴的旋转,单位为度。三个旋转以 XYZ 欧拉角的形式围绕模型中心依次施加。范围:
[-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(管线名称、警告信息以及产物路径)。当output.format为stl时该字段被忽略。
output
可选的输出格式选择器。默认为 stl。
- Name
- format
- Type
- string
- 默认值 stl
- Description
构建返回的产物包。可用值:
stl(默认)——返回model_urls.lamp_stl(灯罩,以及在设置了 fixture 预设时随附的底板),并在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状态。 - 无模型:原型任务已成功,但未生成 3D 模型。
- 选项超出范围:
options中的某个字段超出了允许的范围或枚举取值集合。
- 缺少参数:
- Name
401 - Unauthorized- Description
authentication 失败。请检查你的 API key。
- Name
402 - Payment Required- Description
credits 不足,无法执行此任务。
- Name
404 - Not Found- Description
所引用的原型任务不存在、属于其他用户,或是通过网页应用创建的(只有 API 模式下的原型任务才能链接到构建任务)。
- Name
429 - Too Many Requests- Description
你已超出速率限制。
Request
# 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"
}

获取灯具任务
根据有效的任务 id 获取原型或构建任务。URL 路径必须与任务所处的阶段匹配——通过
/prototype/:id 获取的构建任务会返回 404,反之亦然。
参数
- Name
- id
- Type
- path
- Description
要获取的灯具任务的唯一标识符。
返回值
响应内容为灯具任务对象。其具体结构取决于所请求的阶段。
Request
# 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=***"
}
}
删除灯具任务
取消一个灯具任务。如果任务仍处于 PENDING 状态,创建时消耗的
credits 将被退还。已经处于 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
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).
流式获取灯具任务
通过服务器发送事件(SSE)流式获取灯具任务的实时更新。
URL 路径必须与任务所处的阶段相匹配——在
/prototype/:buildId/stream 处打开流会发出一条 status_code: 404 的
单一 event: error payload,随后关闭该流。
参数
- Name
- id
- Type
- path
- Description
要进行流式传输的灯具任务的唯一标识符。
返回值
以 Server-Sent Events 的形式返回一个包含 Lamp Prototype
或 Lamp Build 任务对象的流。
对于 PENDING 或 IN_PROGRESS 状态的任务,响应流中只会包含
必要的 progress 和 status 字段。
Request
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=***"
}
}
获取灯具任务列表
获取单个阶段的灯具任务分页列表。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
# 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=***"
]
}
]
灯具原型任务对象
灯具原型任务对象是 Meshy 用于跟踪的一个工作单元,用于根据源照片生成风格化的哑光白色概念图,并将其转换为空心的3D 模型。此阶段的输出会通过 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 日星期五 GMT 时间中午 12:00:00 表示为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
此任务消耗的 credits 数量。当任务状态为
PENDING、IN_PROGRESS或SUCCEEDED时会显示该值。对于FAILED的任务返回0(失败时 credits 会被退还)。
- 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=***"
]
}
灯具构建任务对象
灯具构建任务对象是 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
任务创建时间的 timestamp,以毫秒为单位。
- Name
- started_at
- Type
- timestamp
- Description
任务开始时间的 timestamp,以毫秒为单位。
- Name
- finished_at
- Type
- timestamp
- Description
任务完成时间的 timestamp,以毫秒为单位。
- Name
- expires_at
- Type
- timestamp
- Description
任务结果过期时间的 timestamp,以毫秒为单位。
- Name
- preceding_tasks
- Type
- integer
- Description
排在前面的任务数量。仅当状态为
PENDING时才有意义。
- Name
- task_error
- Type
- object
- Description
失败任务的错误详情。有关完整的
task_error对象参考,请参阅 Errors。
- Name
- consumed_credits
- Type
- integer
- Description
此任务消耗的 credits 数量。对于
FAILED任务,返回0(失败时会退还 credits)。
- 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)的压缩包的可下载 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=***"
}
}