文本生成 3D API

文本生成 3D API 是一项功能，允许你将 Meshy 的文本生成 3D 能力集成到你自己的应用程序中。在本节中，你将找到开始使用该 API 所需的全部信息。

文本生成 3D 的工作流程分为两个阶段：预览阶段和精细化阶段。在预览阶段，会生成一个没有贴图的基础网格，便于你评估几何体。在精细化阶段，预览网格会根据文本提示进行贴图。

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

创建文本生成3D预览任务

该接口用于创建新的文本生成3D预览任务。请参考文本生成3D任务对象了解文本生成3D任务对象包含的属性。

参数

必填属性

Name
mode
Type
string
Description
创建预览任务时，该字段应设置为 "preview"。
Name
prompt
Type
string
Description
描述 3D 模型是什么类型的物体。最大 600 个字符。

可选属性

Name
art_style
Type
string
Description
描述你期望的物体艺术风格。
可选值：
- realistic：写实风格
- sculpture：雕塑风格
如未指定，默认为 realistic。
注意：当使用雕塑风格时，enable_pbr 应设置为 false，因为雕塑风格会生成自带的 PBR 贴图。
Name
seed
Type
integer
Description
任务的随机种子。当你使用相同的 prompt 和 seed 时，大多数情况下会生成相同的结果。但由于软件和硬件的更新，偶尔同一 seed 也可能产生不同结果。
Name
ai_model
Type
string
Description
所用模型的 ID。
可选值：
- meshy-4
- meshy-5
如未指定，默认为 meshy-4。
精细化任务会使用与对应预览任务相同的模型。
Name
topology
Type
string
Description
指定生成模型的拓扑结构。
可选值：
- quad：生成以四边形为主的网格
- triangle：生成简化的三角网格
如未指定，默认为 triangle。
Name
target_polycount
Type
integer
Description
指定生成模型的目标面数。实际面数可能会因几何复杂度而有所偏差。
有效取值范围根据用户等级不同而变化：
- 100 到 300,000（含）
如未指定，默认为 30,000。
Name
should_remesh
Type
boolean
Description
should_remesh 标志控制是否启用重建网格阶段。
当设置为 false 时，将直接返回未经处理的三角网格，忽略 topology 和 target_polycount。
如未指定，默认为 true。
Name
symmetry_mode
Type
string
Description
symmetry_mode 字段控制模型生成过程中的对称性行为。
可选值：
- off：关闭对称
- auto：根据输入几何自动判断并应用对称
- on：强制对称生成
如未指定，默认为 auto。

返回值

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

请求

POST

/openapi/v2/text-to-3d

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",
  "art_style": "realistic",
  "should_remesh": true
}'

响应

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

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

创建文本生成3D精细化任务

该接口用于创建新的文本生成3D精细化任务。

参数

必填属性

Name
mode
Type
string
Description
创建精细化任务时，该字段应设置为 "refine"。
Name
preview_task_id
Type
string
Description
对应的预览任务 id。
给定的预览任务状态必须为 SUCCEEDED。

可选属性

Name
enable_pbr
Type
boolean
Description
生成 PBR 贴图（金属度、粗糙度、法线）以及基础色贴图。
如未指定，默认为 false。
注意：当使用雕塑风格时，enable_pbr 应设置为 false，因为雕塑风格会生成自带的 PBR 贴图。
目前，enable_pbr=true 仅支持 ai_model 为 meshy-4。
Name
texture_prompt
Type
string
Description
提供额外的文本提示以引导贴图过程。最大 600 个字符。
Name
texture_image_url
Type
string
Description
提供 2D 图片以引导贴图过程。目前支持 .jpg、.jpeg 和 .png 格式。
提供图片有两种方式：
- 公网可访问的 URL：可从公网访问的图片链接
- Data URI：图片的 base64 编码 Data URI。例如：data:image/jpeg;base64;<your base64-encoded image data>
如果原始资产与上传图片在几何上有较大差异，图像贴图效果可能不佳。texture_image_url 和 texture_prompt 只能二选一。如果都提供，则默认使用 texture_prompt 进行贴图。通过文本或图片贴图每个任务消耗 10 积分。
目前，texture_image_url 仅支持 ai_model 为 meshy-4。

