Text to 3D API

Text to 3D API 是一项功能，可让你将 Meshy 的 Text to 3D 能力集成到自己的应用程序中。在本节中，你将找到开始使用此 API 所需的全部信息。

Text to 3D 采用两步工作流程。首先，创建一个 预览（preview） 任务（mode: "preview"），生成不带 texture 的 3D mesh，以便你评估其形状。然后，将已完成的预览任务的任务 ID 传入 refine 任务（mode: "refine"），为该 mesh 应用 texture。这两个步骤共用同一个 endpoint。

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

创建 Text to 3D 预览任务

此 endpoint 用于创建一个 Text to 3D 预览任务，根据文本 prompt 生成不带纹理的 3D mesh（仅 geometry）。这是两步工作流程的第一步。预览成功后，可使用返回的任务 ID 创建 refine 任务进行贴图处理。完整的响应结构请参考 Text to 3D 任务对象。

参数

Name
mode
Type
string
必选
Description
创建预览任务时，此字段应设置为 "preview"。
Name
prompt
Type
string
必选
Description
描述该 3D 模型是什么类型的物体。最多 800 个字符。
Name
model_type
Type
string
默认值 standard
Description
指定 3D mesh 生成的类型。
可用取值：
- standard：常规的高细节 3D mesh 生成。
- smart-topology：通过 ai_model（meshy-t2）选择 Smart Topology 模型。
- lowpoly（deprecated）：生成经过优化、多边形更简洁的 low-poly mesh。我们建议改用 smart-topology。
选择 smart-topology 时，should_remesh 和 decimation_mode 会被忽略，且仅接受 topology: triangle。
选择 lowpoly 时，ai_model、topology、target_polycount 和 should_remesh 会被忽略。
Name
ai_model
Type
string
默认值 latest
Description
要使用的模型 ID。可用取值取决于 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（默认）：Smart Topology 模型 —— 拥有更简洁的 topology、原生分离的部件、triangle 输出，并可通过 target_polycount 设置面数。
Name
geometry_resolution
Type
string
默认值 standard
Description
geometry 生成阶段。2k 以 2048³ 运行 Ultra 阶段；4k 以 4096³ 运行，以获得最精细的表面细节。
可用取值：standard、2k、4k
仅在 preview mode 下支持。需要 meshy-7.1 或 latest。
Name
ultra_mode
Type
boolean
⚠ 已弃用
默认值 false
Description
请改用 geometry_resolution。ultra_mode: true 等同于 geometry_resolution: "2k"。
Name
should_remesh
Type
boolean
默认值 false (Meshy 6 and Meshy 7 models), true (others)
Description
控制是否启用 remesh 阶段。对于最高质量的模型，我们建议将 should_remesh 设置为 false。

仅当 should_remesh = true

Name
topology
Type
string
默认值 triangle
Description
指定生成模型的 topology。
可用取值：
- quad：生成以四边形为主的 mesh。
- triangle：生成经过精简的三角形 mesh。
Smart Topology 的输出仅支持 triangle。若同时使用 quad 和 ai_model: meshy-t2 会返回错误。
Name
decimation_mode
Type
integer
Description
通过设置 polycount 级别来启用自适应精简。设置后，target_polycount 会被忽略。
可用取值：
- 1：自适应 —— 超高 polycount。
- 2：自适应 —— 高 polycount。
- 3：自适应 —— 中等 polycount。
- 4：自适应 —— 低 polycount。

Name
target_polycount
Type
integer
Description
输出结果中目标多边形（面）数量。实际数量可能会因 geometry 的不同而与目标值有所偏差。
target_polycount 在两种独立情况下生效：
- Remesh —— 在 standard 模型上设置 should_remesh: true。mesh 会被 remesh（精简）到大约这个数量。范围为 100 到 300,000，默认 30,000。若设置了 decimation_mode，则以它为准，target_polycount 会被忽略。
- Smart Topology —— 使用 model_type: smart-topology 和 ai_model: meshy-t2。模型会直接以此面数生成；不会运行 remesh，也无需设置 should_remesh。范围为 100 到 15,000，默认 4,000。

