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

Text to 3D API

在你自己的应用程序中根据文本提示生成 3D 模型。

Text to 3D 分两步进行。首先,创建一个 preview 任务(mode: "preview")以生成不带 texture 的 3D mesh,这样你就可以检查其形状。然后,将成功的 preview 任务的任务 ID 发送给 refine 任务(mode: "refine"),为 mesh 添加 texture。这两个步骤使用相同的 endpoint。


POST/openapi/v2/text-to-3d

创建 Text to 3D preview 任务

创建一个 Text to 3D preview 任务,根据文本 prompt 生成一个未上贴图的 3D mesh(仅几何体)。这是两步工作流程的第一步。preview 成功后,将其任务 ID 发送到 refine 任务中,为 mesh 添加贴图。参见创建 Text to 3D refine 任务。完整的响应 schema 参见 Text to 3D 任务对象。

该任务在后台运行。关于任务通常耗时多久,参见处理时间。

Request

POST
/openapi/v2/text-to-3d
# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a monster mask"
}'

# Preview with Ultra 4K geometry, remesh, and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a futuristic robot warrior",
  "ai_model": "meshy-7.1",
  "geometry_resolution": "4k",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

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

参数

  • Name
    mode
    Type
    string
    必选
    Description

    两步工作流程的阶段。发送 preview 以创建一个 preview 任务。

  • Name
    prompt
    Type
    string
    必选
    Description

    描述要生成的对象的文本,最多 800 个字符。超出长度将返回 400。

  • Name
    model_type
    Type
    string
    默认值 standard
    Description

    要生成的 3D mesh 类型。

    可用取值:

    • standard:高细节 3D mesh
    • smart-topology:Smart Topology mesh。通过 ai_model(meshy-t2 或 meshy-t2.5)选择模型。

    使用 smart-topology 时,Meshy 会忽略 should_remesh 和 decimation_mode,并且只接受 topology: triangle。

  • Name
    ai_model
    Type
    string
    默认值 latest
    Description

    用于生成 3D 模型的 AI 模型。可用取值取决于 model_type。

    标准模型(model_type: standard):

    • meshy-6-lite
    • meshy-6
    • meshy-7.1
    • latest:Meshy 7.1
    • meshy-7(deprecated):请改为发送 meshy-7.1。该模型将于 2026 年 12 月 31 日下线。

    Smart Topology 模型(model_type: smart-topology):

    • meshy-t2:更干净的 topology、原生分离的部件、三角面输出,面数通过 target_polycount 设置
    • meshy-t2.5(默认):更适合游戏 asset 的更锐利细节、三角面输出,面数通过 target_polycount 设置

    关于哪种模型适合你的项目(例如游戏角色或 3D 打印),参见模型。

  • Name
    geometry_resolution
    Type
    string
    默认值 standard
    Description

    几何体生成的处理档位。仅适用于 preview 任务。在 refine 任务中使用此参数将返回 400。

    可用取值:

    • standard
    • 2k:以 2048³ 运行 Ultra 处理
    • 4k:以 4096³ 运行 Ultra 处理,获得更精细的表面细节

    2k 需要 meshy-7.1、latest 或已 deprecated 的 meshy-7。4k 需要 meshy-7.1 或 latest。其他模型将返回 400。

  • Name
    ultra_mode
    Type
    boolean
    ⚠ 已弃用
    默认值 false
    Description

    请改为发送 geometry_resolution。ultra_mode: true 等同于 geometry_resolution: "2k"。

  • 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 的输出仅支持三角面。若 ai_model 为 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
    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 模型,而不是对 standard 模型进行 remesh。参见模型。

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

    请勿使用此参数。它不会影响输出结果。

    可用取值:

    • 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 pose 或 T pose 生成模型。

  • Name
    art_style
    Type
    string
    ⚠ 已弃用
    默认值 realistic
    Description

    请勿使用此参数。Meshy 会忽略它。

  • Name
    moderation
    Type
    boolean
    默认值 false
    Description

    是否在生成前对 prompt 进行有害内容筛查。如果 Meshy 检测到有害内容,该请求将返回 400,且 Meshy 不会创建任务。

  • Name
    target_formats
    Type
    string[]
    Description

    要生成的文件格式。Meshy 只生成并返回这些格式,这可以缩短任务耗时。如果不设置该参数,Meshy 会生成除 3mf 之外的所有格式,3mf 只有在你请求时才会生成。

    可用取值:

    • glb
    • obj
    • fbx
    • stl
    • usdz
    • 3mf
  • Name
    alpha_thumbnail
    Type
    boolean
    默认值 false
    Description

    是否同时渲染一张带透明背景(RGBA)的预览图,获取任务时会在 alpha_thumbnail_url 中返回。thumbnail_url 不会改变。

  • Name
    auto_size
    Type
    boolean
    默认值 false
    Description

    是否使用 AI 视觉估算对象的真实世界高度,并据此调整模型尺寸。除非你设置了 origin_at,否则 Meshy 会将 origin 放在底部。

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

    将模型的 origin 放在哪里,bottom 或 center。

