Text to 3D API
在你自己的应用程序中根据文本提示生成 3D 模型。
Text to 3D 分两步进行。首先,创建一个 preview 任务(mode: "preview")以生成不带 texture 的 3D mesh,这样你就可以检查其形状。然后,将成功的 preview 任务的任务 ID 发送给 refine 任务(mode: "refine"),为 mesh 添加 texture。这两个步骤使用相同的 endpoint。
创建 Text to 3D preview 任务
创建一个 Text to 3D preview 任务,根据文本 prompt 生成一个未上贴图的 3D mesh(仅几何体)。这是两步工作流程的第一步。preview 成功后,将其任务 ID 发送到 refine 任务中,为 mesh 添加贴图。参见创建 Text to 3D refine 任务。完整的响应 schema 参见 Text to 3D 任务对象。
该任务在后台运行。关于任务通常耗时多久,参见处理时间。
Request
# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "preview",
"prompt": "a monster mask"
}'
# Preview with Ultra 4K geometry, remesh, and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "preview",
"prompt": "a futuristic robot warrior",
"ai_model": "meshy-7.1",
"geometry_resolution": "4k",
"should_remesh": true,
"target_polycount": 100000,
"pose_mode": "a-pose",
"target_formats": ["glb"]
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
参数
- Name
- mode
- Type
- string
- 必选
- Description
两步工作流程的阶段。发送
preview以创建一个 preview 任务。
- Name
- prompt
- Type
- string
- 必选
- Description
描述要生成的对象的文本,最多 800 个字符。超出长度将返回
400。
- Name
- model_type
- Type
- string
- 默认值 standard
- Description
要生成的 3D mesh 类型。
可用取值:
standard:高细节 3D meshsmart-topology:Smart Topology mesh。通过ai_model(meshy-t2或meshy-t2.5)选择模型。
使用
smart-topology时,Meshy 会忽略should_remesh和decimation_mode,并且只接受topology: triangle。
- Name
- ai_model
- Type
- string
- 默认值 latest
- Description
用于生成 3D 模型的 AI 模型。可用取值取决于
model_type。标准模型(
model_type: standard):meshy-6-litemeshy-6meshy-7.1latest:Meshy 7.1meshy-7(deprecated):请改为发送meshy-7.1。该模型将于 2026 年 12 月 31 日下线。
Smart Topology 模型(
model_type: smart-topology):meshy-t2:更干净的 topology、原生分离的部件、三角面输出,面数通过target_polycount设置meshy-t2.5(默认):更适合游戏 asset 的更锐利细节、三角面输出,面数通过target_polycount设置
关于哪种模型适合你的项目(例如游戏角色或 3D 打印),参见模型。
- Name
- geometry_resolution
- Type
- string
- 默认值 standard
- Description
几何体生成的处理档位。仅适用于 preview 任务。在 refine 任务中使用此参数将返回
400。可用取值:
standard2k:以 2048³ 运行 Ultra 处理4k:以 4096³ 运行 Ultra 处理,获得更精细的表面细节
2k需要meshy-7.1、latest或已 deprecated 的meshy-7。4k需要meshy-7.1或latest。其他模型将返回400。
- Name
- ultra_mode
- Type
- boolean
- ⚠ 已弃用
- 默认值 false
- Description
请改为发送
geometry_resolution。ultra_mode: true等同于geometry_resolution: "2k"。
- Name
- should_remesh
- Type
- boolean
- 默认值 true (meshy-6-lite), false (other models)
- Description
是否在生成后对模型进行 remesh。若要获得最高质量的 3D 模型,请发送
false。
should_remesh = true- Name
- topology
- Type
- string
- 默认值 triangle
- Description
重新生成 mesh 后的模型面类型。
可用取值:
quad:以四边面为主的 meshtriangle:经过精简的三角面 mesh
Smart Topology 的输出仅支持三角面。若
ai_model为meshy-t2或meshy-t2.5时发送quad,将返回400。
- Name
- decimation_mode
- Type
- integer
- Description
按级别自适应的面数。设置该参数时,Meshy 会忽略
target_polycount。可用取值:
1:ultra2:high3:medium4:low
- Name
- target_polycount
- Type
- integer
- Description
目标面数。实际结果可能因 geometry 不同而与目标值有差异。它适用于两种不同情况:
- Remesh:在
standard模型上设置should_remesh: true时。Meshy 会将 mesh 重新生成(精简)到大致这个数量。如果你设置了decimation_mode,Meshy 会使用它并忽略target_polycount。 - Smart Topology:在
model_type: smart-topology且ai_model为meshy-t2或meshy-t2.5时。Meshy 会直接以此面数生成模型,不会运行 remesh,也不需要should_remesh。
下表展示了每种情况的取值范围及默认值:
情况 范围 默认值 Remesh 100到30000030000meshy-t2100到150004000meshy-t2.5100到3000015000超出范围的值将返回
400。对于 low-poly 的游戏 asset,建议使用 Smart Topology 模型,而不是对 standard 模型进行 remesh。参见模型。
- Remesh:在
- Name
- symmetry_mode
- Type
- string
- ⚠ 已弃用
- 默认值 auto
- Description
请勿使用此参数。它不会影响输出结果。
可用取值:
off:禁用 symmetryauto:根据输入 geometry 应用 symmetryon:在生成过程中强制使用 symmetry
- Name
- pose_mode
- Type
- string
- Description
角色模型的姿势,
a-pose或t-pose。若要不指定姿势,请不要设置pose_mode和is_a_t_pose。
- Name
- is_a_t_pose
- Type
- boolean
- ⚠ 已弃用
- 默认值 false
- Description
请改为发送
pose_mode。是否以 A pose 或 T pose 生成模型。
- Name
- art_style
- Type
- string
- ⚠ 已弃用
- 默认值 realistic
- Description
请勿使用此参数。Meshy 会忽略它。
- Name
- moderation
- Type
- boolean
- 默认值 false
- Description
是否在生成前对
prompt进行有害内容筛查。如果 Meshy 检测到有害内容,该请求将返回400,且 Meshy 不会创建任务。
- Name
- target_formats
- Type
- string[]
- Description
要生成的文件格式。Meshy 只生成并返回这些格式,这可以缩短任务耗时。如果不设置该参数,Meshy 会生成除
3mf之外的所有格式,3mf只有在你请求时才会生成。可用取值:
glbobjfbxstlusdz3mf
- Name
- alpha_thumbnail
- Type
- boolean
- 默认值 false
- Description
是否同时渲染一张带透明背景(RGBA)的预览图,获取任务时会在
alpha_thumbnail_url中返回。thumbnail_url不会改变。
- Name
- auto_size
- Type
- boolean
- 默认值 false
- Description
是否使用 AI 视觉估算对象的真实世界高度,并据此调整模型尺寸。除非你设置了
origin_at,否则 Meshy 会将 origin 放在底部。
auto_size = true- Name
- origin_at
- Type
- string
- 默认值 bottom
- Description
将模型的 origin 放在哪里,
bottom或center。
返回值
响应中的 result 字段包含新建的 Text to 3D 任务的 ID。
失败情形
- Name
400 - Bad Request- Description
请求无法运行。错误消息会说明发现了什么问题。例如:
- 缺少参数:缺少必填参数,例如
prompt或mode。 - Prompt 过长:
prompt超过了字符数限制。 - Ultra 不支持该模型:
geometry_resolution为2k或4k,但所用的ai_model不支持运行它。
修正请求后重新发送。参见 Errors。
- 缺少参数:缺少必填参数,例如
- Name
401 - Unauthorized- Description
API key 缺失或无效。请检查
Authorization请求头。
- Name
402 - Payment Required- Description
例如:
- 积分不足:账户没有足够的积分来完成此任务,或账户已达到积分限制。请检查你的积分 balance,然后重试。
- 免费套餐:创建任务需要付费套餐。请在订阅设置中升级你的套餐,然后重试。
- Name
403 - Forbidden- Description
内容审核拦截了该 prompt 或输入图像。请更改输入内容后重试。
- Name
429 - Too Many Requests- Description
你已超出速率限制。请稍候后重试。参见速率限制。
创建 Text to 3D refine 任务
创建一个 Text to 3D refine 任务,为已完成的 preview 任务的 mesh 添加 texture。将成功的 preview 任务的 ID 作为 preview_task_id 发送。参见创建 Text to 3D preview 任务。这是两步工作流程的第二步。
任务在后台运行。关于任务通常需要多长时间,请参见处理时间。
Request
# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "refine",
"preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"enable_pbr": true
}'
# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "refine",
"preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"target_formats": ["glb"],
"auto_size": true
}'
# Refine with Meshy N1 from the preview's stored reference image
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "refine",
"preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"ai_model": "meshy-n1"
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
参数
- Name
- mode
- Type
- string
- 必选
- Description
两步工作流程中的步骤。发送
refine以创建 refine 任务。
- Name
- preview_task_id
- Type
- string
- 必选
- Description
要添加 texture 的 preview 任务的 ID。该 preview 任务的状态必须为
SUCCEEDED。
- Name
- enable_pbr
- Type
- boolean
- 默认值 false
- Description
是否在生成基础颜色贴图的同时也生成 PBR 贴图(金属度、粗糙度和法线)。
在
ai_model为meshy-6时,Meshy 还会生成一张 emission 贴图,但texture_resolution: 8k时除外。meshy-6-lite、meshy-7和latest不会生成 emission 贴图。未设置ai_model的meshy-t2或meshy-t2.5preview 的 refine 同样不会生成。使用ai_model: meshy-n1时,设为true会返回400。
- Name
- texture_resolution
- Type
- string
- 默认值 2k
- Description
基础颜色 texture 的分辨率。仅适用于 refine 任务。若在 preview 中发送此 parameter 会返回
400。可用值:
2k:2048×20484k:4096×40968k:8192×8192
更高的分辨率可以捕捉更多表面细节。
4k和8k需要ai_model为meshy-6、meshy-7或latest。使用meshy-n1时会返回400。在8k时,Meshy 不会生成 emission 贴图。
- Name
- hd_texture
- Type
- boolean
- ⚠ 已弃用
- 默认值 false
- Description
请改为发送
texture_resolution。hd_texture: true与texture_resolution: "4k"相同。如果两者都发送,Meshy 会使用texture_resolution。
- Name
- texture_prompt
- Type
- string
- Description
用于指导 texture 生成的文本,最多 800 个字符。更长的文本会返回
400。请发送texture_prompt或texture_image_url,不要两者都发送。如果两者都发送,Meshy 会使用texture_prompt。使用ai_model: meshy-n1时发送此参数会返回400。
- Name
- texture_image_url
- Type
- string
- Description
用于指导 texture 生成的 2D 图片,可以是公开 URL 或 base64 编码的 data URI,例如
data:image/jpeg;base64,<your base64-encoded image data>。图片必须是
.jpg、.jpeg、.png或.webp文件,大小不超过 20 MB,每边至少 32 像素,且不超过 178,956,970 像素(宽 × 高)。使用
ai_model: meshy-n1时,Meshy 会将该图片作为正视图来生成 texture。当图片中的形状与模型差异较大时,根据图片生成 texture 的效果可能不理想。
- Name
- ai_model
- Type
- string
- 默认值 inherited from the preview task
- Description
用于为 mesh 添加 texture 的 AI 模型。mesh 来自 preview,因此在 refine 时
ai_model仅选择 texture 模型。可用值:
meshy-7:Meshy 7latest:最新的 texture 模型,目前为 Meshy 7meshy-6:Meshy 6meshy-6-lite:Meshy 6 Litemeshy-n1:仅根据参考图片生成 2K 基础颜色 texture。没有文本 prompt,没有 PBR 贴图,也没有 4K 或 8K。
以上值均为 texture 模型。留空则使用与 preview 相匹配的模型来生成 texture。发送一个值可覆盖该默认模型。
使用
meshy-n1时,Meshy 会根据texture_image_url生成 texture。如果未提供该参数,Meshy 会使用meshy-7.1或latestpreview 存储的参考图片。其他任何 preview 若未发送texture_image_url都会返回400。该 preview 最多可包含 7,999,999 个三角形。remesh 为四边面(quad)的 preview 会返回400。
- Name
- moderation
- Type
- boolean
- 默认值 false
- Description
是否在生成之前对
texture_prompt和texture_image_url进行有害内容审查。如果 Meshy 检测到有害内容,请求将返回400,且 Meshy 不会创建任务。
- Name
- remove_lighting
- Type
- boolean
- 默认值 true
- Description
是否从基础颜色 texture 中移除高光和阴影。更干净的结果在自定义光照下效果更好。
仅当
ai_model为meshy-6时生效。meshy-7和latest接受此参数但会忽略它,未设置ai_model的meshy-t2或meshy-t2.5preview 的 refine 同样如此。在meshy-6-lite中发送此参数会返回400。使用meshy-n1时,设为true会返回400。
- Name
- target_formats
- Type
- string[]
- Description
要生成的文件格式。Meshy 仅生成并返回这些格式,这样可以缩短任务时间。如果留空,Meshy 会生成除
3mf之外的所有格式,3mf仅在你请求时才会生成。可用值:
glbobjfbxstlusdz3mf
- Name
- alpha_thumbnail
- Type
- boolean
- 默认值 false
- Description
是否同时渲染一张带透明背景(RGBA)的预览图,在获取任务时通过
alpha_thumbnail_url返回。thumbnail_url不会改变。
- Name
- auto_size
- Type
- boolean
- 默认值 false
- Description
是否使用 AI 视觉估算物体的真实世界高度,并将模型调整为该尺寸。除非设置了
origin_at,否则 Meshy 会将 origin 置于底部。
auto_size = true- Name
- origin_at
- Type
- string
- 默认值 bottom
- Description
模型 origin 的位置,
bottom或center。
返回内容
响应的 result 字段保存新 Text to 3D 任务的 ID。
失败模式
- Name
400 - Bad Request- Description
请求无法运行。错误消息会说明发现了什么问题。例如:
- Invalid task ID:
preview_task_id无效,或与你的任何 preview 任务都不匹配。 - Task not ready:该 preview 任务尚未成功。
- Model mismatch:该 preview 任务的 AI 模型与请求的 refine 模型不兼容。
- Unsupported model for remove_lighting:
remove_lighting与ai_model: "meshy-6-lite"一起发送。 - No reference image for Meshy N1:发送了
ai_model: meshy-n1但未提供texture_image_url,且该 preview 没有 Meshy N1 可使用的参考图片。请发送texture_image_url。 - Quad preview for Meshy N1:针对 remesh 为四边面(quad)的 preview 发送了
ai_model: meshy-n1。请使用其他ai_model进行 refine。 - Too many triangles for Meshy N1:在
ai_model: meshy-n1下,该 preview 的三角形数量超过了 7,999,999。请使用其他ai_model进行 refine。 - Unsupported option for Meshy N1:
ai_model: meshy-n1与以下某个选项一起发送:texture_promptenable_pbr: truetexture_resolution为4k或8k- 未设置
texture_resolution的hd_texture: true remove_lighting: true
修正请求后重新发送。参见 Errors。
- Invalid task ID:
- Name
401 - Unauthorized- Description
API key 缺失或无效。请检查
Authorization请求头。
- Name
402 - Payment Required- Description
例如:
- Insufficient credits:账户没有足够的积分来完成该任务,或账户已达到积分限额。请检查你的 balance,然后重试。
- Free plan:创建任务需要付费计划。请在subscription 设置中升级你的计划,然后重试。
- Name
403 - Forbidden- Description
内容审查拦截了该 prompt 或某张输入图片。请更改输入内容后重试。
- Name
429 - Too Many Requests- Description
你已超出速率限制。请稍候后重试。参见速率限制。
获取 Text to 3D 任务
根据任务 ID 返回对应的 Text to 3D 任务。该接口同时适用于 preview 和 refine 任务。
Request
curl https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"prompt": "a monster mask",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20
}
参数
- Name
- id
- Type
- path
- Description
创建响应中返回的任务 ID。
返回值
示例
下表展示了每种 mode 下的示例模型。
| Mode | 示例模型 |
|---|---|
| Preview | ![]() |
| Refine | ![]() |
删除一个 Text to 3D 任务
永久删除一个 Text to 3D 任务,包括其模型和数据。删除操作无法撤销。
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
"message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}
路径参数
- Name
- id
- Type
- path
- Description
要删除的任务的 ID。
任务状态
删除一个 PENDING 任务会退还你创建它时所使用的积分。
IN_PROGRESS 任务无法被删除。该请求会返回 409 Conflict,
且任务会继续运行。Meshy 不会为已经开始的任务退还积分,
因此删除它会让你同时损失积分和结果。请等待它
变为 SUCCEEDED、FAILED 或 CANCELED 状态后再删除。
删除处于最终状态(SUCCEEDED、FAILED 或 CANCELED)的任务
不会退还其积分。
返回值
任务删除成功时返回 200 OK;当任务处于
IN_PROGRESS 状态时返回 409 Conflict。
获取 Text to 3D 任务列表
返回您的 Text to 3D 任务列表。
Request
curl https://api.meshy.ai/openapi/v2/text-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"prompt": "a monster mask",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20
}
]
参数
- Name
- page_num
- Type
- integer
- 默认值 1
- Description
要返回的页码,最大为
255。更大的值将返回400。
- Name
- page_size
- Type
- integer
- 默认值 10
- Description
每页的任务数量,最大为
100。
- Name
- sort_by
- Type
- string
- Description
排序方式。
可用值:
+created_at:最早的在前-created_at:最新的在前
返回值
分页的 Text to 3D 任务对象列表。
流式获取 Text to 3D 任务
以服务器发送事件(SSE)的形式流式推送 Text to 3D 任务的更新。
Request
curl -N https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response Stream
// Error event example
event: error
data: {
"status_code": 404,
"message": "Task not found"
}
// Message event examples illustrate task progress.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"progress": 0,
"status": "PENDING"
}
event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"progress": 50,
"status": "IN_PROGRESS"
}
event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
"emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20
}
参数
- Name
- id
- Type
- path
- Description
来自创建响应的任务 ID。
返回值
以服务器发送事件的形式返回 Text to 3D 任务对象 的流。
每个事件都包含完整的任务对象,其结构与 Get endpoint 返回的内容相同。当任务处于 PENDING 或 IN_PROGRESS 状态时,其结果字段尚无值。
Text to 3D 任务对象
Text to 3D 任务对象描述了一个根据文本 prompt 生成 3D 模型的任务。它保存了任务的状态、progress,以及任务成功后的模型文件。Text to 3D 有两个阶段,preview 和 refine。preview 任务生成仅含 mesh 的 3D 模型,refine 任务则根据 preview 的结果生成带贴图的 3D 模型。
属性
Example Text to 3D Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
},
"prompt": "a monster mask",
"texture_prompt": "green slimy skin with scales and warts",
"texture_image_url": "",
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
"emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20
}
- Name
- id
- Type
- string
- Description
任务 ID。请将其视为一个不透明的字符串,不要依赖其格式。
- Name
- type
- Type
- string
- Description
任务类型,
text-to-3d-preview表示 preview 任务,text-to-3d-refine表示 refine 任务。
- Name
- model_urls
- Type
- object
- Description
生成的 3D 模型的下载 URL,每种文件格式对应一个。任务未生成的格式不会有对应的键,而不是空字符串。
- Name
glb- Type
- string
- Description
GLB 文件。
- Name
fbx- Type
- string
- Description
FBX 文件。
- Name
usdz- Type
- string
- Description
USDZ 文件。
- Name
obj- Type
- string
- Description
OBJ 文件。
- Name
mtl- Type
- string
- Description
MTL 文件。
- Name
stl- Type
- string
- Description
STL 文件。
- Name
3mf- Type
- string
- Description
3MF 文件。仅当
target_formats包含3mf时才会出现。
- Name
- prompt
- Type
- string
- Description
你在创建任务时发送的
prompt,未经修改。
- Name
- texture_prompt
- Type
- string
- Description
你发送的、用于指导 refine 阶段贴图的文本 prompt。
- Name
- ultra_mode
- Type
- boolean
- ⚠ 已弃用
- Description
请改为读取
geometry_resolution。
- Name
- geometry_resolution
- Type
- string
- Description
preview 任务所使用的 Ultra 档位,
2k或4k。standard档位下不包含该字段。
- Name
- texture_image_url
- Type
- string
- Description
你发送的、用于指导贴图的图片的下载 URL。
- Name
- thumbnail_url
- Type
- string
- Description
3D 模型缩略图的下载 URL。
- Name
- alpha_thumbnail_url
- Type
- string
- Description
thumbnail_url的透明背景版本(RGBA)的下载 URL。仅当你在创建任务时设置了alpha_thumbnail: true,并且 Meshy 已渲染出透明预览图时才会出现。
- Name
- progress
- Type
- integer
- Description
任务完成的百分比。任务开始前为
0,成功后为100。
- Name
- started_at
- Type
- timestamp
- Description
任务开始的时间,以 Unix 毫秒表示。任务开始前为
0。
- Name
- created_at
- Type
- timestamp
- Description
任务创建的时间,以 Unix 毫秒表示。
- Name
- finished_at
- Type
- timestamp
- Description
任务完成的时间,以 Unix 毫秒表示。任务完成前为
0。
- Name
- status
- Type
- string
- Description
任务状态,取值为
PENDING、IN_PROGRESS、SUCCEEDED、FAILED或CANCELED之一。
- Name
- texture_urls
- Type
- array
- Description
生成的 texture 贴图的下载 URL,为一个对象数组。通常只包含一个对象。每个对象包含以下字段:
- Name
base_color- Type
- string
- Description
基础颜色贴图。
- Name
metallic- Type
- string
- Description
金属度贴图。如果你在创建任务时设置了
enable_pbr: false,则不会出现。
- Name
normal- Type
- string
- Description
法线贴图。如果你在创建任务时设置了
enable_pbr: false,则不会出现。
- Name
roughness- Type
- string
- Description
粗糙度贴图。如果你在创建任务时设置了
enable_pbr: false,则不会出现。
- Name
emission- Type
- string
- Description
自发光贴图。在以下任一情况下都不会出现:
- 你在创建任务时设置了
enable_pbr: false。 ai_model为meshy-6-lite、meshy-7、meshy-7.1或latest。texture_resolution为8k。- 该任务是在未设置
ai_model的情况下,对meshy-t2或meshy-t2.5的 preview 进行 refine。
- 你在创建任务时设置了
- Name
- preceding_tasks
- Type
- integer
- Description
排在此任务之前的队列任务数量。该值仅在任务处于
PENDING状态时才有意义。
- Name
- task_error
- Type
- object
- Description
任务失败时的错误详情。除非状态为
FAILED,否则为null。参见 Errors。
- Name
- consumed_credits
- Type
- integer
- Description
任务消耗的积分数量。当状态为
PENDING、IN_PROGRESS或SUCCEEDED时会出现该字段。对于FAILED的任务,该值为0,因为 Meshy 会在任务失败时退还积分。