Name
symmetry_mode
Type
string
⚠ 已弃用
默认值 auto
Description
已 deprecated。此参数不再影响输出。
symmetry_mode 字段用于控制模型生成过程中的 symmetry 行为。
有效取值为：
- off：禁用 symmetry。
- auto：根据输入 geometry 自动判断并应用 symmetry。
- on：在生成过程中强制使用 symmetry。
Name
pose_mode
Type
string
默认值 ""
Description
指定生成模型的姿势 mode。
可用取值：
- 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-6 不支持此参数。使用 Meshy-6 的请求会忽略 art_style，且某些组合可能导致错误。可用取值：realistic、sculpture。
使用 Sculpture 风格时应将 enable_pbr 设置为 false，因为 Sculpture 风格会生成其自己的一套 PBR 贴图。
Name
moderation
Type
boolean
默认值 false
Description
设置为 true 时，系统会自动对输入内容进行潜在有害内容的筛查。如检测到有害内容，任务将不会进入生成阶段。
prompt 中的文本将被筛查。
Name
target_formats
Type
string[]
Description
指定输出中要包含的 3D 文件格式。仅会生成并返回所请求的格式，这可以缩短任务完成时间。若省略此参数，则包含所有支持的格式。
可用取值：glb、obj、fbx、stl、usdz、3mf
若省略此参数，除 3mf 外的所有格式都会生成。3mf 仅在明确指定时才会包含。
Name
alpha_thumbnail
Type
boolean
默认值 false
Description
设置为 true 时，任务会额外渲染一个透明背景（RGBA）版本的预览图，并在 GET 响应中以 alpha_thumbnail_url 返回。现有的 thumbnail_url 字段保持不变。
Name
auto_size
Type
boolean
默认值 false
Description
设置为 true 时，服务会使用 AI 视觉自动估算物体的真实世界高度，并相应地调整模型尺寸。除非显式设置 origin_at，否则 origin 默认为 bottom。

仅当 auto_size = true

Name
origin_at
Type
string
默认值 bottom
Description
启用 auto_size 时 origin 的位置。
可用取值：bottom、center。

返回值

响应中的 result 属性包含新创建的 Text to 3D 任务的任务 id。

失败模式

Name
400 - Bad Request
Description
请求不可接受。常见原因包括：
- 缺少参数：缺少必需参数（例如 prompt、mode）。
- 参数无效：art_style 不是允许的取值之一。
- prompt 过长：prompt 超出字符限制。
- 模型不支持 low poly：ai_model: "meshy-6-lite" 不支持 model_type: "lowpoly"。
- 模型不支持 Ultra：geometry_resolution 需要 meshy-7.1 或 latest。
Name
401 - Unauthorized
Description
Authentication 失败。请检查你的 API key。
Name
402 - Payment Required
Description
credits 不足，无法执行此任务。
Name
429 - Too Many Requests
Description
你已超出速率限制。

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

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

创建 Text to 3D Refine 任务

此 endpoint 用于创建一个 Text to 3D refine 任务，该任务会为已完成的预览 mesh 应用 texture。您必须提供来自成功的预览任务的 preview_task_id。这是两步工作流程中的第二步。

参数

Name
mode
Type
string
必选
Description
创建 refine 任务时，此字段应设置为 "refine"。
Name
preview_task_id
Type
string
必选
Description
对应的预览任务 id。
给定预览任务的状态必须为 SUCCEEDED。
Name
enable_pbr
Type
boolean
默认值 false
Description
除基础颜色外，还生成 PBR 贴图（metallic、roughness、normal）。当 ai_model 为 meshy-6 时也会包含 emission map，但在 texture_resolution: 8k 时不会生成 emission map。meshy-6-lite、meshy-7.1 和 latest 不会生成 emission map。
Name
texture_resolution
Type
string
默认值 2k
Description
基础颜色 texture 分辨率。可选值为 2k（2048×2048）、4k（4096×4096）或 8k（8192×8192）。分辨率越高，捕捉到的表面细节越多。仅适用于 refine mode。
4k 和 8k 需要 ai_model 为 meshy-6、meshy-7.1 或 latest。在 8k 时，不会生成 emission map。
Name
hd_texture
Type
boolean
⚠ 已弃用
默认值 false
Description
请改用 texture_resolution —— 相当于 texture_resolution: "4k"。当两者都设置时，texture_resolution 优先生效。
Name
texture_prompt
Type
string
Description
提供额外的文本 prompt 以指导 texture 生成过程。最多 800 个字符。
Name
texture_image_url
Type
string
Description
提供一张 2D 图片以指导 texture 生成过程。目前支持 .jpg、.jpeg 和 .png 格式。
提供图片的方式有两种：
- 公开可访问的 URL：可从公共互联网访问的 URL
- Data URI：图片的 base64 编码 data URI。data URI 示例：data:image/jpeg;base64,<your base64-encoded image data>
如果原始 asset 与上传图片之间存在较大的 geometry 差异，图像 texture 生成可能无法达到最佳效果。指导 texture 生成过程时，只能使用 texture_image_url 或 texture_prompt 中的一个。如果同时提供了这两个参数，默认将使用 texture_prompt 对模型进行 texture 处理。
Name
ai_model
Type
string
默认值 inherited from the preview task
Description
用于 refine 的模型 ID。
可用值：
- meshy-6-lite、meshy-6、meshy-7.1、latest（Meshy 7.1）
- meshy-7（已 deprecated）：请改用 meshy-7.1。
省略此参数将继承预览任务所使用的模型，从而使预览任务及其 refine 任务从头到尾使用同一模型。传入明确的值可覆盖此继承行为。
明确指定的 latest 在此处的解析结果与预览任务中完全一致（当前为 Meshy 7.1），因此 latest 预览任务及其 latest refine 任务始终会使用同一 texture 模型。
Name
moderation
Type
boolean
默认值 false
Description
当设置为 true 时，将自动对输入内容进行潜在有害内容筛查。如检测到有害内容，任务将不会进入生成阶段。
texture_prompt 中的文本和 texture_image_url 中的图片都会被筛查。
Name
remove_lighting
Type
boolean
默认值 true
Description
从基础颜色 texture 中移除高光和阴影，生成更干净的结果，更适合自定义灯光设置。
仅在 ai_model 为 meshy-6 时生效；其他模型会忽略此设置。
Name
target_formats
Type
string[]
Description
指定输出中应包含的 3D 文件格式。仅会生成并返回所请求的格式，这可以缩短任务完成时间。省略时，将包含所有受支持的格式。
可用值：glb、obj、fbx、stl、usdz、3mf
省略时，将生成除 3mf 之外的所有格式。3mf 仅在显式指定时才会包含。
Name
alpha_thumbnail
Type
boolean
默认值 false
Description
当设置为 true 时，任务会额外渲染预览的透明背景（RGBA）版本，并在 GET 响应中以 alpha_thumbnail_url 返回。现有的 thumbnail_url 字段保持不变。
Name
auto_size
Type
boolean
默认值 false
Description
当设置为 true 时，服务会使用 AI 视觉自动估算物体的真实世界高度，并据此对模型进行尺寸调整。除非显式设置了 origin_at，否则 origin 默认为 bottom。

