文本生成体素 API

文本生成体素 API 是一个功能，允许您将 Meshy 的文本生成体素功能集成到您自己的应用程序中。在本节中，您将找到开始使用此 API 所需的所有信息。

这是一个旧版 API，很快将被弃用。请使用 文本生成 3D API 代替。

POST/openapi/v1/text-to-voxel

创建一个文本生成体素任务

此端点允许您创建一个新的文本生成体素任务。请参阅 文本生成体素任务对象 以查看文本生成体素任务对象包含哪些属性。

参数

必需属性

  • Name
    voxel_size_shrink_factor
    Type
    integer
    Description

    此字段是用于控制三维数据体素大小的参数。较高的值对应于较小的体素大小。可能的值为 8、4、2、1。

  • Name
    prompt
    Type
    string
    Description

    描述 3D 模型是什么样的对象。

可选属性

  • Name
    negative_prompt
    Type
    string
    Description

    描述模型不应该是什么样子。

  • Name
    seed
    Type
    integer
    Description

    当您使用相同的提示和种子时，您将生成相同的结果。

返回

响应的 result 属性包含新创建的文本生成体素任务的任务 id。

请求

POST
/openapi/v1/text-to-voxel
curl https://api.meshy.ai/openapi/v1/text-to-voxel \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
  "voxel_size_shrink_factor": 1,
  "prompt": "a monster mask",
  "negative_prompt": "low quality, low resolution, low poly, ugly"
}'

响应

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
GET/openapi/v1/text-to-voxel/:id

检索一个文本生成体素任务

此端点允许您在提供有效任务 id 的情况下检索文本生成体素任务。 请参阅 文本生成体素任务对象 以查看文本生成体素任务对象包含哪些属性。

参数

  • Name
    id
    Type
    path
    Description

    要检索的文本生成体素任务的唯一标识符。

返回

响应包含文本生成体素任务对象。查看 文本生成体素任务对象 部分以获取详细信息。

请求

GET
/openapi/v1/text-to-voxel/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.ai/openapi/v1/text-to-voxel/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=***",
    "vox": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.vox?Expires=***",
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "negative_prompt": "low quality, low resolution, low poly, ugly",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "voxel_size_shrink_factor": 8,
}

文本生成体素任务对象

文本生成体素任务对象是 Meshy 跟踪的一个工作单元，用于从 文本 输入生成体素模型。 该模型具有以下属性：

属性

  • Name
    id
    Type
    string
    Description

    任务的唯一标识符。虽然我们使用 k-sortable UUID 作为任务 id 的实现细节，但您不应对 id 的格式做任何假设。

  • Name
    model_urls
    Type
    object
    Description

    由 Meshy 生成的带纹理 3D 模型文件的可下载 URL。

    • Name
      glb
      Type
      string
      Description

      GLB 文件的可下载 URL。

    • Name
      vox
      Type
      string
      Description

      VOX 文件的可下载 URL。

  • Name
    prompt
    Type
    string
    Description

    这是用于创建任务的未修改 prompt。

  • Name
    negative_prompt
    Type
    string
    Description

    这是用于创建任务的未修改 negative_prompt。

  • Name
    thumbnail_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 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
    voxel_size_shrink_factor
    Type
    integer
    Description

    此字段是用于控制三维数据体素大小的参数。较高的值对应于较小的体素大小。可能的值为 8、4、2、1 之一。

  • 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=***",
    "vox": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.vox?Expires=***",
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "negative_prompt": "low quality, low resolution, low poly, ugly",
  "progress": 1,
  "seed": 1234,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "voxel_size_shrink_factor": 8,
}