创意工坊 — 灯罩 API
把文字描述或一张照片变成可 3D 打印的灯罩，分两段：prototype 生成一张
哑光白色的概念图，build 再把概念图转成中空的 STL 灯罩（可选附带一块
适配光源的底座圆盘）。两段通过 input_task_id 串联。
POST /openapi/creative-lab/lamp/v1/prototypePOST /openapi/creative-lab/lamp/v1/build
创建灯罩 Prototype 任务
生成一张灯罩的哑光白色概念图 —— 既可以从文本提示词（text-to-3D），也可以
从参考图片（image-to-3D）。返回的任务 ID 即作为后续 build 端点的
input_task_id。响应结构详见后文
灯罩 Prototype 任务对象 章节。
参数
text 与 image_url 必传其一。两个都传或都不传都会返回 400。
- Name
- text
- Type
- string
- 必选
- Description
描述灯罩主题的文字提示词。当
image_url未提供时必传。最长 800 字符。
- Name
- image_url
- Type
- string
- 必选
- Description
Meshy 用作灯罩视觉参考的源照片。当
text未提供时必传。目前支持.jpg、.jpeg、.png、.webp格式。可通过两种方式提供图片：
- 公网可访问 URL：可从公网访问的 URL。
- Data URI：图片的 base64 编码 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 个字符。
返回值
响应的 result 字段返回新创建的灯罩 prototype 任务的 id。轮询 查询任务
端点或订阅 流式订阅任务 直到任务状态变为 SUCCEEDED，再把该 ID 作为
build 端点的 input_task_id 传入。
失败场景
- Name
400 - Bad Request- Description
请求不合法，常见原因：
- 缺少参数：
text与image_url必传其一。 - 二者同时传入：
text与image_url互斥，不能同时存在。 - 图片格式不支持：
image_url不是受支持的格式（.jpg、.jpeg、.png、.webp）。 - 图片尺寸不合法：图片过小、文件超过最大体积上限，或像素数超过上限。
- URL 无法访问：
image_url下载失败（404 或超时）。 - Data URI 不合法：base64 字符串格式错误。
- 内容被审核拦截：图片被 NSFW 或知识产权审核标记。
- 文本过长：
text超过 800 字符。 image_subject取值非法：不在character/landscape中。
- 缺少参数：
- Name
401 - Unauthorized- Description
身份验证失败，请检查 API key。
- Name
402 - Payment Required- Description
积分不足，无法创建任务。
- Name
429 - Too Many Requests- Description
请求超出速率限制。
请求
# Stage 1（图生 3D）：生成哑光白色灯罩概念图
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（文生 3D）：从文字提示词生成
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"
}'
响应
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
创建灯罩 Build 任务
根据已成功的 prototype 任务，生成最终可 3D 打印的灯罩。Build 在 prototype 概念图上
跑图生 3D 管线，再把网格交给 lamp processor 做中空化、顶面平整、可选底部切口；当
light_source_preset 选用某个夹具时，还会额外输出一块适配光源的底座圆盘。响应
结构详见后文 灯罩 Build 任务对象 章节。
参数
- Name
- input_task_id
- Type
- string
- 必选
- Description
通过同一个 OpenAPI 端点创建的 prototype 任务的 ID。该 prototype 必须由同一 API key 创建、状态已变为
SUCCEEDED，且产出恰好一张候选图。通过 webapp 创建的 prototype 任务不接受 —— build 端点只接受由
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（默认）— 输出一块直径 60mm、适配兼容光源夹具的底座圆盘。结果包含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时，在打包内包含 lamp processor 的result.json（含测量到的网格指标与最终生效的 option 集合）。output.format为stl时被忽略。
output
可选的输出格式选择。默认 stl。
- Name
- format
- Type
- string
- 默认值 stl
- Description
Build 返回的产物形态。可选值：
stl（默认）— 灯罩本体放在model_urls.lamp_stl；当light_source_preset≠none时同时返回model_urls.base_stl。zip— 把 processor 输出的全部文件（lamp.stl、可选base.stl、可选result.json）打成单个 zip，返回在model_urls.bundle_zip。
返回值
响应的 result 字段返回新创建的灯罩 build 任务的 id。轮询 查询任务
端点或订阅 流式订阅任务 直到任务状态变为 SUCCEEDED，即可从
model_urls 中下载产物。
失败场景
- Name
400 - Bad Request- Description
请求不合法，常见原因：
- 缺少参数：
input_task_id必传。 - UUID 不合法：
input_task_id不是合法 UUID。 - 父任务未成功：引用的 prototype 任务尚未达到
SUCCEEDED。 - 没有候选图：prototype 任务虽然成功，但未产出任何候选图。
- options 字段越界：某个
options字段超出允许的范围或枚举集。
- 缺少参数：
- Name
401 - Unauthorized- Description
身份验证失败，请检查 API key。
- Name
402 - Payment Required- Description
积分不足，无法创建任务。
- Name
404 - Not Found- Description
引用的 prototype 任务不存在、属于其他用户，或是 webapp 创建的（只接受 API 模式的 prototype 任务）。
- Name
429 - Too Many Requests- Description
请求超出速率限制。
请求
# Stage 2：基于已成功的 prototype 任务串联 build
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"
}
}'
响应
{
"result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}
查询灯罩任务
根据合法的任务 id 查询一个 prototype 或 build 任务。URL 路径必须与任务阶段一致 ——
用 /prototype/:id 拉一个 build 任务返回 404，反之亦然。
响应结构详见 灯罩 Prototype 任务对象 与 灯罩 Build 任务对象 章节。
参数
- Name
- id
- Type
- path
- Description
要查询的灯罩任务的唯一标识符。
返回值
响应包含灯罩任务对象，形态取决于请求的阶段。
请求
# 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 响应
{
"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 响应
{
"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=***"
}
}
删除灯罩任务
取消一个灯罩任务。若任务还在 PENDING，创建时消耗的积分会退还；已经
IN_PROGRESS 的任务会被取消但不退还（worker 可能已经在消耗资源）；已经处于
终态（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 路径不一致。
请求
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}"
响应
// 成功时返回 204 No Content（空响应体）。
流式订阅灯罩任务
通过 Server-Sent Events (SSE) 实时订阅灯罩任务进度。URL 路径必须与任务阶段一致
—— 对 /prototype/:buildId/stream 打开流会发出一条 event: error（status_code: 404）
然后关闭流。
参数
- Name
- id
- Type
- path
- Description
要订阅的灯罩任务的唯一标识符。
返回值
返回 灯罩 Prototype 或
灯罩 Build 任务对象的 SSE 流。
对于 PENDING / IN_PROGRESS 状态的任务，流中只包含必要的 progress 与 status 字段。
请求
curl -N https://api.meshy.ai/openapi/creative-lab/lamp/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
响应流
// 错误事件示例（stage 不匹配或任务不存在）
event: error
data: {
"status_code": 404,
"message": "Task not found"
}
// 消息事件示例：表示任务进度。
// PENDING / IN_PROGRESS 状态下，事件流不包含全部字段。
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=***"
}
}
列出灯罩任务
按阶段分页列出当前 API key 名下的灯罩任务。URL 路径决定阶段 —— /prototype 返回
prototype 任务；/build 返回 build 任务。跨阶段的任务不会出现在另一边的响应中。
路径参数
- Name
- stage
- Type
- path
- 必选
- Description
prototype或build。集合仅返回与 URL 阶段匹配的任务 —— 拉/prototype不会返回 build 任务，反之亦然。
查询参数
- 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 时返回
灯罩 Prototype 任务对象；
列出 /build 时返回 灯罩 Build 任务对象。
请求
# 列出 prototype 任务
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/prototype?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
# 列出 build 任务
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/build?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
响应（列出 Prototype 任务）
[
{
"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=***"
]
}
]
灯罩 Prototype 任务对象
灯罩 Prototype 任务是 Meshy 用来跟踪「从文字提示词或源照片生成哑光白色概念图」
这一阶段的工作单元。它的产物经由 input_task_id 串联给
Build 阶段。
字段
- Name
- id
- Type
- string
- Description
任务的唯一标识符。当前实现使用 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
任务进度。未开始时为
0；成功时为100。
- Name
- created_at
- Type
- timestamp
- Description
任务创建时间戳，单位毫秒。
时间戳表示自 1970-01-01 UTC 起经过的毫秒数，遵循 RFC 3339 标准。 例如，2023-09-01 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
失败任务的错误详情。完整对象结构详见 Errors。
- Name
- consumed_credits
- Type
- integer
- Description
该任务消耗的积分数。
PENDING、IN_PROGRESS、SUCCEEDED状态下呈现；FAILED状态返回0（失败时积分退还）。
- Name
- image_urls
- Type
- array of strings
- Description
该 prototype 任务生成的候选概念图的下载 URL 数组。目前 API 始终返回恰好一张候选；字段以数组形态返回，便于未来在不破坏兼容性的前提下扩展多候选。
灯罩 Prototype 任务对象示例
{
"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 任务对象
灯罩 Build 任务是 Meshy 用来跟踪「从已成功的 prototype 任务生成最终可 3D 打印灯罩」 这一阶段的工作单元。Build 在 prototype 概念图上跑图生 3D 草模 + 贴图管线，再把网格 交给 lamp processor 完成中空化、顶部平整化、可选夹具底切等后处理。
字段
- 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
失败任务的错误详情。完整对象结构详见 Errors。
- Name
- consumed_credits
- Type
- integer
- Description
该任务消耗的积分数。
FAILED状态返回0（失败时积分退还）。
- Name
- model_urls
- Type
- object
- Description
生成的产物下载 URL，以产物名为 key。具体出现哪些 key 取决于
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
processor 全部产物（
lamp.stl、可选base.stl，以及当options.include_result_json为true时的result.json）打包成的单个 zip 的下载 URL。当output.format为zip时呈现。此时lamp_stl/base_stl缺省。
灯罩 Build 任务对象示例
{
"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=***"
}
}