图像转3D API
图像转3D API 是一项功能,允许您将 Meshy 的图像转3D能力集成到您自己的应用程序中。在本节中,您将找到开始使用此API所需的所有信息。
创建图像转3D任务
此端点允许您创建一个新的图像转3D任务。请参阅图像转3D任务对象以查看图像转3D任务对象包含哪些属性。
参数
只需提供 input_task_id 或 image_url 其中之一(必选)。如果两者都提供,input_task_id 优先。
- Name
- input_task_id
- Type
- string
- 必选
- Description
已完成的图像生成任务的 ID,其输出将作为此任务的输入图片。该任务必须是以下任务之一:文本转图像或图像转图像。此外,它必须通过 API 运行、状态为
SUCCEEDED,并且仅产出一张图片。
- Name
- image_url
- Type
- string
- 必选
- Description
提供一张用于模型生成的图像。当前支持
.jpg、.jpeg和.png格式。有两种方式提供图片:
- 公网可访问的URL:一个可以从公网访问的图片链接。
- Data URI:图片的base64编码数据URI。例如:
data:image/jpeg;base64,<your base64-encoded image data>。
- Name
- model_type
- Type
- string
- 默认值 standard
- Description
指定3D网格生成的类型。
可选值:
standard:常规高细节3D网格生成。lowpoly:生成优化后多边形更简洁的低面数网格。
当选择
lowpoly时,ai_model、topology、target_polycount、should_remesh、save_pre_remeshed_model将被忽略。
- Name
- ai_model
- Type
- string
- 默认值 latest
- Description
要使用的模型ID。可选值:
meshy-5、meshy-6、latest(Meshy 6)。
- Name
- should_texture
- Type
- boolean
- 默认值 true
- Description
决定是否生成贴图。设置为
false时跳过贴图阶段,仅生成网格。
should_texture = true- Name
- enable_pbr
- Type
- boolean
- 默认值 false
- Description
生成 PBR 贴图(金属度、粗糙度、法线)以及基础色。当
ai_model为meshy-6或latest时,还会额外生成自发光贴图。
- Name
- hd_texture
- Type
- boolean
- 默认值 false
- Description
以 4K(4096×4096)分辨率生成基础色贴图,获得更高细节。
仅在
ai_model为meshy-6或latest时支持。PBR 贴图始终以 2K 分辨率生成。
- Name
- texture_prompt
- Type
- string
- Description
提供文本提示以引导贴图生成。最多600字符。
- Name
- texture_image_url
- Type
- string
- Description
提供一张2D图片以引导贴图生成。当前支持
.jpg、.jpeg和.png格式。有两种方式提供图片:
- 公网可访问的URL:一个可以从公网访问的图片链接。
- Data URI:图片的base64编码数据URI。例如:
data:image/jpeg;base64,<your base64-encoded image data>。
如果原始资产与上传图片在几何上差异较大,贴图效果可能不理想。
texture_image_url和texture_prompt只能二选一。如果都提供,则默认使用texture_prompt。通过文本或图片引导贴图均消耗10积分。
- Name
- should_remesh
- Type
- boolean
- 默认值 false (meshy-6), true (others)
- Description
控制是否启用重建网格阶段。当设置为
false时,API 将直接返回最高精度的三角网格。
should_remesh = true- Name
- topology
- Type
- string
- 默认值 triangle
- Description
指定生成模型的拓扑结构。
可选值:
quad:生成以四边形为主的网格。triangle:生成简化的三角网格。
- Name
- target_polycount
- Type
- integer
- 默认值 30,000
- Description
指定生成模型的目标面数。实际面数可能会根据几何复杂度有所偏差。
有效取值范围根据用户等级不同:
- 100 到 300,000(含)
- Name
- decimation_mode
- Type
- integer
- Description
通过设置面数级别启用自适应减面。设置后,
target_polycount将被忽略。可选值:
1:自适应——超高面数。2:自适应——高面数。3:自适应——中等面数。4:自适应——低面数。
- Name
- save_pre_remeshed_model
- Type
- boolean
- 默认值 false
- Description
设置为
true时,会在执行重建网格阶段之前额外保存一份原始 GLB 结果。
- Name
- symmetry_mode
- Type
- string
- 默认值 auto
- Description
symmetry_mode字段控制生成过程中对称性的行为。有效值:
off:关闭对称。auto:根据输入几何自动判断并应用对称。on:强制在生成过程中应用对称。
- Name
- pose_mode
- Type
- string
- 默认值 ""
- Description
指定生成模型的姿态模式。
可选值:
a-pose:生成 A Pose 的模型。t-pose:生成 T Pose 的模型。""(空字符串):不应用特定姿态。
- Name
- is_a_t_pose
- Type
- boolean
- ⚠ 已弃用
- 默认值 false
- Description
请使用
pose_mode代替。是否生成 A/T 姿态的模型。
- Name
- image_enhancement
- Type
- boolean
- 默认值 true
- Description
对输入图像进行优化以获得更好的生成效果。设置为
false时,模型将忠实还原输入图像的原始外观,不进行任何风格处理。仅当
ai_model为meshy-6或latest时支持。
- Name
- remove_lighting
- Type
- boolean
- 默认值 true
- Description
移除基础色贴图中的高光和阴影,生成更纯净的效果,在自定义光照设置下表现更佳。
仅当
ai_model为meshy-6或latest时支持。
- Name
- moderation
- Type
- boolean
- 默认值 false
- Description
当设置为
true时,输入内容将自动进行潜在有害内容筛查。如果检测到有害内容,任务将不会进入生成阶段。image_url、texture_image_url和texture_prompt的内容都将被筛查。
- Name
- target_formats
- Type
- string[]
- Description
指定输出中包含的 3D 文件格式。仅会生成并返回所请求的格式,可减少任务完成时间。省略时,将包含所有支持的格式。
可选值:
glb、obj、fbx、stl、usdz、3mf未指定时,除
3mf外的所有格式均会生成。3mf仅在明确指定时才会包含。
- Name
- auto_size
- Type
- boolean
- 默认值 false
- Description
当设置为
true时,服务使用 AI 视觉自动估算物体的真实高度并相应调整模型大小。除非显式设置了origin_at,否则原点将默认为bottom。
auto_size = true- Name
- origin_at
- Type
- string
- 默认值 bottom
- Description
当
auto_size启用时的原点位置。可选值:
bottom、center。
返回值
响应的result字段包含新建图像转3D任务的任务id。
失败模式
- Name
400 - Bad Request- Description
请求不合法。常见原因:
- 缺少参数:必须提供
image_url或input_task_id其中之一。 - 输入任务无效:
input_task_id必须引用一个状态为SUCCEEDED、且仅产出一张图片的文本转图像或图像转图像任务。 - 图片格式无效:提供的
image_url不是支持的格式(.jpg、.jpeg、.png)。 - URL 不可访问:
image_url无法下载(404 或超时)。 - Data URI 无效:base64 字符串格式错误。
- 参数组合无效:
enable_pbr仅在should_texture为 true 时支持。
- 缺少参数:必须提供
- Name
401 - Unauthorized- Description
认证失败。请检查您的 API 密钥。
- Name
402 - Payment Required- Description
积分不足,无法执行此任务。
- Name
429 - Too Many Requests- Description
您已超出请求频率限制。
请求
# 仅使用必需参数的简单请求
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>"
}'
# 启用重建网格、PBR 和 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>",
"enable_pbr": true,
"should_remesh": true,
"target_polycount": 100000,
"should_texture": true,
"pose_mode": "a-pose",
"target_formats": ["glb"]
}'
响应
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
获取图像转3D任务
此端点允许您通过有效的任务id获取图像转3D任务。请参阅图像转3D任务对象以查看图像转3D任务对象包含哪些属性。
参数
- Name
- id
- Type
- path
- Description
要获取的图像转3D任务的唯一标识符。
返回值
响应包含图像转3D任务对象。详情请查阅图像转3D任务对象部分。
请求
curl https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
响应
{
"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=***",
"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": {
"message": ""
},
"consumed_credits": 30
}
删除图像转3D任务
此端点将永久删除一个图像转3D任务,包括所有相关的模型和数据。此操作不可逆。
路径参数
- Name
- id
- Type
- path
- Description
要删除的图像转3D任务的ID。
返回值
成功则返回 200 OK。
请求
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
响应
// 成功则返回 200 Ok。
获取图像生成3D任务列表
此端点允许您获取图像转3D任务的列表。
参数
可选属性
- Name
- page_num
- Type
- integer
- Description
分页的页码。起始值和默认值为
1。
- Name
- page_size
- Type
- integer
- Description
每页返回的任务数量。默认为
10,最大允许为50。
- Name
- sort_by
- Type
- string
- Description
排序字段。可选值:
+created_at:按创建时间升序排序。-created_at:按创建时间降序排序。
返回值
返回分页的图像转3D任务对象列表。
请求
curl https://api.meshy.ai/openapi/v1/image-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
响应
[
{
"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=***",
"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": {
"message": ""
},
"consumed_credits": 30
}
]
流式图像转3D任务
此端点通过Server-Sent Events (SSE)流式返回图像转3D任务的实时进度更新。
参数
- Name
- id
- Type
- path
- Description
要流式获取的图像转3D任务的唯一标识符。
返回值
返回图像转3D任务对象的流式Server-Sent Events。
对于PENDING或IN_PROGRESS状态的任务,响应流仅包含必要的progress和status字段。
请求
curl -N https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
响应流
// Error event example
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": "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=***",
"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": {
"message": ""
},
"consumed_credits": 30
}
图像转3D任务对象
图像转3D任务对象是Meshy用于追踪从图像输入生成3D模型的工作单元。 该对象包含以下属性:
属性
- Name
- id
- Type
- string
- Description
任务的唯一标识符。虽然我们使用k-sortable UUID作为任务id的实现细节,但您不应对id格式做任何假设。
- Name
- type
- Type
- string
- Description
图像转3D任务的类型。值为
image-to-3d。
- Name
- model_urls
- Type
- object
- Description
Meshy生成的可下载带贴图3D模型文件的URL。如果某种格式未生成,则不会返回该属性。
- Name
glb- Type
- string
- Description
GLB文件的可下载URL。
- Name
fbx- Type
- string
- Description
FBX文件的可下载URL。
- Name
obj- Type
- string
- Description
OBJ文件的可下载URL。
- Name
usdz- Type
- string
- Description
USDZ文件的可下载URL。
- Name
mtl- Type
- string
- Description
当生成OBJ且包含贴图时返回的MTL文件下载链接。
- Name
stl- Type
- string
- Description
STL 文件的可下载链接。
- Name
3mf- Type
- string
- Description
3MF 文件的可下载链接。仅在通过
target_formats请求3mf时返回。
- Name
pre_remeshed_glb- Type
- string
- Description
重建网格前的原始GLB下载链接。
仅当任务创建时同时设置
should_remesh: true和save_pre_remeshed_model: true时才会提供。
- Name
- thumbnail_url
- Type
- string
- Description
模型文件缩略图的可下载URL。
- Name
- texture_prompt
- Type
- string
- Description
用于引导贴图生成的文本提示。
- Name
- texture_image_url
- Type
- string
- Description
用于引导贴图生成的图片URL。
- Name
- progress
- Type
- integer
- Description
任务进度。如果任务尚未开始,该属性为
0。任务成功后为100。
- Name
- started_at
- Type
- timestamp
- Description
任务开始的时间戳(毫秒)。如果任务尚未开始,该属性为
0。时间戳表示自1970年1月1日UTC以来的毫秒数,遵循RFC 3339标准。例如,2023年9月1日12:00:00 GMT为
1693569600000。此规则适用于Meshy API中的所有时间戳。
- Name
- created_at
- Type
- timestamp
- Description
任务创建的时间戳(毫秒)。
- Name
- expires_at
- Type
- timestamp
- Description
任务结果过期的时间戳(毫秒)。
- Name
- finished_at
- Type
- timestamp
- Description
任务完成的时间戳(毫秒)。如果任务尚未完成,该属性为
0。
- Name
- status
- Type
- string
- Description
任务状态。可能的值有
PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED。
- Name
- texture_urls
- Type
- array
- Description
任务生成的贴图URL对象数组。通常只包含一个贴图URL对象。每个贴图URL包含以下属性:
- Name
base_color- Type
- string
- Description
基础色贴图的可下载URL。
- Name
metallic- Type
- string
- Description
金属度贴图的可下载URL。
如果任务创建时
enable_pbr: false,则不会返回该属性。
- Name
normal- Type
- string
- Description
法线贴图的可下载URL。
如果任务创建时
enable_pbr: false,则不会返回该属性。
- Name
roughness- Type
- string
- Description
粗糙度贴图的可下载URL。
如果任务创建时
enable_pbr: false,则不会返回该属性。
- Name
emission- Type
- string
- Description
自发光贴图的可下载URL。
如果任务创建时
enable_pbr: false,或ai_model为meshy-5,则不会返回该属性。
- Name
- preceding_tasks
- Type
- integer
- Description
前置任务数量。
该字段仅在任务状态为
PENDING时有意义。
- Name
- task_error
- Type
- object
- Description
错误对象,包含任务失败时的错误信息。如果任务成功,
message应为空。详情请参阅 Errors。- Name
message- Type
- string
- Description
详细错误信息。
- Name
- consumed_credits
- Type
- integer
- Description
该任务消耗的积分数。当任务状态为
PENDING、IN_PROGRESS或SUCCEEDED时返回。对于FAILED任务返回0(失败时积分会被退还)。
图像转3D任务对象示例
{
"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=***",
"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": {
"message": ""
},
"consumed_credits": 30,
}