图像转3D API

图像转3D API 是一项功能,允许您将 Meshy 的图像转3D能力集成到您自己的应用程序中。在本节中,您将找到开始使用此API所需的所有信息。


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

创建图像转3D任务

此端点允许您创建一个新的图像转3D任务。请参阅图像转3D任务对象以查看图像转3D任务对象包含哪些属性。

参数

  • 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:生成优化后多边形更简洁的低面数网格。
  • Name
    ai_model
    Type
    string
    默认值 latest
    Description

    要使用的模型ID。可选值:meshy-5meshy-6latest(Meshy 6)。

  • Name
    should_texture
    Type
    boolean
    默认值 true
    Description

    决定是否生成贴图。设置为 false 时跳过贴图阶段,仅生成网格。

仅当 should_texture = true
  • Name
    enable_pbr
    Type
    boolean
    默认值 false
    Description

    生成 PBR 贴图(金属度、粗糙度、法线)以及基础色。当 ai_modelmeshy-6latest 时,还会额外生成自发光贴图。

  • Name
    hd_texture
    Type
    boolean
    默认值 false
    Description

    以 4K(4096×4096)分辨率生成基础色贴图,获得更高细节。

  • 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>
  • 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 时,模型将忠实还原输入图像的原始外观,不进行任何风格处理。

  • Name
    remove_lighting
    Type
    boolean
    默认值 true
    Description

    移除基础色贴图中的高光和阴影,生成更纯净的效果,在自定义光照设置下表现更佳。

  • Name
    moderation
    Type
    boolean
    默认值 false
    Description

    当设置为 true 时,输入内容将自动进行潜在有害内容筛查。如果检测到有害内容,任务将不会进入生成阶段。

    image_urltexture_image_urltexture_prompt 的内容都将被筛查。

  • Name
    target_formats
    Type
    string[]
    Description

    指定输出中包含的 3D 文件格式。仅会生成并返回所请求的格式,可减少任务完成时间。省略时,将包含所有支持的格式。

    可选值:glbobjfbxstlusdz3mf

  • Name
    auto_size
    Type
    boolean
    默认值 false
    Description

    当设置为 true 时,服务使用 AI 视觉自动估算物体的真实高度并相应调整模型大小。除非显式设置了 origin_at,否则原点将默认为 bottom

仅当 auto_size = true
  • Name
    origin_at
    Type
    string
    默认值 bottom
    Description

    auto_size 启用时的原点位置。

    可选值:bottomcenter

返回值

响应的result字段包含新建图像转3D任务的任务id

失败模式

  • Name
    400 - Bad Request
    Description

    请求不合法。常见原因:

    • 缺少参数:必须提供 image_urlinput_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

    您已超出请求频率限制。

请求

POST
/openapi/v1/image-to-3d
# 仅使用必需参数的简单请求
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"
}

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

获取图像转3D任务

此端点允许您通过有效的任务id获取图像转3D任务。请参阅图像转3D任务对象以查看图像转3D任务对象包含哪些属性。

参数

  • Name
    id
    Type
    path
    Description

    要获取的图像转3D任务的唯一标识符。

返回值

响应包含图像转3D任务对象。详情请查阅图像转3D任务对象部分。

请求

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

响应

{
  "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
}

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

删除图像转3D任务

此端点将永久删除一个图像转3D任务,包括所有相关的模型和数据。此操作不可逆。

路径参数

  • Name
    id
    Type
    path
    Description

    要删除的图像转3D任务的ID。

返回值

成功则返回 200 OK

请求

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

响应

// 成功则返回 200 Ok。

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

获取图像生成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任务对象列表。

请求

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

响应

[
  {
    "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
  }
]

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

流式图像转3D任务

此端点通过Server-Sent Events (SSE)流式返回图像转3D任务的实时进度更新。

参数

  • Name
    id
    Type
    path
    Description

    要流式获取的图像转3D任务的唯一标识符。

返回值

返回图像转3D任务对象的流式Server-Sent Events。

对于PENDINGIN_PROGRESS状态的任务,响应流仅包含必要的progressstatus字段。

请求

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

响应流

// 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下载链接。

  • 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

  • Name
    created_at
    Type
    timestamp
    Description

    任务创建的时间戳(毫秒)。

  • Name
    expires_at
    Type
    timestamp
    Description

    任务结果过期的时间戳(毫秒)。

  • Name
    finished_at
    Type
    timestamp
    Description

    任务完成的时间戳(毫秒)。如果任务尚未完成,该属性为0

  • Name
    status
    Type
    string
    Description

    任务状态。可能的值有PENDINGIN_PROGRESSSUCCEEDEDFAILEDCANCELED

  • Name
    texture_urls
    Type
    array
    Description

    任务生成的贴图URL对象数组。通常只包含一个贴图URL对象。每个贴图URL包含以下属性:

    • Name
      base_color
      Type
      string
      Description

      基础色贴图的可下载URL。

    • Name
      metallic
      Type
      string
      Description

      金属度贴图的可下载URL。

    • Name
      normal
      Type
      string
      Description

      法线贴图的可下载URL。

    • Name
      roughness
      Type
      string
      Description

      粗糙度贴图的可下载URL。

    • Name
      emission
      Type
      string
      Description

      自发光贴图的可下载URL。

  • Name
    preceding_tasks
    Type
    integer
    Description

    前置任务数量。

  • Name
    task_error
    Type
    object
    Description

    错误对象,包含任务失败时的错误信息。如果任务成功,message应为空。详情请参阅 Errors

    • Name
      message
      Type
      string
      Description

      详细错误信息。

  • Name
    consumed_credits
    Type
    integer
    Description

    该任务消耗的积分数。当任务状态为 PENDINGIN_PROGRESSSUCCEEDED 时返回。对于 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,
}