Image to 3D API

Image to 3D API 是一项功能，可让你将 Meshy 的 Image to 3D 能力集成到自己的应用程序中。在本节中，你将找到开始使用此 API 所需的所有信息。

POST/openapi/v1/image-to-3d

创建 Image to 3D 任务

此 endpoint 允许你创建一个新的 Image to 3D 任务。请参阅 The Image to 3D Task Object 以了解 Image to 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
提供一张图像供 Meshy 用于模型创建。我们目前支持 .jpg、.jpeg 和 .png 格式。
有两种方式提供图像：
- 可公开访问的 URL：可从公共互联网访问的 URL。
- Data URI：图像的 base64 编码 data URI。data URI 示例：data:image/jpeg;base64,<your base64-encoded image data>。

Name
model_type
Type
string
默认值 standard
Description
指定 3D 网格生成的类型。
可用值：
- standard：常规高细节 3D 网格生成。
- smart-topology：通过 ai_model（meshy-t1 或 meshy-t2）选择 Smart Topology 模型。
- lowpoly（deprecated）：生成经过优化、多边形更简洁的 low-poly 网格。我们建议改用 smart-topology。
选择 smart-topology 时，topology、should_remesh 和 save_pre_remeshed_model 将被忽略。
选择 lowpoly 时，ai_model、topology、target_polycount、should_remesh 和 save_pre_remeshed_model 将被忽略。
Name
ai_model
Type
string
默认值 latest
Description
要使用的模型 ID。可用值取决于 model_type。
标准生成（model_type: standard）：
- meshy-5、meshy-6、meshy-7、latest（Meshy 7）
Smart Topology 生成（model_type: smart-topology）：
- meshy-t2（默认，推荐）：Smart Topology 模型——更干净的 topology、原生分离的部件、三角形输出，并可通过 target_polycount 设置面数。
- meshy-t1：旧的 low-poly 模型；不支持通过 target_polycount 设置面数。
Name
ultra_mode
Type
boolean
默认值 false
Description
启用 Ultra 生成，以获得更高保真度的 geometry 和更精细的表面细节。
仅当 ai_model 为 meshy-7（或 latest）时支持。
Name
should_texture
Type
boolean
默认值 true
Description
决定是否生成 texture。设置为 false 会跳过 texture 阶段，提供不带 texture 的 mesh。

仅当 should_texture = true

Name
enable_pbr
Type
boolean
默认值 false
Description
除基础颜色外，还生成 PBR 贴图（金属度、粗糙度、法线）。当 ai_model 为 meshy-6 时也会包含自发光贴图，但 texture_resolution: 8k 时除外。meshy-7 和 latest 不会生成自发光贴图。
Name
texture_resolution
Type
string
默认值 2k
Description
基础颜色 texture 分辨率。可选 2k（2048×2048）、4k（4096×4096）或 8k（8192×8192）。分辨率越高，捕捉的表面细节越多。
ai_model: meshy-5 不支持 4k 和 8k。在 8k 下不会生成自发光贴图。
Name
hd_texture
Type
boolean
⚠ 已弃用
默认值 false
Description
请改用 texture_resolution——等同于 texture_resolution: "4k"。当两者都设置时，texture_resolution 优先。
Name
texture_prompt
Type
string
Description
提供文本 prompt 以指导贴图过程。最多 600 个字符。
Name
texture_image_url
Type
string
Description
提供一张 2D 图像以指导贴图过程。我们目前支持 .jpg、.jpeg 和 .png 格式。
有两种方式提供图像：
- 可公开访问的 URL：可从公共互联网访问的 URL
- Data URI：图像的 base64 编码 data URI。data URI 示例：data:image/jpeg;base64,<your base64-encoded image data>
如果原始资产与上传图像之间存在较大的 geometry 差异，图像贴图可能无法达到最佳效果。texture_image_url 和 texture_prompt 只能使用其中一个来指导贴图过程。如果两个参数都提供，则默认使用 texture_prompt 对模型进行贴图。通过文本或图像进行贴图，每个任务将花费 10 credits。

Name
should_remesh
Type
boolean
默认值 false (meshy-6, meshy-7), true (others)
Description
控制是否启用 remesh 阶段。为获得最高质量的模型，我们建议将 should_remesh 设置为 false。