仅当 auto_size = true

Name
origin_at
Type
string
默认值 bottom
Description
启用 auto_size 时 origin 的位置。
可用值：bottom、center。

返回值

响应中的 result 属性包含新创建的 Text to 3D 任务的任务 id。

失败模式

Name
400 - Bad Request
Description
请求无法被接受。常见原因：
- 无效的任务 ID：preview_task_id 无效或不存在。
- 任务尚未就绪：预览任务尚未成功完成。
- 模型不匹配：预览任务所使用的 AI 模型与请求的 refine 模型不兼容。
Name
401 - Unauthorized
Description
authentication 失败。请检查您的 API key。
Name
402 - Payment Required
Description
credits 不足，无法执行此任务。
Name
404 - Not Found
Description
未找到由 preview_task_id 指定的预览任务。
Name
429 - Too Many Requests
Description
您已超出速率限制。

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

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

检索一个 Text to 3D 任务

此 endpoint 允许您通过有效的任务 id 检索一个 Text to 3D 任务。请参阅 Text to 3D 任务对象以了解 Text to 3D 任务对象包含哪些属性。

此 endpoint 同时适用于 preview 和 refine 任务。

参数

Name
id
Type
path
Description
要检索的 Text to 3D 任务的唯一标识符。

返回值

响应内容包含 Text to 3D 任务对象。详情请查看 Text to 3D 任务对象部分。

示例

Mode	示例模型
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
}

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

删除一个 Text to 3D 任务

此 endpoint 将永久删除一个 Text to 3D 任务，包括所有关联的模型和数据。此操作不可逆。

路径参数

Name
id
Type
path
Description
要删除的 Text to 3D 任务的 ID。

任务状态

仍处于 PENDING 状态的任务会被删除，并且创建时消耗的 credits 会被退还。

已经处于 IN_PROGRESS 状态的任务无法删除：请求会被 409 Conflict 拒绝，任务会继续运行。工作进程已经开始处理的任务，其 credits 不可退还，因此在运行过程中删除它将使你同时失去 credits 和结果。请等待其达到 SUCCEEDED、FAILED 或 CANCELED 状态，然后再删除。

处于终止状态（SUCCEEDED、FAILED 或 CANCELED）的任务会被删除，且不会退还 credits。

返回值

成功时返回 200 OK，当任务处于 IN_PROGRESS 状态时返回 409 Conflict。

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 is left 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."
}

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

列出 Text to 3D 任务

此 endpoint 允许您检索 Text to 3D 任务的列表。

参数

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 任务对象列表。

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

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

流式获取 Text to 3D 任务

此 endpoint 使用 Server-Sent Events（SSE）实时流式传输 Text to 3D 任务的更新。

