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 生成不带 texture 的 3D mesh（仅 geometry）。这是两步工作流程的第一步。preview 成功后，将其任务 ID 发送到 refine 任务中，为 mesh 添加 texture。参见创建 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
Smart Topology 模型（model_type: smart-topology）：
- meshy-t2：topology 更清晰、原生分离部件、输出为三角面，面数由 target_polycount 设置
- meshy-t2.5（默认）：游戏资产细节更锐利，输出为三角面，面数由 target_polycount 设置
Name
geometry_resolution
Type
string
默认值 standard
Description
geometry 生成的处理等级。仅适用于 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
remesh 后模型的面类型。
可选值：
- 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 remesh（简化）到接近该数值。如果你设置了 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
请省略该参数。它不会影响输出结果。
可选值：
- 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
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
例如：
- 积分不足：账户没有足够的积分来执行此任务，或账户已达到积分限制。请检查你的积分余额，然后重试。
- 免费方案：创建任务需要付费方案。请在你的subscription 设置中升级方案，然后重试。
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
}'

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、meshy-7.1 和 latest 不会生成 emission 贴图。对未设置 ai_model 的 meshy-t2 或 meshy-t2.5 preview 进行 refine 时也不会生成。
Name
texture_resolution
Type
string
默认值 2k
Description
基础颜色 texture 的分辨率。仅适用于 refine 任务。若 preview 任务发送此参数，将返回 400。
可用值：
- 2k：2048×2048
- 4k：4096×4096
- 8k：8192×8192
更高的分辨率能呈现更多表面细节。4k 和 8k 需要 ai_model 为 meshy-6、meshy-7.1 或 latest。在 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。
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。
当图片中的形状与模型差异较大时，基于图片的 texture 生成可能效果不佳。
Name
ai_model
Type
string
默认值 inherited from the preview task
Description
用于对 mesh 进行 texture 处理的 AI 模型。
可用值：
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest：Meshy 7.1
- meshy-7（deprecated）：请改为发送 meshy-7.1
不填写时将使用该 preview 任务所用的模型，使 preview 及其 refine 从头到尾使用同一模型。发送某个值即可覆盖该设置。显式发送 latest 的解析方式与在 preview 任务中相同，因此 latest 的 preview 与其 latest 的 refine 始终使用同一个 texture 模型。
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.1 和 latest 虽接受该参数但会忽略它，对未设置 ai_model 的 meshy-t2 或 meshy-t2.5 preview 进行 refine 时同样会忽略。与 meshy-6-lite 一起发送将返回 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"。
修正请求后重新发送。参见 Errors。
Name
401 - Unauthorized
Description
API key 缺失或无效。请检查 Authorization 请求头。
Name
402 - Payment Required
Description
例如：
- 积分不足：账户没有足够的积分来执行此任务，或账户已达到积分限额。请检查你的积分余额，然后重试。
- Free plan：创建任务需要付费计划。请在你的订阅设置中升级你的计划，然后重试。
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": {

    "message": ""

  },

  "consumed_credits": 20
}

参数

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

返回值

Text to 3D 任务对象。

示例

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

Mode	示例模型
Preview
Refine

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

      "message": ""

    },

    "consumed_credits": 20
  }
]

参数

Name
page_num
Type
integer
默认值 1
Description
要返回的页码。
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": {

  "message": ""

},

"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 的结果生成带 texture 的 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": {

    "message": ""

  },

  "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 阶段指导 texture 生成的文本 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
你发送的、用于指导 texture 生成的图片的下载 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
video_url
Type
string
⚠ 已弃用
Description
请不要依赖此字段，因为未来版本会将其移除。预览视频的下载 URL。
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
任务失败时的错误详情。参见错误。
Name
consumed_credits
Type
integer
Description
该任务消耗的积分数量。当状态为 PENDING、IN_PROGRESS 或 SUCCEEDED 时会出现。对于 FAILED 的任务，该值为 0，因为 Meshy 会在任务失败时退还积分。