lowpoly 将于 2026年10月30日 下线。 meshy-7 作为 3D 生成模型将于 2026年12月31日 下线;作为贴图模型仍可使用。 请在这些日期前切换模型,以免请求报错。 查看所有弃用信息

Image to 3D API

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


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

Create an Image to 3D task

创建一个 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"]
  }'

# 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:高细节 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。该模型将于 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 生成的处理阶段。

    可用值:

    • 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 的 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 最高可达 8K
    • meshy-n1:Meshy N1,仅根据参考图生成 2K 基础色 texture
    • meshy-6-lite:Meshy 6 Lite,以最低成本生成 2K texture
    • meshy-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×2048
    • 4k:4096×4096
    • 8k: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 会将该图片作为正面视图进行贴图;如果留空,则使用输入图片。

  • 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。使用 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。

    取值范围和默认值取决于具体情况:

    情况范围默认值
    Remesh100 至 30000030000
    meshy-t2100 至 150004000
    meshy-t2.5100 至 3000015000

    超出范围的值会返回 400。

    对于 low-poly 游戏 asset,建议使用 Smart Topology 模型,而不是对标准模型进行 remesh。请参阅模型。

  • Name
    symmetry_mode
    Type
    string
    ⚠ 已弃用
    默认值 auto
    Description

    请将此项留空,因为它不会影响输出。该参数原本用于控制生成过程中的 symmetry:

    • off:无 symmetry
    • auto:根据输入 geometry 选择 symmetry
    • on:强制 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_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。
    • 图片尺寸无效: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 下使用 4k texture。请参阅模型。

    请修正请求后重新发送。参阅 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

    你已超出速率限制。请稍候后重试。参阅速率限制。


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": null,
  "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": 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 任务对象列表。


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

流式获取 Image to 3D 任务

以服务器发送事件(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": 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: true
      • texture_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 会在任务失败时退还积分。