返回值

响应中的 result 字段包含新建的 Text to 3D 任务的 ID。

失败情形

  • Name
    400 - Bad Request
    Description

    请求无法运行。错误消息会说明发现了什么问题。例如:

    • 缺少参数:缺少必填参数,例如 prompt 或 mode。
    • Prompt 过长:prompt 超过了字符数限制。
    • Ultra 不支持该模型:geometry_resolution 为 2k 或 4k,但所用的 ai_model 不支持运行它。

    修正请求后重新发送。参见 Errors。

  • Name
    401 - Unauthorized
    Description

    API key 缺失或无效。请检查 Authorization 请求头。

  • Name
    402 - Payment Required
    Description

    例如:

    • 积分不足:账户没有足够的积分来完成此任务,或账户已达到积分限制。请检查你的积分 balance,然后重试。
    • 免费套餐:创建任务需要付费套餐。请在订阅设置中升级你的套餐,然后重试。
  • Name
    403 - Forbidden
    Description

    内容审核拦截了该 prompt 或输入图像。请更改输入内容后重试。

  • Name
    429 - Too Many Requests
    Description

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


POST/openapi/v2/text-to-3d

创建 Text to 3D refine 任务

创建一个 Text to 3D refine 任务,为已完成的 preview 任务的 mesh 添加 texture。将成功的 preview 任务的 ID 作为 preview_task_id 发送。参见创建 Text to 3D preview 任务。这是两步工作流程的第二步。

任务在后台运行。关于任务通常需要多长时间,请参见处理时间。

Request

POST
/openapi/v2/text-to-3d
# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "enable_pbr": true
}'

# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "target_formats": ["glb"],
  "auto_size": true
}'

# Refine with Meshy N1 from the preview's stored reference image
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "ai_model": "meshy-n1"
}'

Response

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

参数

  • Name
    mode
    Type
    string
    必选
    Description

    两步工作流程中的步骤。发送 refine 以创建 refine 任务。

  • Name
    preview_task_id
    Type
    string
    必选
    Description

    要添加 texture 的 preview 任务的 ID。该 preview 任务的状态必须为 SUCCEEDED。

  • Name
    enable_pbr
    Type
    boolean
    默认值 false
    Description

    是否在生成基础颜色贴图的同时也生成 PBR 贴图(金属度、粗糙度和法线)。

    在 ai_model 为 meshy-6 时,Meshy 还会生成一张 emission 贴图,但 texture_resolution: 8k 时除外。meshy-6-lite、meshy-7 和 latest 不会生成 emission 贴图。未设置 ai_model 的 meshy-t2 或 meshy-t2.5 preview 的 refine 同样不会生成。使用 ai_model: meshy-n1 时,设为 true 会返回 400。

  • Name
    texture_resolution
    Type
    string
    默认值 2k
    Description

    基础颜色 texture 的分辨率。仅适用于 refine 任务。若在 preview 中发送此 parameter 会返回 400。

    可用值:

    • 2k:2048×2048
    • 4k:4096×4096
    • 8k:8192×8192

    更高的分辨率可以捕捉更多表面细节。4k 和 8k 需要 ai_model 为 meshy-6、meshy-7 或 latest。使用 meshy-n1 时会返回 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_prompt 或 texture_image_url,不要两者都发送。如果两者都发送,Meshy 会使用 texture_prompt。使用 ai_model: meshy-n1 时发送此参数会返回 400。

  • Name
    texture_image_url
    Type
    string
    Description

    用于指导 texture 生成的 2D 图片,可以是公开 URL 或 base64 编码的 data URI,例如 data:image/jpeg;base64,<your base64-encoded image data>。

    图片必须是 .jpg、.jpeg、.png 或 .webp 文件,大小不超过 20 MB,每边至少 32 像素,且不超过 178,956,970 像素(宽 × 高)。

    使用 ai_model: meshy-n1 时,Meshy 会将该图片作为正视图来生成 texture。

  • Name
    ai_model
    Type
    string
    默认值 inherited from the preview task
    Description

    用于为 mesh 添加 texture 的 AI 模型。mesh 来自 preview,因此在 refine 时 ai_model 仅选择 texture 模型。

    可用值:

    • meshy-7:Meshy 7
    • latest:最新的 texture 模型,目前为 Meshy 7
    • meshy-6:Meshy 6
    • meshy-6-lite:Meshy 6 Lite
    • meshy-n1:仅根据参考图片生成 2K 基础颜色 texture。没有文本 prompt,没有 PBR 贴图,也没有 4K 或 8K。

    以上值均为 texture 模型。留空则使用与 preview 相匹配的模型来生成 texture。发送一个值可覆盖该默认模型。

    使用 meshy-n1 时,Meshy 会根据 texture_image_url 生成 texture。如果未提供该参数,Meshy 会使用 meshy-7.1 或 latest preview 存储的参考图片。其他任何 preview 若未发送 texture_image_url 都会返回 400。该 preview 最多可包含 7,999,999 个三角形。remesh 为四边面(quad)的 preview 会返回 400。

  • Name
    moderation
    Type
    boolean
    默认值 false
    Description

    是否在生成之前对 texture_prompt 和 texture_image_url 进行有害内容审查。如果 Meshy 检测到有害内容,请求将返回 400,且 Meshy 不会创建任务。

  • Name
    remove_lighting
    Type
    boolean
    默认值 true
    Description

    是否从基础颜色 texture 中移除高光和阴影。更干净的结果在自定义光照下效果更好。

    仅当 ai_model 为 meshy-6 时生效。meshy-7 和 latest 接受此参数但会忽略它,未设置 ai_model 的 meshy-t2 或 meshy-t2.5 preview 的 refine 同样如此。在 meshy-6-lite 中发送此参数会返回 400。使用 meshy-n1 时,设为 true 会返回 400。

  • Name
    target_formats
    Type
    string[]
    Description

    要生成的文件格式。Meshy 仅生成并返回这些格式,这样可以缩短任务时间。如果留空,Meshy 会生成除 3mf 之外的所有格式,3mf 仅在你请求时才会生成。

    可用值:

    • glb
    • obj
    • fbx
    • stl
    • usdz
    • 3mf
  • Name
    alpha_thumbnail
    Type
    boolean
    默认值 false
    Description

    是否同时渲染一张带透明背景(RGBA)的预览图,在获取任务时通过 alpha_thumbnail_url 返回。thumbnail_url 不会改变。

  • Name
    auto_size
    Type
    boolean
    默认值 false
    Description

    是否使用 AI 视觉估算物体的真实世界高度,并将模型调整为该尺寸。除非设置了 origin_at,否则 Meshy 会将 origin 置于底部。

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

    模型 origin 的位置,bottom 或 center。

