Image to 3D API

将图像转换为 3D 模型，可选择是否带贴图，并可选择所需的格式。发送图像，或使用文字生成影像或影像生成影像任务的输出结果。

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

创建 Image to 3D 任务

创建一个 Image to 3D 任务。该任务在后台运行。有关任务通常需要多长时间，请参阅处理时间。

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 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"]
  }'

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。

Name
model_type
Type
string
默认值 standard
Description
要生成的 3D mesh 类型。
可用值：
- standard：高细节 mesh
- smart-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.1
- meshy-7.1
- meshy-6
- meshy-6-lite
- meshy-7（deprecated）：请改用 meshy-7.1
Smart Topology 模型（model_type: smart-topology）会生成三角形，面数可通过 target_polycount 设置：
- meshy-t2：更干净的 topology，且原生分离各部件
- meshy-t2.5（默认）：为游戏资产提供更锐利的细节
Name
geometry_resolution
Type
string
默认值 standard
Description
geometry 生成的处理阶段。
可用值：
- standard
- 2k：以 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 生成，返回不带 texture 的 mesh。

仅当 should_texture = true

Name
enable_pbr
Type
boolean
默认值 false
Description
除基础颜色外，是否同时生成 PBR 贴图（金属度、粗糙度和法线）。true 需要 should_texture: true，若 should_texture: false 则返回 400。
使用 meshy-6 时，Meshy 还会生成自发光贴图，但在 texture_resolution: 8k 时除外。以下模型不会生成自发光贴图：
- meshy-6-lite
- meshy-7
- meshy-7.1
- meshy-t2
- meshy-t2.5
- latest
Name
texture_resolution
Type
string
默认值 2k
Description
基础颜色 texture 的尺寸。更大的 texture 能捕捉更多表面细节。
可用值：
- 2k：2048×2048
- 4k：4096×4096
- 8k：8192×8192
4k 和 8k 不适用于 meshy-6-lite，使用时会返回 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。
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。
Meshy 只会使用 texture_prompt 和 texture_image_url 中的一个来指导 texture。如果两者都发送，Meshy 会使用 texture_prompt。有关 texture 生成的积分消耗，请参阅 Pricing。
当图像的形状与 3D 模型的 geometry 差异较大时，基于图像生成 texture 的效果可能不理想。

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：以四边形为主的 mesh
- triangle：经过减面处理的三角形 mesh
Smart Topology 的输出仅支持三角形，因此在使用 meshy-t2 或 meshy-t2.5 时设置 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 到 300000 30000
meshy-t2 100 到 15000 4000
meshy-t2.5 100 到 30000 15000
超出范围的值会返回 400。

情况	范围	默认值
Remesh	`100` 到 `300000`	`30000`
`meshy-t2`	`100` 到 `15000`	`4000`
`meshy-t2.5`	`100` 到 `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ 已弃用
默认值 auto
Description
请不要设置此项，因为它不会影响输出结果。其取值曾用于控制生成过程中的 symmetry：
- off：无 symmetry
- auto：根据输入 geometry 选择 symmetry
- on：强制 symmetry
Name
pose_mode
Type
string
默认值 ""
Description
生成模型的姿势。
可用值：
- a-pose：A 字形姿势
- t-pose：T 字形姿势
- ""（空字符串）：无特定姿势
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 下生效。meshy-7.1 和 latest 会接受但忽略该参数。若使用 meshy-6-lite 或 model_type: smart-topology，会返回 400。
Name
moderation
Type
boolean
默认值 false
Description
是否在生成前对以下输入进行有害内容审核：
- image_url
- texture_image_url
- texture_prompt
如果 Meshy 检测到有害内容，请求会返回 400，且 Meshy 不会创建任务。
Name
target_formats
Type
string[]
Description
要生成的文件格式。Meshy 只会生成并返回你所列出的格式，这可以缩短任务耗时。如果省略此项，Meshy 会生成除 3mf 之外的所有格式，只有在列出 3mf 时才会生成该格式。
可用值：
- glb
- obj
- fbx
- stl
- usdz
- 3mf
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。
- 无效的 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 或 remove_lighting。
修复请求后重新发送。请参阅 Errors。
Name
401 - Unauthorized
Description
API key 缺失或无效。请检查 Authorization 请求头。
Name
402 - Payment Required
Description
例如：
- 积分不足：账户没有足够的积分来执行此任务，或账户已达到积分上限。请检查你的积分 balance，然后重试。
- 免费计划：创建任务需要付费计划。请在订阅设置中升级你的计划，然后重试。
Name
404 - Not Found
Description
input_task_id 与你的任何任务都不匹配。请检查任务 ID，然后重新发送请求。
Name
429 - Too Many Requests
Description
你已超出速率限制。请稍候后重试。请参阅速率限制。

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

获取 Image to 3D 任务

根据 ID 返回一个 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
}

参数

Name
id
Type
path
Description
创建响应中的任务 ID。

返回值

Image to 3D 任务对象。

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

删除 Image to 3D 任务

永久删除一个 Image to 3D 任务，包括它的模型和数据。删除操作无法撤销。

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

// 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。

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

列出 Image to 3D 任务

返回你的 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
  }
]

参数

Name
page_num
Type
integer
默认值 1
Description
要返回的页码。页码从 1 开始。
Name
page_size
Type
integer
默认值 10
Description
每页的任务数量，最多为 100。
Name
sort_by
Type
string
Description
排序顺序。
可用值：
- +created_at：从最早开始
- -created_at：从最新开始

返回值

一个分页的 Image to 3D 任务对象列表。

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

流式获取 Image to 3D 任务

以 Server-Sent Events（SSE）的形式流式推送 Image to 3D 任务的更新。

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

参数

Name
id
Type
path
Description
创建响应中返回的任务 ID。

返回值

以 Server-Sent Events 形式返回的 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": {
    "message": ""
  },
  "consumed_credits": 30
}

Name
id
Type
string
Description
任务 ID。请将其视为不透明字符串，不要依赖其格式。
Name
type
Type
string
Description
任务类型，始终为 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
3D 模型预览图的下载 URL。当存在 thumbnail_urls 时，它与 thumbnail_urls.front 是同一张图像。Meshy 保留此字段是为了向后兼容。
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_url
Type
string
Description
用于指导 texture 的图像的下载 URL。
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
任务生成的纹理贴图，作为对象数组。通常包含一个对象，具有以下字段：
- 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 或 texture_resolution: 8k，或者 ai_model 为以下模型之一时，此字段不存在：
  
  meshy-6-lite
  
  meshy-7
  
  meshy-7.1
  
  meshy-t2
  
  meshy-t2.5
  
  latest
Name
preceding_tasks
Type
integer
Description
排在此任务之前的队列中任务数量。该值仅在任务处于 PENDING 状态时才有意义。
Name
task_error
Type
object
Description
任务失败时的错误详情。参见错误。
Name
consumed_credits
Type
integer
Description
任务消耗的积分数量。当状态为 PENDING、IN_PROGRESS 或 SUCCEEDED 时会出现。对于 FAILED 任务，该值为 0，因为 Meshy 会在任务失败时退还积分。