仅当 should_remesh = true

Name
topology
Type
string
默认值 triangle
Description
指定生成模型的 topology。
可用值：
- quad：生成以四边形为主的 mesh。
- triangle：生成经过抽稀的三角形 mesh。
Name
decimation_mode
Type
integer
Description
通过设置一个 polycount 级别来启用自适应抽稀。设置后，target_polycount 将被忽略。
可用值：
- 1：自适应——超高 polycount。
- 2：自适应——高 polycount。
- 3：自适应——中等 polycount。
- 4：自适应——低 polycount。
Name
save_pre_remeshed_model
Type
boolean
默认值 false
Description
设置为 true 时，Meshy 还会在 remesh 阶段完成前存储一个额外的 GLB 文件。

Name
target_polycount
Type
integer
Description
输出中目标多边形（面）数量。实际数量可能会因 geometry 不同而偏离目标值。
target_polycount 在两种独立情况下生效：
- Remesh —— 在 standard 模型上设置 should_remesh: true。mesh 将被 remesh（抽稀）到大约该数量。范围为 100 到 300,000，默认值为 30,000。如果设置了 decimation_mode，则优先生效，target_polycount 将被忽略。
- Smart Topology —— 设置 model_type: smart-topology 和 ai_model: meshy-t2。模型将直接以该面数生成；不会运行 remesh，也无需设置 should_remesh。范围为 100 到 15,000，默认值为 4,000。

Name
symmetry_mode
Type
string
⚠ 已弃用
默认值 auto
Description
已 deprecated。此参数不再影响输出。
symmetry_mode 字段在模型生成过程中控制 symmetry 行为。
有效值为：
- off：禁用 symmetry。
- auto：根据输入 geometry 自动判定并应用 symmetry。
- on：在生成过程中强制应用 symmetry。
Name
pose_mode
Type
string
默认值 ""
Description
指定生成模型的姿势 mode。
可用值：
- a-pose：以 A 字姿势生成模型。
- t-pose：以 T 字姿势生成模型。
- ""（空字符串）：不应用特定姿势。
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、meshy-7 或 latest 时支持。
Name
remove_lighting
Type
boolean
默认值 true
Description
从基础颜色 texture 中移除高光和阴影，从而生成更干净的结果，在自定义灯光设置下效果更佳。
仅当 ai_model 为 meshy-6 时支持。
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，否则 origin 默认将为 bottom。
Name
alpha_thumbnail
Type
boolean
默认值 false
Description
设置为 true 时，任务会额外渲染一个透明背景（RGBA）版本的预览图，并在 GET 响应中以 alpha_thumbnail_url 返回。现有的 thumbnail_url 字段保持不变。
Name
multi_view_thumbnails
Type
boolean
默认值 false
Description
设置为 true 时，任务会额外渲染四个基本视角的缩略图（正面、右侧、背面、左侧），并在 GET 响应中通过 thumbnail_urls 返回。现有的 thumbnail_url 字段保持不变，仍指向正面视图，因此不会影响现有客户端。
会为任务延迟增加大约 3 秒。

仅当 auto_size = true

Name
origin_at
Type
string
默认值 bottom
Description
启用 auto_size 时 origin 的位置。
可用值：bottom、center。

返回值

响应中的 result 属性包含新创建的 Image to 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 或 timeout）。
- Data URI 无效：base64 字符串格式不正确。
- 参数组合无效：只有当 should_texture 为 true 时才支持 enable_pbr。
Name
401 - Unauthorized
Description
身份验证失败。请检查你的 API key。
Name
402 - Payment Required
Description
credits 不足，无法执行此任务。
Name
429 - Too Many Requests
Description
你已超出速率限制。

Request

POST

/openapi/v1/image-to-3d

# 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 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>",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/openapi/v1/image-to-3d/:id

获取 Image to 3D 任务

此 endpoint 允许你根据有效的任务 id 获取一个 Image to 3D 任务。请参阅 Image to 3D 任务对象以查看 Image to 3D 任务对象包含哪些属性。

参数

Name
id
Type
path
Description
要获取的 Image to 3D 任务的唯一标识符。

