Image to 3D API
将图像转换为 3D 模型,可选择是否带贴图,并可选择所需的格式。发送图像,或使用文字生成影像或影像生成影像任务的输出结果。
Create an Image to 3D task
创建一个 Image to 3D 任务。该任务会在后台运行。关于任务通常需要多长时间,请参阅处理时间。
Request
# Simple request with required params
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-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>"
}'
# With Ultra 4K geometry, remesh, PBR, and A-pose
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-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>",
"ai_model": "meshy-7.1",
"geometry_resolution": "4k",
"enable_pbr": true,
"should_remesh": true,
"target_polycount": 100000,
"should_texture": true,
"pose_mode": "a-pose",
"target_formats": ["glb"]
}'
# Textured with Meshy N1 from the input image
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-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>",
"ai_model": "meshy-7.1",
"texture_model": "meshy-n1"
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
参数
- Name
- input_task_id
- Type
- string
- 必选
- Description
除非发送
image_url,否则必填。你想要用作输入的 Text to Image 或 Image to Image 任务的 ID,该图片将被使用。该任务必须是你通过 API 创建的、状态为SUCCEEDED,且恰好生成了一张图片的任务。
- Name
- image_url
- Type
- string
- 必选
- Description
除非发送
input_task_id,否则必填。要转换为 3D 模型的图片,可以是公开可访问的 URL,也可以是 base64 编码的 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(宽 × 高)。
- Name
- model_type
- Type
- string
- 默认值 standard
- Description
要生成的 3D mesh 类型。
可用值:
standard:高细节 meshsmart-topology:来自 Smart Topology 模型的 mesh,你可以通过ai_model(meshy-t2或meshy-t2.5)来选择
使用
smart-topology时,Meshy 会忽略should_remesh、save_pre_remeshed_model和decimation_mode,并且只接受topology: triangle。
- Name
- ai_model
- Type
- string
- 默认值 latest
- Description
用于生成 3D 模型的 AI 模型。可用的值取决于
model_type。标准模型(
model_type: standard):latest:Meshy 7.1meshy-7.1meshy-6meshy-6-litemeshy-7(deprecated):请改用meshy-7.1。该模型将于 2026 年 12 月 31 日下线。
Smart Topology 模型(
model_type: smart-topology)生成三角形网格,面数可通过target_polycount设置:meshy-t2:更干净的 topology 以及原生分离的部件meshy-t2.5(默认):为游戏 asset 提供更锐利的细节
请参阅模型,了解哪种模型适合你的项目,例如游戏角色或 3D 打印模型。
- Name
- geometry_resolution
- Type
- string
- 默认值 standard
- Description
geometry 生成的处理阶段。
可用值:
standard2k:以 2048³ 运行 Ultra 阶段4k:以 4096³ 运行 Ultra 阶段,以获得最精细的表面细节
2k需要meshy-7.1、latest或已 deprecated 的meshy-7。4k需要meshy-7.1或latest。
- 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 基础色 texturemeshy-6-lite:Meshy 6 Lite,以最低成本生成 2K texturemeshy-6:Meshy 6,仅在ai_model: meshy-6时作为默认模型
每个
ai_model都接受meshy-7、meshy-n1和meshy-6-lite。如果请求的选项所选 texture 模型不支持,会返回400。使用meshy-n1时,如果生成的模型超过 7,999,999 个三角面,任务会失败,Meshy 会退还 积分。设置should_texture: false时,Meshy 会忽略texture_model,但未知的值仍会返回400。请参阅模型,了解各个 texture 模型的功能以及如何选择。
- Name
- enable_pbr
- Type
- boolean
- 默认值 false
- Description
除了基础色之外,是否还生成 PBR 贴图(金属度、粗糙度和法线)。
true需要should_texture: true,若should_texture: false则返回400。使用texture_model: meshy-n1时,设置true会返回400。Meshy 6 texture 模型还会生成 emission 贴图,但在
texture_resolution: 8k时除外。
- Name
- texture_resolution
- Type
- string
- 默认值 2k
- Description
基础色 texture 的尺寸。更大的 texture 能捕捉更多表面细节。
可用值:
2k:2048×20484k:4096×40968k:8192×8192
4k和8k需要 Meshy 7 或 Meshy 6 texture 模型,其他模型使用这两个值会返回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_model: meshy-n1时,发送该参数会返回400。
- Name
- texture_image_url
- Type
- string
- Description
用于指导 texture 的图片,可以是公开可访问的 URL,也可以是 base64 编码的 data URI,例如
data:image/jpeg;base64,<your base64-encoded image data>。图片必须是 JPG、JPEG、PNG 或 WebP 文件,大小不超过 20 MB,每边至少 32 像素,且总像素不超过 178,956,970(宽 × 高)。Meshy 只会使用
texture_prompt和texture_image_url中的一个来指导 texture。如果两者都发送,Meshy 会使用texture_prompt。关于贴图的 积分 消耗,请参阅 Pricing。使用
texture_model: meshy-n1时,Meshy 会将该图片作为正面视图进行贴图;如果留空,则使用输入图片。当图片的形状与 3D 模型的 geometry 差异较大时,基于图片的贴图效果可能不理想。
- 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 的输出仅支持三角形,因此在
meshy-t2或meshy-t2.5下使用quad会返回400。使用texture_model: meshy-n1时,如果模型进行了 remesh(meshy-6-lite默认会这样做),quad会返回400。
- Name
- decimation_mode
- Type
- integer
- Description
按级别自适应设置面数。当你设置了此项时,Meshy 会忽略
target_polycount。可用值:
1:ultra(极致)2:high(高)3:medium(中)4:low(低)
- Name
- save_pre_remeshed_model
- Type
- boolean
- 默认值 false
- Description
是否同时保存 remesh 阶段之前的模型的 GLB 文件。Meshy 会在
model_urls.pre_remeshed_glb中返回该文件。
- 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 模型,而不是对标准模型进行 remesh。请参阅模型。
- Remesh:当在
- Name
- symmetry_mode
- Type
- string
- ⚠ 已弃用
- 默认值 auto
- Description
请将此项留空,因为它不会影响输出。该参数原本用于控制生成过程中的 symmetry:
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
- surface_mode
- Type
- string
- ⚠ 已弃用
- Description
请改用
ai_model。该参数不会影响输出,因为它所选择的模型生成方式已经下线。可接受的值为
organic和hard。其他任何值都会返回400。
- Name
- image_enhancement
- Type
- boolean
- 默认值 true
- Description
是否在生成前对输入图片进行优化。
false会保留输入图片的原始外观,不进行任何风格处理。该选项仅适用于
meshy-6、meshy-7.1或latest。使用meshy-6-lite或model_type: smart-topology时,会返回400。
- Name
- remove_lighting
- Type
- boolean
- 默认值 true
- Description
是否从基础色 texture 中去除高光和阴影。处理后的结果更干净,在你自己的灯光环境下效果更好。
该选项仅在使用 Meshy 6 texture 模型时生效,若所选 texture 模型不支持此项,设置为
true会返回400。使用model_type: smart-topology,或使用ai_model: meshy-6-lite及其默认 texture 模型时,发送此参数会返回400。
- Name
- moderation
- Type
- boolean
- 默认值 false
- Description
是否在生成前对以下输入内容进行有害内容筛查:
image_urltexture_image_urltexture_prompt
如果 Meshy 检测到有害内容,请求将返回
400,且 Meshy 不会创建任务。
- Name
- target_formats
- Type
- string[]
- Description
要生成的文件格式。Meshy 只会生成并返回你所列出的格式,这可以缩短任务耗时。如果留空,Meshy 会生成除
3mf之外的所有格式;只有当你明确列出3mf时,才会生成该格式。可用值:
glbobjfbxstlusdz3mf
- Name
- auto_size
- Type
- boolean
- 默认值 false
- Description
是否使用 AI 视觉估算物体的真实世界高度,并据此调整模型尺寸。除非你设置了
origin_at,否则 Meshy 会将 origin 放置在底部。
- 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 秒。
auto_size = true- Name
- origin_at
- Type
- string
- 默认值 bottom
- Description
模型 origin 的放置位置,
bottom或center。
返回值
响应中的 result 字段保存了新建 Image to 3D 任务的 ID。
失败情形
- Name
400 - Bad Request- Description
请求无法执行。错误信息会说明具体发现了哪个问题。例如:
- 缺少参数:既未发送
image_url,也未发送input_task_id。 - 输入任务无效:
input_task_id不是一个状态为SUCCEEDED、且恰好生成了一张图片的 Text to Image 或 Image to Image 任务。 - 图片格式无效:
image_url指向的图片不是 JPG、JPEG、PNG 或 WebP 文件。 - URL 无法访问:Meshy 无法下载
image_url指向的图片,因为该 URL 返回404或超时。 - 图片过大:
image_url或texture_image_url指向的图片超过 20 MB。 - 图片尺寸无效:
image_url或texture_image_url指向的图片有一边小于 32 像素,或总像素超过 178,956,970(宽 × 高)。 - data URI 无效:base64 字符串格式有误。
- 参数组合无效:
enable_pbr为true,但should_texture为false。 - 不支持 Ultra 的模型:
geometry_resolution为2k或4k,但所选ai_model无法运行该功能。 - 不支持该图片选项的模型:以下情况之一:
- 在
ai_model: "meshy-6-lite"或model_type: "smart-topology"下发送了image_enhancement。 - 在
model_type: "smart-topology"下,或在ai_model: "meshy-6-lite"及其默认 texture 模型下,发送了remove_lighting。
- 在
- texture 模型无效:
texture_model不是可用值之一。 - texture 模型不可用:
texture_model为meshy-6,但ai_model不是meshy-6。请发送meshy-7、meshy-n1或meshy-6-lite,或将其留空。 - texture 模型不支持该选项:请求中要求该 texture 模型执行其不支持的选项,例如在
meshy-n1下设置enable_pbr: true,或在meshy-6-lite下使用4ktexture。请参阅模型。
请修正请求后重新发送。参阅 Errors。
- 缺少参数:既未发送
- Name
401 - Unauthorized- Description
API key 缺失或无效。请检查
Authorization请求头。
- Name
402 - Payment Required- Description
例如:
- 积分不足:账户没有足够的 积分 来执行此任务,或账户已达到 积分 上限。请检查你的 积分 余额,然后重试。
- 免费计划:创建任务需要付费计划。请在订阅设置中升级你的计划,然后重试。
- Name
403 - Forbidden- Description
内容审核拦截了该 prompt 或某张输入图片。请修改输入内容后重试。
- Name
404 - Not Found- Description
input_task_id与你的任何任务都不匹配。请检查任务 ID,然后重新发送请求。
- Name
429 - Too Many Requests- Description
你已超出速率限制。请稍候后重试。参阅速率限制。
获取 Image to 3D 任务
根据 ID 返回一个 Image to 3D 任务。
Request
curl https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "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",
"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": 30
}
删除 Image to 3D 任务
永久删除一个 Image to 3D 任务,包括它的模型和数据。删除操作无法撤销。
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/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。
列出 Image to 3D 任务
返回您的 Image to 3D 任务列表。
Request
curl https://api.meshy.ai/openapi/v1/image-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "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",
"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": 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:最新优先
返回值
分页的 Image to 3D 任务对象列表。
流式获取 Image to 3D 任务
以服务器发送事件(SSE)的形式,流式返回 Image to 3D 任务的更新。
Request
curl -N https://api.meshy.ai/openapi/v1/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": "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",
"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": 30
}
参数
- Name
- id
- Type
- path
- Description
创建响应中返回的任务 ID。
返回值
以服务器发送事件的形式返回的 Image to 3D 任务对象 流。
每个事件都包含完整的任务对象,其结构与 Get endpoint 返回的内容相同。当任务处于 PENDING 或 IN_PROGRESS 状态时,其结果字段尚无值。
Image to 3D 任务对象
一个 Image to 3D 任务对象描述了一次从图像生成 3D 模型的任务。它保存了任务的状态、进度,以及任务成功后的模型文件。
属性
Example Image to 3D Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "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": "",
"texture_image_url": "",
"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",
"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": 30
}
- Name
- id
- Type
- string
- Description
任务 ID。请将其视为一个不透明字符串,不要依赖其格式。
- Name
- type
- Type
- string
- Description
任务类型,始终为
image-to-3d。
- Name
- model_urls
- Type
- object
- Description
生成的 3D 模型的下载链接,每种文件格式对应一个。任务未生成的格式不会有对应的键,而不是空字符串。
- 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
3D 模型预览图的下载链接。当存在
thumbnail_urls时,它与thumbnail_urls.front是同一张图片。Meshy 保留此字段是为了向后兼容。
- Name
- alpha_thumbnail_url
- Type
- string
- Description
thumbnail_url的透明背景版本(RGBA)的下载链接。仅当你在创建任务时设置了alpha_thumbnail: true且 Meshy 渲染出了透明预览图时才会出现。
- Name
- thumbnail_urls
- Type
- object
- Description
从四个方向查看 3D 模型的预览图下载链接。每个值都是一个指向 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_url
- Type
- string
- Description
用于指导 texture 生成的图片的下载链接。
- Name
- ultra_mode
- Type
- boolean
- ⚠ 已弃用
- Description
请改用
geometry_resolution。
- Name
- geometry_resolution
- Type
- string
- Description
任务运行的 Ultra 档位,
2k或4k。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 贴图,是一个对象数组。它通常只包含一个对象,具有以下字段:
- 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
自发光贴图的下载链接。只有当你在创建任务时同时满足以下所有条件时,Meshy 才会包含此字段:
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 会在任务失败时退还积分。