Multi-Image to 3D API
通过同一物体从不同角度拍摄的一到四张图像生成 3D 模型。
创建 Multi-Image to 3D 任务
创建一个 Multi-Image to 3D 任务。任务会在后台运行。关于任务通常需要多长时间,请参阅处理时间。关于任务包含哪些字段,请参阅 Multi-Image to 3D 任务对象。
Request
# Simple request
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_urls": [
"<your publicly accessible image url or base64-encoded data URI>",
"<your second publicly accessible image url or base64-encoded data URI>"
]
}'
# With Ultra 2K geometry, PBR texturing, and GLB format
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_urls": [
"<your publicly accessible image url or base64-encoded data URI>",
"<your second publicly accessible image url or base64-encoded data URI>"
],
"ai_model": "meshy-7.1",
"geometry_resolution": "2k",
"should_texture": true,
"enable_pbr": true,
"target_formats": ["glb"]
}'
# Textured with Meshy N1 from the input images, the first as the front view
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_urls": [
"<your front view image url or base64-encoded data URI>",
"<your back view image url or base64-encoded data URI>"
],
"ai_model": "meshy-7.1",
"texture_model": "meshy-n1"
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
参数
- Name
- input_task_id
- Type
- string
- 必选
- Description
除非你发送
image_urls,否则为必填项。一个 Text to Image 或 Image to Image 任务(包括多视图任务)的 ID。Meshy 会使用其一到四张图片作为输入。该任务必须是你通过 API 创建的、状态为SUCCEEDED的任务。
- Name
- image_urls
- Type
- array
- 必选
- Description
除非你发送
input_task_id,否则为必填项。一到四张图片,每张以公开可访问的 URL 或 data URI 形式提供,例如data:image/jpeg;base64,<your base64-encoded image data>。如果两者都发送,Meshy 会使用input_task_id。每张图片必须是
.jpg、.jpeg、.png或.webp格式的文件,大小不超过 20 MB,每边至少 32 像素,且总像素数(宽 × 高)不超过 178,956,970。超过四张图片会返回400。为获得最佳效果,这些图片应展示同一物体的不同角度。使用
meshy-7.1或latest时,Meshy 会将第一张图片作为正面视图,其余图片的顺序无关紧要。
- Name
- ai_model
- Type
- string
- 默认值 latest
- Description
生成 3D 模型所使用的 AI 模型。
可用值:
latest:Meshy 7.1meshy-7.1meshy-6meshy-6-litemeshy-7:已 deprecated,请改为发送meshy-7.1。该模型将于 2026 年 12 月 31 日下线。
请参阅模型,了解哪种模型适合你的项目,例如真实物体或 3D 打印件。
- Name
- geometry_resolution
- Type
- string
- 默认值 standard
- Description
要生成多少 geometry 细节。
可用值:
standard2k:以 2048³ 运行 Ultra pass。需要meshy-7.1、latest,或已 deprecated 的meshy-7。
- Name
- ultra_mode
- Type
- boolean
- ⚠ 已弃用
- 默认值 false
- Description
请改为发送
geometry_resolution。ultra_mode: true与geometry_resolution: "2k"效果相同。
- Name
- should_texture
- Type
- boolean
- 默认值 true
- Description
是否生成 texture。
true会返回带 texture 的模型,false会跳过贴图步骤,返回不带 texture 的 mesh。
should_texture = true- Name
- texture_model
- Type
- string
- 默认值 depends on ai_model
- Description
在同一任务中,从多个视图为 3D 模型贴图所使用的 AI 模型。留空则使用你所选
ai_model的默认 texture 模型。它不会改变积分消耗。可用值:
meshy-7:Meshy 7,带 PBR 贴图,texture 最高可达 8Kmeshy-n1:Meshy N1,仅根据参考图片生成 2K 基础色 texture
每种
ai_model都支持这两者。使用meshy-6或meshy-6-lite发送带贴图的请求会返回400,所选 texture 模型不支持的选项也会返回400。当should_texture: false时,Meshy 会忽略texture_model,但未知值仍会返回400。使用
meshy-n1时,Meshy 会根据texture_image_urls或texture_image_url进行贴图;如果两者都未发送,则根据输入图片贴图。第一张图片为正面视图。生成的模型若超过 7,999,999 个三角面,任务会失败,Meshy 会退还相应积分。请参阅模型,了解每种 texture 模型的作用及如何选择。
- Name
- enable_pbr
- Type
- boolean
- 默认值 false
- Description
除基础色之外,是否也生成金属度、粗糙度和法线贴图。Meshy 6 texture 模型还会生成自发光贴图,但在
texture_resolution: 8k时除外。使用texture_model: meshy-n1时,设为true会返回400。
- Name
- texture_resolution
- Type
- string
- 默认值 2k
- Description
基础色 texture 的尺寸。尺寸越大,能捕捉的表面细节越多。
可用值:
2k:2048×20484k:4096×40968k:8192×8192
4k和8k需要 Meshy 7 或 Meshy 6 texture 模型,使用其他模型会返回400。在8k下,Meshy 不会生成自发光贴图。
- 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_model: meshy-n1时,发送该字段会返回400。
- Name
- texture_image_url
- Type
- string
- Description
一张用于指导 texture 的 2D 图片,以公开可访问的 URL 或 data URI 形式提供,例如
data:image/jpeg;base64,<your base64-encoded image data>。该图片必须是.jpg、.jpeg、.png或.webp格式的文件,大小不超过 20 MB,每边至少 32 像素,且总像素数(宽 × 高)不超过 178,956,970。如果你同时发送
texture_image_url和texture_prompt,Meshy 会使用texture_prompt。使用texture_model: meshy-n1时,Meshy 会将此图片用作正面视图进行贴图。当图片中的形状与 3D 模型差异较大时,texture 效果可能不理想。
- Name
- texture_image_urls
- Type
- string[]
- Description
一到四张从不同视角展示该物体、用于指导 texture 的图片。Meshy 会将第一张图片作为正面视图。其余视图(左侧、背面、右侧)的顺序无关紧要。
每张图片遵循与
texture_image_url相同的规则:公开可访问的 URL 或 data URI,格式为.jpg、.jpeg、.png或.webp,大小不超过 20 MB,每边至少 32 像素,且总像素数(宽 × 高)不超过 178,956,970。这些图片仅用于指导 texture,不依赖于
image_urls。这两个列表可以包含不同的图片,数量也可以不同。texture_image_urls需要 Meshy 7 或 Meshy N1 texture 模型。请配合以下之一发送:ai_model为meshy-7.1、latest,或已 deprecated 的meshy-7texture_model为meshy-7或meshy-n1
不能将其与
texture_image_url或texture_prompt一起发送。
- 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
remesh 后模型的面类型。
可用值:
quad:以四边面为主的 meshtriangle:经过精简的三角面 mesh
使用
texture_model: meshy-n1时,如果模型会被 remesh(meshy-6-lite默认如此),quad会返回400。
- Name
- target_polycount
- Type
- integer
- 默认值 30000
- Description
目标面数,范围从
100到300000。实际结果可能因模型的 geometry 而与目标值有所不同。超出此范围的值会返回400。
- Name
- decimation_mode
- Type
- integer
- Description
按级别自适应控制面数。设置此项后,Meshy 会忽略
target_polycount。可用值:
1:ultra2:high3:medium4:low
- Name
- save_pre_remeshed_model
- Type
- boolean
- 默认值 false
- Description
是否同时保存 remesh 之前的 GLB,会通过
model_urls.pre_remeshed_glb返回。
- 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 字或 T 字姿势生成模型。
- Name
- image_enhancement
- Type
- boolean
- 默认值 true
- Description
是否在生成前优化输入图片。
false会保留输入图片的原始外观,不做任何风格处理。仅meshy-6、meshy-7.1或latest支持此项。与meshy-6-lite一起发送会返回400。
- Name
- remove_lighting
- Type
- boolean
- 默认值 true
- Description
是否从基础色 texture 中移除高光和阴影。更干净的结果在你自己的光照环境下表现更好。只有 Meshy 6 texture 模型会使用此项,且在
texture_resolution: 8k时始终会移除光照。使用texture_model: meshy-n1时,设为true会返回400。使用ai_model: meshy-6-lite及其默认 texture 模型时,发送此项会返回400。
- Name
- moderation
- Type
- boolean
- 默认值 false
- Description
是否对输入内容进行有害内容筛查。Meshy 会筛查每张输入图片、
texture_image_url或texture_image_urls中的每张图片,以及texture_prompt中的文本。如果 Meshy 发现有害内容,请求会返回400,Meshy 不会创建任务。
- Name
- target_formats
- Type
- string[]
- Description
要生成的 3D 文件格式。Meshy 只会生成并返回你所列出的格式,这可以缩短任务耗时。
可用值:
glbobjfbxstlusdz3mf
如果留空,Meshy 会生成除
3mf之外的所有格式。只有当你列出3mf时,Meshy 才会生成该格式。
- 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。
- Name
- alpha_thumbnail
- Type
- boolean
- 默认值 false
- Description
是否同时渲染带透明背景(RGBA)的预览图,获取任务时会在
alpha_thumbnail_url中返回。thumbnail_url不受影响。
- Name
- multi_view_thumbnails
- Type
- boolean
- 默认值 false
- Description
是否同时渲染正面、右侧、背面和左侧的预览图,获取任务时会在
thumbnail_urls中返回。thumbnail_url不受影响,仍显示正面视图。此项会使任务多花费约 5 秒。
返回值
响应中的 result 字段保存着新建的 Multi-Image to 3D 任务的 ID。
失败情况
- Name
400 - Bad Request- Description
请求无法运行。错误信息会说明发现了什么问题。例如:
- 缺少参数:既未发送
image_urls,也未发送input_task_id。 - 输入任务无效:
input_task_id不是一个状态为SUCCEEDED的 Text to Image 或 Image to Image 任务,也不是多视图任务。 - 图片数量无效:
image_urls或texture_image_urls中的图片数量不在 1 到 4 之间。 - 图片格式无效:
image_urls中的某张图片格式不受支持。 - texture 输入冲突:
texture_image_urls与texture_image_url、texture_prompt,或should_texture: false一起发送。 - 该模型不支持多视图 texture:
texture_image_urls与ai_model为meshy-6或meshy-6-lite一起发送,除非texture_model为meshy-7或meshy-n1。 - URL 无法访问:Meshy 无法下载
image_urls或texture_image_urls中的某张图片。 - 图片过大:
image_urls、texture_image_url或texture_image_urls中的某张图片超过 20 MB。 - 图片尺寸无效:
image_urls、texture_image_url或texture_image_urls中的某张图片某边小于 32 像素,或总像素数(宽 × 高)超过 178,956,970。 - 多图输入不支持该分辨率:
geometry_resolution为"4k",该 endpoint 不支持此值。请使用2k或standard。 - 该模型不支持此图片选项:使用
ai_model: "meshy-6-lite"时发送了image_enhancement,或使用ai_model: "meshy-6-lite"及其默认 texture 模型时发送了remove_lighting。 - texture 模型无效:
texture_model不是有效的 texture 模型名称。 - texture 模型不可用:带贴图的请求发送了
texture_model为meshy-6或meshy-6-lite。Multi-Image to 3D 只接受支持从多视图贴图的 texture 模型。请发送meshy-7或meshy-n1,或留空texture_model。 - 该 texture 模型不支持此选项:请求向 texture 模型请求了其不支持的选项,例如在
meshy-n1下设置enable_pbr: true,或在meshy-6-lite下使用4ktexture。请参阅模型。
请修正请求后重新发送。请参阅 Errors。
- 缺少参数:既未发送
- Name
401 - Unauthorized- Description
缺少 API key 或 API key 无效。请检查
Authorization请求头。
- Name
402 - Payment Required- Description
例如:
- 积分不足:账户没有足够的积分来完成此任务,或账户达到了积分限额。请检查你的积分 balance,然后重试。
- 免费计划:创建任务需要付费计划。请在你的订阅设置中升级计划,然后重试。
- Name
403 - Forbidden- Description
内容审核拦截了 prompt 或某张输入图片。请修改输入内容后重试。
- Name
404 - Not Found- Description
input_task_id与你的任何任务都不匹配。请检查任务 ID 后重新发送请求。
- Name
429 - Too Many Requests- Description
你已超出速率限制。请稍候后重试。请参阅速率限制。
获取 Multi-Image to 3D 任务
根据 ID 返回一个 Multi-Image to 3D 任务。
Request
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "multi-image-to-3d",
"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=***",
"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=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"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"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 30
}
删除一个 Multi-Image to 3D 任务
永久删除一个 Multi-Image to 3D 任务,包括其模型和数据。删除操作无法撤销。
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/multi-image-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。
获取 Multi-Image to 3D 任务列表
返回你的 Multi-Image to 3D 任务列表。
Request
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "multi-image-to-3d",
"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=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"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"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 30
}
]
参数
- 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:从最新到最早
返回
一个分页的 Multi-Image to 3D 任务对象列表。
流式获取 Multi-Image to 3D 任务
以服务器发送事件(SSE)的形式流式推送 Multi-Image to 3D 任务的更新。
Request
curl -N https://api.meshy.ai/openapi/v1/multi-image-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",
"type": "multi-image-to-3d",
"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=***",
"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=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"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"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 30
}
参数
- Name
- id
- Type
- path
- Description
创建响应中返回的任务 ID。
返回值
以服务器发送事件形式推送的 Multi-Image to 3D 任务对象 数据流。
每个事件都包含完整的任务对象,其结构与 Get endpoint 返回的内容相同。当任务处于 PENDING 或 IN_PROGRESS 状态时,其结果字段尚无取值。
Multi-Image to 3D 任务对象
Multi-Image to 3D 任务对象描述了根据一张到四张物体图片生成 3D 模型的一次生成过程。它保存了任务的状态、进度,以及任务成功后的模型文件。
属性
Example Multi-Image to 3D Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "multi-image-to-3d",
"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=***",
"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=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"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"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 30
}
- Name
- id
- Type
- string
- Description
任务 ID。请将其视为不透明字符串,不要依赖其格式。
- Name
- type
- Type
- string
- Description
任务类型,始终为
multi-image-to-3d。
- Name
- model_urls
- Type
- object
- Description
生成的 3D 模型的下载 URL,每种文件格式一个。任务未生成的格式不会有对应的键,而不是空字符串。
- Name
glb- Type
- string
- Description
GLB 文件。
- Name
fbx- Type
- string
- Description
FBX 文件。
- Name
obj- Type
- string
- Description
OBJ 文件。
- Name
usdz- Type
- string
- Description
USDZ 文件。
- Name
mtl- Type
- string
- Description
MTL 文件,当模型带有 texture 时会随 OBJ 文件一起返回。
- Name
stl- Type
- string
- Description
STL 文件。
- Name
3mf- Type
- string
- Description
3MF 文件。仅当
target_formats包含3mf时才会出现。
- Name
pre_remeshed_glb- Type
- string
- Description
Remesh 之前的 GLB 文件。仅当创建任务时同时设置了
should_remesh: true和save_pre_remeshed_model: true时才会出现。
- Name
- thumbnail_url
- Type
- string
- Description
模型预览图的下载 URL。当
thumbnail_urls.front字段存在时,它与该字段的值相同。
- Name
- alpha_thumbnail_url
- Type
- string
- Description
thumbnail_url的透明背景版本(RGBA)的下载 URL。仅当创建任务时设置了alpha_thumbnail: true且 Meshy 渲染了透明预览图时才会出现。
- Name
- thumbnail_urls
- Type
- object
- Description
3D 模型四个方向预览图的下载 URL。每个都是指向 512×512 PNG 图片的签名 URL,使用与
thumbnail_url相同的材质和光照渲染而成。你可以用它们在不下载 GLB 的情况下从多个角度预览模型。仅当创建任务时设置了
multi_view_thumbnails: true且任务达到SUCCEEDED状态时才会出现。未设置multi_view_thumbnails: true创建的任务没有此字段。- Name
- front
- Type
- string
- Description
正视图,绕竖直轴 0°。它与
thumbnail_url相同。
- Name
- right
- Type
- string
- Description
右视图,90°。
- Name
- back
- Type
- string
- Description
后视图,180°。
- Name
- left
- Type
- string
- Description
左视图,270°。
- Name
- texture_prompt
- Type
- string
- Description
指导 texture 生成的文本 prompt。
- Name
- texture_image_urls
- Type
- string[]
- Description
创建任务时使用的 texture 参考图片的下载 URL,顺序与你发送时的顺序一致。仅当创建任务时提供了
texture_image_urls时才会出现。
- Name
- ultra_mode
- Type
- boolean
- ⚠ 已弃用
- Description
请改为读取
geometry_resolution。
- Name
- geometry_resolution
- Type
- string
- Description
任务运行所使用的 Ultra 档位,即
2k。standard任务没有此字段。
- Name
- progress
- Type
- integer
- Description
任务完成的百分比。任务开始前为
0,成功后为100。
- Name
- started_at
- Type
- timestamp
- Description
任务开始的时间,以 Unix 毫秒表示。任务开始前为
0。
- Name
- created_at
- Type
- timestamp
- Description
任务创建的时间,以 Unix 毫秒表示。
- Name
- expires_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
自发光贴图。仅当创建任务时同时满足以下所有条件才会包含:
ai_model: meshy-6,并使用其默认 texture 模型enable_pbr: truetexture_resolution为2k或4k
- 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 会在任务失败时退还积分。