返回值

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

请求

POST

/openapi/v2/text-to-3d

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

响应

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

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

获取文本生成3D任务

该接口允许你通过有效的任务 id 获取文本生成3D任务。请参考文本生成3D任务对象查看任务对象包含的属性。

该接口同时适用于预览和精细化任务。

参数

Name
id
Type
path
Description
要获取的文本生成3D任务的唯一标识符。

返回值

响应包含文本生成3D任务对象。详情请查看文本生成3D任务对象部分。

示例

模式	示例模型
预览
精细化

请求

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

响应

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "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",
  "art_style": "realistic",
  "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": ""
  }
}

GET/openapi/v2/text-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：按创建时间降序排序。

返回值

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

请求

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

响应

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "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",
    "art_style": "realistic",
    "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": ""
    }
  }
]

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

流式获取文本生成3D任务

该接口通过 Server-Sent Events (SSE) 实时流式返回文本生成3D任务的进度更新。

参数

Name
id
Type
path
Description
要流式获取的文本生成3D任务的唯一标识符。

返回值

返回文本生成3D任务对象的 SSE 实时流。

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

请求

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

响应流

// 错误事件示例
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// 消息事件示例，展示任务进度。
// 对于 PENDING 或 IN_PROGRESS 状态的任务，响应流不会包含所有字段。
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",
"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_roughness.png?Expires=XXX",
    "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX"
  }
],
"preceding_tasks": 0,
"task_error": {
    "message": ""
  }
}

文本生成3D任务对象

文本生成3D任务对象是 Meshy 用于追踪从文本输入生成 3D 模型的工作单元。文本生成3D API 分为两个阶段：preview（预览）和 refine（精细化）。预览阶段用于生成仅有网格的 3D 模型，精细化阶段则基于预览结果生成带贴图的 3D 模型。

该对象包含以下属性：

属性

Name
id
Type
string
Description
任务的唯一标识符。虽然我们采用 k-sortable UUID 作为任务 id 的实现细节，但你不应对 id 格式做任何假设。
Name
model_urls
Type
object
Description
Meshy 生成的带贴图 3D 模型文件的可下载链接。如果某种格式未生成，则不会返回该属性。
- 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
prompt
Type
string
Description
创建任务时使用的原始 prompt。
Name
negative_prompt
Type
string
Description
为兼容性保留的废弃字段，对生成模型无实际影响。
Name
art_style
Type
string
Description
创建预览任务时使用的原始 art_style。
Name
texture_richness
Type
string
Description
为兼容性保留的废弃字段，对生成模型无实际影响。
Name
texture_prompt
Type
string
Description
精细化阶段用于引导贴图过程的额外文本提示。
Name
texture_image_url
Type
string
Description
用于引导贴图过程的图片下载链接。
Name
thumbnail_url
Type
string
Description
模型文件缩略图的可下载链接。
Name
video_url
Type
string
Description
预览视频的可下载链接。
Name
progress
Type
integer
Description
任务进度。如果任务尚未开始，该值为 0。任务成功后为 100。
Name
seed
Type
integer
Description
任务的随机种子。当你使用相同的 prompt 和 seed 时，大多数情况下会生成相同的结果。但由于软件和硬件的更新，偶尔同一 seed 也可能产生不同结果。
Name
started_at
Type
timestamp
Description
任务开始时间的时间戳（毫秒）。如果任务尚未开始，该值为 0。
时间戳表示自 1970 年 1 月 1 日 UTC 起经过的毫秒数，遵循 RFC 3339 标准。例如，2023 年 9 月 1 日 12:00:00 GMT 表示为 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
  基础色贴图的可下载链接。
- 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
preceding_tasks
Type
integer
Description
前置任务数量。
仅当任务状态为 PENDING 时，该字段有意义。
Name
task_error
Type
object
Description
任务失败时包含错误信息的对象。若任务成功，message 字段应为空。
- Name
  message
  Type
  string
  Description
  详细错误信息。

响应

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "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=***"
  },
  "prompt": "a monster mask",
  "art_style": "realistic",
  "texture_richness": "high",
  "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=***",
  "video_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.mp4?Expires=***",
  "progress": 1,
  "seed": 1234,
  "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_roughness.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  }
}