参数

Name
id
Type
path
Description
要流式传输的 Text to 3D 任务的唯一标识符。

返回值

以 Server-Sent Events 的形式返回 Text to 3D 任务对象的流。

对于 PENDING 或 IN_PROGRESS 状态的任务，响应流中只会包含必要的 progress 和 status 字段。

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.
// 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",
  "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
}

The Text to 3D Task Object

Text to 3D 任务对象是 Meshy 用于跟踪从文本输入生成 3D 模型的工作单元。Text to 3D API 有两个阶段，preview 和 refine。Preview 阶段用于生成仅包含 mesh 的 3D 模型，refine 阶段则基于 preview 阶段的结果生成带纹理的 3D 模型。

该对象具有以下属性：

Properties

Name
id
Type
string
Description
任务的唯一标识符。虽然我们在实现细节中使用可 k 排序的 UUID 作为任务 id，但你不应对 id 的格式做任何假设。
Name
type
Type
string
Description
Text to 3D 任务的类型。可能的值为 text-to-3d-preview（表示 preview 阶段任务）和 text-to-3d-refine（表示 refine 阶段任务）。
Name
model_urls
Type
object
Description
Meshy 生成的带纹理 3D 模型文件的可下载 URL。如果某种格式未生成，对应格式的属性将被省略，而不是返回空字符串。
- Name
  glb
  Type
  string
  Description
  GLB 文件的可下载 URL。
- Name
  fbx
  Type
  string
  Description
  FBX 文件的可下载 URL。
- Name
  usdz
  Type
  string
  Description
  USDZ 文件的可下载 URL。
- Name
  obj
  Type
  string
  Description
  OBJ 文件的可下载 URL。
- Name
  mtl
  Type
  string
  Description
  MTL 文件的可下载 URL。
- Name
  stl
  Type
  string
  Description
  STL 文件的可下载 URL。
- Name
  3mf
  Type
  string
  Description
  3MF 文件的可下载 URL。仅当通过 target_formats 请求了 3mf 时才会出现。
Name
prompt
Type
string
Description
这是创建任务时使用的未经修改的 prompt。
Name
negative_prompt
Type
string
⚠ 已弃用
Description
为向后兼容而保留。此字段对生成的模型没有功能性影响。
Name
art_style
Type
string
⚠ 已弃用
Description
创建 preview 任务时使用的未经修改的 art_style。Meshy-6 不支持此字段。
Name
texture_richness
Type
string
⚠ 已弃用
Description
为向后兼容而保留。此字段对生成的模型没有功能性影响。
Name
texture_prompt
Type
string
Description
在 refine 阶段用于指导贴图过程的附加文本提示。
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
模型文件缩略图的可下载 URL。
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url 的透明背景（RGBA）版本的可下载 URL。仅当任务创建时设置了 alpha_thumbnail: true 且成功渲染出透明预览图时才会出现；否则将省略此字段。
Name
video_url
Type
string
⚠ 已弃用
Description
预览视频的可下载 URL。将在未来版本中移除。
Name
progress
Type
integer
Description
任务的进度。如果任务尚未开始，此属性为 0。任务成功后，此值将变为 100。
Name
started_at
Type
timestamp
Description
任务开始时间的时间戳，单位为毫秒。如果任务尚未开始，此属性为 0。
时间戳表示自 1970 年 1 月 1 日 UTC 起经过的毫秒数，遵循 RFC 3339 标准。例如，格林尼治标准时间 2023 年 9 月 1 日星期五中午 12:00:00 表示为 1693569600000。这适用于 Meshy API 中的所有时间戳。
Name
created_at
Type
timestamp
Description
任务创建时间的时间戳，单位为毫秒。
Name
finished_at
Type
timestamp
Description
任务完成时间的时间戳，单位为毫秒。如果任务尚未完成，此属性为 0。
Name
status
Type
string
Description
任务的状态。可能的值为 PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED 之一。
Name
texture_urls
Type
array
Description
任务生成的纹理 URL 对象数组。通常这里只包含一个纹理 URL 对象。每个纹理 URL 具有以下属性：
- 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，或 ai_model 为 meshy-6-lite，将省略此属性。
Name
preceding_tasks
Type
integer
Description
前面排队任务的数量。
仅当任务状态为 PENDING 时，此字段的值才有意义。
Name
task_error
Type
object
Description
失败任务的错误详情。完整的 task_error 对象参考请参阅 Errors。
Name
consumed_credits
Type
integer
Description
该任务消耗的 credits 数量。当任务状态为 PENDING、IN_PROGRESS 或 SUCCEEDED 时会出现此字段。对于 FAILED 任务，返回 0（失败时 credits 会被退回）。

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
}