返回内容

响应的 result 字段保存新 Text to 3D 任务的 ID。

失败模式

  • Name
    400 - Bad Request
    Description

    请求无法运行。错误消息会说明发现了什么问题。例如:

    • Invalid task ID:preview_task_id 无效,或与你的任何 preview 任务都不匹配。
    • Task not ready:该 preview 任务尚未成功。
    • Model mismatch:该 preview 任务的 AI 模型与请求的 refine 模型不兼容。
    • Unsupported model for remove_lighting:remove_lighting 与 ai_model: "meshy-6-lite" 一起发送。
    • No reference image for Meshy N1:发送了 ai_model: meshy-n1 但未提供 texture_image_url,且该 preview 没有 Meshy N1 可使用的参考图片。请发送 texture_image_url。
    • Quad preview for Meshy N1:针对 remesh 为四边面(quad)的 preview 发送了 ai_model: meshy-n1。请使用其他 ai_model 进行 refine。
    • Too many triangles for Meshy N1:在 ai_model: meshy-n1 下,该 preview 的三角形数量超过了 7,999,999。请使用其他 ai_model 进行 refine。
    • Unsupported option for Meshy N1:ai_model: meshy-n1 与以下某个选项一起发送:
      • texture_prompt
      • enable_pbr: true
      • texture_resolution 为 4k 或 8k
      • 未设置 texture_resolution 的 hd_texture: true
      • remove_lighting: true

    修正请求后重新发送。参见 Errors。

  • Name
    401 - Unauthorized
    Description

    API key 缺失或无效。请检查 Authorization 请求头。

  • Name
    402 - Payment Required
    Description

    例如:

    • Insufficient credits:账户没有足够的积分来完成该任务,或账户已达到积分限额。请检查你的 balance,然后重试。
    • Free plan:创建任务需要付费计划。请在subscription 设置中升级你的计划,然后重试。
  • Name
    403 - Forbidden
    Description

    内容审查拦截了该 prompt 或某张输入图片。请更改输入内容后重试。

  • Name
    429 - Too Many Requests
    Description

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


GET/openapi/v2/text-to-3d/:id

获取 Text to 3D 任务

根据任务 ID 返回对应的 Text to 3D 任务。该接口同时适用于 preview 和 refine 任务。

Request

GET
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?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=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 20
}

参数

  • Name
    id
    Type
    path
    Description

    创建响应中返回的任务 ID。

返回值

Text to 3D 任务对象。

示例