返回值

响应中包含 Image to 3D 任务对象。详情请参阅 Image to 3D 任务对象部分。

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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": {
    "message": ""
  },
  "consumed_credits": 30
}

DELETE/openapi/v1/image-to-3d/:id

删除一个 Image to 3D 任务

此 endpoint 会永久删除一个 Image to 3D 任务，包括所有相关的模型和数据。此操作不可逆。

路径参数

Name
id
Type
path
Description
要删除的 Image to 3D 任务的 ID。

返回值

成功时返回 200 OK。

Request

DELETE

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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

// Returns 200 Ok on success.

GET/openapi/v1/image-to-3d

列出 Image to 3D 任务

此 endpoint 允许您检索 Image to 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：按创建时间降序排序。

返回一个分页列表，包含 Image to 3D 任务对象。

Request

GET

/openapi/v1/image-to-3d

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": {
      "message": ""
    },
    "consumed_credits": 30
  }
]

GET/openapi/v1/image-to-3d/:id/stream

流式获取 Image to 3D 任务

此 endpoint 使用服务器发送事件（SSE）流式传输 Image to 3D 任务的实时更新。

参数

Name
id
Type
path
Description
要进行流式传输的 Image to 3D 任务的唯一标识符。

以服务器发送事件的形式返回一个 Image to 3D 任务对象的流。

对于 PENDING 或 IN_PROGRESS 状态的任务，响应流中只会包含必要的 progress 和 status 字段。

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

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.
// 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=***",
  "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": {
    "message": ""
  },
  "consumed_credits": 30
}

Image to 3D 任务对象

Image to 3D 任务对象是 Meshy 用来跟踪从图片输入生成 3D 模型的工作单元。该对象具有以下属性：

属性

Name
id
Type
string
Description
任务的唯一标识符。虽然我们在实现细节上使用 k-sortable UUID 作为任务 id，但你不应对 id 的格式做任何假设。
Name
type
Type
string
Description
Image to 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
  指向 MTL 文件的可下载 URL，当存在贴图时会随 OBJ 导出一起返回。
- Name
  stl
  Type
  string
  Description
  指向 STL 文件的可下载 URL。
- Name
  3mf
  Type
  string
  Description
  指向 3MF 文件的可下载 URL。仅当通过 target_formats 请求了 3mf 时才会出现。
- Name
  pre_remeshed_glb
  Type
  string
  Description
  指向重拓扑之前的原始 GLB 输出文件的可下载 URL。
  仅当任务创建时同时设置了 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 且透明预览图成功渲染时才会出现；否则会省略此字段。
Name
thumbnail_urls
Type
object
Description
生成的 3D 模型的四个主视角缩略图的可下载 URL。每个值都是一个指向 512×512 PNG 图片的签名 URL，该图片使用与 thumbnail_url 相同的材质和光照渲染而成。可用于在批处理流程中从多个角度预览模型，而无需下载 GLB。
仅当任务创建时设置了 multi_view_thumbnails: true 并且已达到 SUCCEEDED 状态时才会出现。较早的任务以及未启用该选项创建的任务将不包含此字段。
- 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
用于指导贴图处理过程的文本提示词。
Name
texture_image_url
Type
string
Description
指向用于指导贴图处理过程的贴图图片的可下载 URL。
Name
ultra_mode
Type
boolean
Description
回显任务创建时使用的 ultra_mode 值。仅当 meshy-7（或 latest）任务显式设置了 ultra_mode 时才会出现；否则会省略。
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 PM 表示为 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、meshy-7 或 latest，则会省略此属性。
Name
preceding_tasks
Type
integer
Description
排在此任务之前的任务数量。
此字段的值仅在任务状态为 PENDING 时才有意义。
Name
task_error
Type
object
Description
失败任务的错误详情。完整的 task_error 对象说明请参阅 Errors。
Name
consumed_credits
Type
integer
Description
此任务消耗的 credits 数量。当任务状态为 PENDING、IN_PROGRESS 或 SUCCEEDED 时会出现该字段。对于 FAILED 任务返回 0（失败时 credits 会被退还）。

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": {
    "message": ""
  },
  "consumed_credits": 30
}