下表展示了每种 mode 下的示例模型。

Mode示例模型
PreviewPreview model
RefineRefined model

DELETE/openapi/v2/text-to-3d/:id

删除一个 Text to 3D 任务

永久删除一个 Text to 3D 任务,包括其模型和数据。删除操作无法撤销。

Request

DELETE
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v2/text-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/v2/text-to-3d

获取 Text to 3D 任务列表

返回您的 Text to 3D 任务列表。

Request

GET
/openapi/v2/text-to-3d
curl https://api.meshy.ai/openapi/v2/text-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-3d-preview",
    "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=***",
      "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "prompt": "a monster mask",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
      }
    ],
    "preceding_tasks": 0,
    "task_error": null,

    "consumed_credits": 20
  }
]

参数

  • 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:最新的在前

返回值

分页的 Text to 3D 任务对象列表。


GET/openapi/v2/text-to-3d/:id/stream

流式获取 Text to 3D 任务

以服务器发送事件(SSE)的形式流式推送 Text to 3D 任务的更新。

Request

GET
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v2/text-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",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"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": 20
}

参数

  • Name
    id
    Type
    path
    Description

    来自创建响应的任务 ID。

返回值

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

每个事件都包含完整的任务对象,其结构与 Get endpoint 返回的内容相同。当任务处于 PENDING 或 IN_PROGRESS 状态时,其结果字段尚无值。


Text to 3D 任务对象

Text to 3D 任务对象描述了一个根据文本 prompt 生成 3D 模型的任务。它保存了任务的状态、progress,以及任务成功后的模型文件。Text to 3D 有两个阶段,preview 和 refine。preview 任务生成仅含 mesh 的 3D 模型,refine 任务则根据 preview 的结果生成带贴图的 3D 模型。

属性

Example Text to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "prompt": "a monster mask",
  "texture_prompt": "green slimy skin with scales and warts",
  "texture_image_url": "",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "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": 20
}
  • Name
    id
    Type
    string
    Description

    任务 ID。请将其视为一个不透明的字符串,不要依赖其格式。

  • Name
    type
    Type
    string
    Description

    任务类型,text-to-3d-preview 表示 preview 任务,text-to-3d-refine 表示 refine 任务。

  • Name
    model_urls
    Type
    object
    Description

    生成的 3D 模型的下载 URL,每种文件格式对应一个。任务未生成的格式不会有对应的键,而不是空字符串。

    • Name
      glb
      Type
      string
      Description

      GLB 文件。

    • Name
      fbx
      Type
      string
      Description

      FBX 文件。

    • Name
      usdz
      Type
      string
      Description

      USDZ 文件。

    • Name
      obj
      Type
      string
      Description

      OBJ 文件。

    • Name
      mtl
      Type
      string
      Description

      MTL 文件。

    • Name
      stl
      Type
      string
      Description

      STL 文件。

    • Name
      3mf
      Type
      string
      Description

      3MF 文件。仅当 target_formats 包含 3mf 时才会出现。

  • Name
    prompt
    Type
    string
    Description

    你在创建任务时发送的 prompt,未经修改。

  • Name
    texture_prompt
    Type
    string
    Description

    你发送的、用于指导 refine 阶段贴图的文本 prompt。

  • Name
    ultra_mode
    Type
    boolean
    ⚠ 已弃用
    Description

    请改为读取 geometry_resolution。

  • Name
    geometry_resolution
    Type
    string
    Description

    preview 任务所使用的 Ultra 档位,2k 或 4k。standard 档位下不包含该字段。

  • Name
    texture_image_url
    Type
    string
    Description

    你发送的、用于指导贴图的图片的下载 URL。

  • Name
    thumbnail_url
    Type
    string
    Description

    3D 模型缩略图的下载 URL。

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    thumbnail_url 的透明背景版本(RGBA)的下载 URL。仅当你在创建任务时设置了 alpha_thumbnail: true,并且 Meshy 已渲染出透明预览图时才会出现。

  • Name
    progress
    Type
    integer
    Description

    任务完成的百分比。任务开始前为 0,成功后为 100。

  • Name
    started_at
    Type
    timestamp
    Description

    任务开始的时间,以 Unix 毫秒表示。任务开始前为 0。

  • Name
    created_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 贴图的下载 URL,为一个对象数组。通常只包含一个对象。每个对象包含以下字段:

    • 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

      自发光贴图。在以下任一情况下都不会出现:

      • 你在创建任务时设置了 enable_pbr: false。
      • ai_model 为 meshy-6-lite、meshy-7、meshy-7.1 或 latest。
      • texture_resolution 为 8k。
      • 该任务是在未设置 ai_model 的情况下,对 meshy-t2 或 meshy-t2.5 的 preview 进行 refine。
  • 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 会在任务失败时退还积分。