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

Creative Lab Keychain API

通过两个阶段,将一张照片转换为可 3D 打印的、带有彩色浮雕的钥匙扣。原型任务会根据照片生成一张彩色概念图像。构建任务会将该图像转换为浮雕 3D 模型,并以原型任务的 ID 作为 input_task_id。

  • POST /openapi/creative-lab/keychain/v1/prototype
  • POST /openapi/creative-lab/keychain/v1/build

POST/openapi/creative-lab/keychain/v1/prototype

创建 Keychain prototype 任务

根据一张照片生成一张彩色概念图。要构建 3D 模型,请将此任务的 ID 作为 input_task_id 传递给构建 endpoint。关于该任务的字段,请参阅 Keychain prototype 任务对象。

Request

POST
/openapi/creative-lab/keychain/v1/prototype
# Stage 1: generate a colorized keychain concept image
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "name_text": "Luna"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
Prototype example
Start with a source photo, then generate the prototype image used by the keychain build stage.
Source photo used as the Creative Lab Keychain input
Prototype input
Creative Lab Keychain prototype output generated from the source photo
Prototype output

参数

  • Name
    image_url
    Type
    string
    必选
    Description

    要转换为钥匙扣概念图的照片,可以是公开 URL 或 data URI(data:image/jpeg;base64,<your base64-encoded image data>)。

    图片必须是 JPG、JPEG、PNG 或 WebP 文件,且不超过 20 MB。

  • Name
    name
    Type
    string
    Description

    任务名称,最多 100 个字符。它会在任务的 name 字段中返回。超长的名称会返回 400。

    它用于在你的 dashboard 和任务列表中标记该任务,不会出现在钥匙扣上。如果要在钥匙扣上显示名称,请使用 name_text。

  • Name
    name_text
    Type
    string
    Description

    要添加到钥匙扣上的名称,例如宠物或人的名字,最多 10 个字符。Meshy 按字符计数,而非按字节,因此一个 10 字符的中文、日文或韩文名字也能放下。超长的名称会返回 400。留空则生成不带名称的钥匙扣。

    该名称会以扁平的彩色细节形式出现在钥匙扣正面,而不是凸起或镂空的文字。

    Meshy 会修剪前后空白并移除不可见的格式字符。prototype 任务对象会以 name_text 返回结果,因此你可以在为构建付费之前检查该文本。

    Meshy 在 prototype 阶段添加名称。构建会保留它,并忽略发送给构建 endpoint 的 name_text。

  • Name
    remove_background
    Type
    boolean
    默认值 false
    Description

    是否从 prototype 图像中移除背景。true 会返回保留整个徽章部分的透明 RGBA PNG,方便你将其放置在任意背景上。构建阶段也会从去除背景后的图像开始处理。如果 Meshy 无法移除背景,会返回带背景的图像,任务仍会成功。

    构建阶段的 remove_background 选项是独立的。

返回值

result 字段保存新建 prototype 任务的 ID。获取该任务或对其进行流式获取,直到 status 变为 SUCCEEDED。然后将该 ID 作为 input_task_id 传递给构建 endpoint。

失败情形

  • Name
    400 - Bad Request
    Description

    请求无法执行。例如:

    • 缺少 image_url。
    • 图片不是 JPG、JPEG、PNG 或 WebP 文件。
    • 图片过小、超过 20 MB,或超过最大像素数。
    • Meshy 无法下载该图片,例如 URL 返回 404 或超时。
    • data URI 不是有效的 base64。
    • name_text 超过 10 个字符。Meshy 会拒绝该请求而非自动截短,也不会为此请求计费。
    • 图片或 name_text 被标记为 NSFW。

    错误消息会说明发现了哪个问题。修正请求后重新发送。

  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

    符合以下情形之一:

    • 账户没有足够的积分。
    • 该 API key、workspace 或成员已达到其积分限额。
    • 该账户处于免费计划。

    请检查你的积分和计划,然后重试。

  • Name
    403 - Forbidden
    Description

    你的团队开启了 IP Filtering,且 Meshy 将该图片标记为涉及第三方知识产权。请发送你拥有使用权的图片。Meshy 只检查图片的知识产权问题,不检查 name_text。

  • Name
    429 - Too Many Requests
    Description

    达到以下某个限制:

    • 你发送的请求超过了速率限制所允许的数量。请等待几秒后重试。参见速率限制。
    • 你排队或正在运行的任务过多。请等待部分任务完成后重试。
    • 在没有积分的无限计划下,已达到可在无积分情况下运行的任务数量上限。请等待某个任务完成,或增加积分。
  • Name
    500 - Internal Server Error
    Description

    Meshy 遇到了服务器错误,例如无法对图片执行知识产权检查。Meshy 不会创建该任务,并会退还已扣除的任何积分。请重试该请求。


POST/openapi/creative-lab/keychain/v1/build

创建 Keychain 构建任务

从一个已成功的 prototype 任务生成可 3D 打印的 keychain。Meshy 会将 prototype 的概念图转换为深度图浮雕,并以你选择的格式返回一个模型文件。关于该任务的字段,请参阅 The Keychain build task object。

Request

POST
/openapi/creative-lab/keychain/v1/build
# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "options": {
      "badge_shape": "circle",
      "size_mm": 40,
      "relief_height_mm": 2.5
    },
    "output": {
      "format": "glb"
    }
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}
Build example
该构建任务会将所选的 prototype 图像转换为可 3D 打印的 keychain 模型。
Creative Lab Keychain build model preview
Build model preview

参数

  • Name
    input_task_id
    Type
    string
    必选
    Description

    要构建的 prototype 任务的 ID。它必须是你的账户通过 POST /openapi/creative-lab/keychain/v1/prototype 创建的任务,且状态为 SUCCEEDED。

    如果 ID 不是你通过 API 创建的 Keychain prototype 任务之一(包括在 web app 中创建的 prototype),将返回 404。

  • Name
    name
    Type
    string
    Description

    任务的名称,最多 100 个字符。它会在任务的 name 字段中返回。名称过长会返回 400。

options

用于浮雕形状的可选设置。每个字段都有默认值,所以只需发送你想更改的字段。字段取值超出范围会返回 400。

  • Name
    badge_shape
    Type
    string
    默认值 circle
    Description

    当 Meshy 没有从主体描摹出轮廓时,keychain 使用的外形轮廓。当 remove_background 为 false,或者 Meshy 无法找到主体的轮廓时,会使用该字段。

    可用值:

    • circle
    • rounded-rect
    • hexagon
    • shield
    • star
  • Name
    size_mm
    Type
    number
    默认值 40
    Description

    keychain 边界正方形的边长,单位为毫米,最大为 400。0 表示使用默认值。

  • Name
    relief_height_mm
    Type
    number
    默认值 2.2
    Description

    浮雕相对于底座的最大高度,单位为毫米,范围从 0 到 20。

  • Name
    relief_offset_mm
    Type
    number
    默认值 0
    Description

    将浮雕整体下压的幅度,单位为毫米,范围从 0 到 20。Meshy 会在浮雕各处的高度上统一减去该值,直到降至底座高度。

  • Name
    base_thickness_mm
    Type
    number
    默认值 0.1
    Description

    浮雕背后平整底板的厚度,单位为毫米,范围从 0 到 20。

  • Name
    has_closed_back
    Type
    boolean
    默认值 true
    Description

    是否封闭 keychain 的背面。false 会让背面保持开放,呈壳状。

  • Name
    relief_curve
    Type
    string
    默认值 linear
    Description

    将深度图数值映射到浮雕高度所使用的曲线。

    可用值:

    • linear
    • gamma
    • s-curve
  • Name
    curve_param
    Type
    number
    默认值 1.0
    Description

    曲线的强度,最大为 10。gamma 和 s-curve 曲线会使用该值,linear 会忽略它。0 表示使用默认值。

  • Name
    invert_depth
    Type
    boolean
    默认值 false
    Description

    是否反转深度图,使较暗区域生成更高的浮雕。

  • Name
    smoothing
    Type
    number
    默认值 0.24
    Description

    在 Meshy 构建浮雕之前,对深度图进行平滑处理的程度,范围从 0 到 10。

  • Name
    relief_scale
    Type
    number
    默认值 1.0
    Description

    以中心为基准,对轮廓内的浮雕及其 texture 进行缩放的程度,最大为 10。大于 1 的值会放大主体,小于 1 的值会缩小主体。它不会改变浮雕的高度。0 表示使用默认值。

  • Name
    depth_threshold
    Type
    number
    默认值 0.1
    Description

    深度图数值低于该阈值时,Meshy 会将深度设为零,范围从 0 到 1。

  • Name
    remove_background
    Type
    boolean
    默认值 true
    Description

    是否从主体描摹出 keychain 的轮廓,使 keychain 贴合主体的形状。false 则改用 badge_shape 的轮廓。当 Meshy 无法找到主体的轮廓时,也会使用 badge_shape。

    这与 prototype 的 remove_background 参数是相互独立的,后者设置的是 prototype 图像是否具有透明背景。

  • Name
    export_resolution
    Type
    integer
    默认值 512
    Description

    导出模型的 mesh 分辨率,范围从 64 到 512。Meshy 基于 512 像素的深度图构建 geometry,因此更精细的 mesh 只会增加面数,而不会增加细节。0 表示使用默认值。

output

可选。设置构建返回的文件格式。

  • Name
    format
    Type
    string
    默认值 glb
    Description

    构建返回的文件格式。

    可用值:

    • glb:一个 model.glb 文件,位于 model_urls.glb
    • obj:一个包含 model.obj、model.mtl 和 texture.png 的 zip 文件,位于 model_urls.obj
    • zip:一个包含 Meshy 生成的所有文件的 zip 文件,位于 model_urls.bundle_zip

返回值

result 字段保存新构建任务的 ID。获取任务或流式获取任务,直到 status 变为 SUCCEEDED。然后从 model_urls 中唯一的一条记录下载文件。

失败情形

  • Name
    400 - Bad Request
    Description

    该请求无法运行。例如:

    • input_task_id 缺失或不是有效的任务 ID。
    • prototype 任务的状态不是 SUCCEEDED。如果它仍在运行,请等待后重试。如果它失败或被取消,请创建一个新的 prototype 任务。
    • prototype 任务成功了,但没有图像。请创建一个新的 prototype 任务。
    • 某个 options 字段超出了取值范围,或不是可用值。

    错误信息会说明发现了哪个问题。

  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

    以下情形之一适用:

    • 账户的积分不足。
    • API key、workspace 或成员已达到其积分限额。
    • 账户处于免费方案。

    请检查你的积分和方案,然后重试。

  • Name
    404 - Not Found
    Description

    input_task_id 不匹配你的账户通过 API 创建的任何 Keychain prototype 任务。在 web app 中创建的 prototype 也会返回 404。请发送来自 prototype 创建响应中的 result ID。

  • Name
    429 - Too Many Requests
    Description

    达到了以下限制之一:

    • 你发送的请求数超过了速率限制允许的数量。请等待几秒钟后重试。参见 Rate limits。
    • 你排队或正在运行的任务过多。请等待部分任务完成后重试。
    • 在没有剩余积分的无限制方案下,你已达到可在没有积分的情况下运行的任务数量上限。请等待某个任务完成,或增加积分。

GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id

获取 Keychain 任务

返回一个 prototype 或 build 任务。路径必须与任务所处的阶段相匹配。通过 /prototype/:id 请求的 build 任务会返回 404,通过 /build/:id 请求的 prototype 任务同样会返回 404。

关于字段说明,参见 The Keychain prototype task object 和 The Keychain build task object。

Request

GET
/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578
# Prototype
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

参数

  • Name
    id
    Type
    path
    Description

    创建响应中的任务 ID。

返回值

根据路径中的阶段,返回 prototype 任务对象 或 build 任务对象。

失败模式

  • Name
    400 - Bad Request
    Description

    id 不是有效的任务 ID。请发送创建响应中的 result ID。

  • Name
    403 - Forbidden
    Description

    你的团队已开启 IP Filtering,且 Meshy 标记了该 prototype 任务图片涉及第三方知识产权。Build 任务以及 Enterprise 套餐的团队不会出现此错误。请使用你拥有使用权的图片创建 prototype 任务。

  • Name
    404 - Not Found
    Description

    你的账户下没有此 ID 对应的 Keychain 任务,或者任务所处的阶段与路径不匹配。请检查 ID,并使用 /prototype 或 /build 以匹配该任务。

  • Name
    500 - Internal Server Error
    Description

    Meshy 无法执行知识产权检查。请重试该请求。


DELETE/openapi/creative-lab/keychain/v1/(prototype|build)/:id

删除一个 Keychain 任务

取消一个 Keychain 任务。取消一个 PENDING 任务会退还其积分。IN_PROGRESS 任务会被取消但不会退款,因为工作进程已经开始处理它。处于最终状态(SUCCEEDED、FAILED 或 CANCELED)的任务无法取消。

路径必须与任务所处的阶段匹配。例如,使用构建任务的 ID 对 /prototype/:id 执行 DELETE 会返回 404。

Request

DELETE
/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).

路径参数

  • Name
    id
    Type
    path
    Description

    要取消的任务的 ID。

返回值

204 No Content,空响应体。

失败情况

  • Name
    400 - Bad Request
    Description

    适用以下情况之一:

    • id 不是有效的任务 ID。请发送创建响应中的 result ID。
    • 任务已处于最终状态(SUCCEEDED、FAILED 或 CANCELED),因此无法取消。
  • Name
    404 - Not Found
    Description

    没有属于你账户的、具有此 ID 的 Keychain 任务,或者任务所处的阶段与路径不匹配。请检查该 ID,并使用 /prototype 或 /build 来匹配任务。


GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id/stream

流式获取 Keychain 任务

以服务器发送事件(SSE)的形式流式传输 Keychain 任务的更新。路径必须与任务所处的阶段匹配。如果不匹配——例如将 build 任务的 ID 用在 /prototype/:id/stream 上——该流会发送一个 status_code: 404 的 error 事件,然后关闭。

Request

GET
/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream
curl -N https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (wrong stage or task not found)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object; fields not yet populated are null / empty.
// The following PENDING frame is shortened to the fields that change.
event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

参数

  • Name
    id
    Type
    path
    Description

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

返回值

一个由 prototype 或 build 任务对象组成的流。每个事件都包含完整的任务对象,格式与 获取 Keychain 任务 返回的一致。当任务处于 PENDING 或 IN_PROGRESS 状态时,其输出字段仍为空(null、[] 或 {}),且 finished_at 为 null。

如果 IP 过滤 拦截了任务的结果,该流会在原本位置发送一个 error 事件,其中的 status_code 与发起 get 请求时会返回的状态码一致。


GET/openapi/creative-lab/keychain/v1/(prototype|build)

列出 Keychain 任务

返回你某个阶段的 Keychain 任务,每次返回一页。路径决定阶段:/prototype 仅返回 prototype 任务,/build 仅返回 build 任务。

Request

GET
/openapi/creative-lab/keychain/v1/prototype
# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-keychain-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123486000,
    "expires_at": 1729382686000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

路径参数

  • Name
    stage
    Type
    path
    必选
    Description

    要列出的阶段,prototype 或 build。

查询参数

  • Name
    page_num
    Type
    integer
    默认值 1
    Description

    要返回的页码,范围为 1 到 255。0 返回第一页。超出 0 到 255 范围的值将返回 400。

  • Name
    page_size
    Type
    integer
    默认值 10
    Description

    每页任务数量,最多 100。101 到 255 之间的值返回 100 个任务,0 使用默认值。超出 0 到 255 范围的值将返回 400。

  • Name
    sort_by
    Type
    string
    默认值 -created_at
    Description

    排序方式。

    可用值:

    • -created_at:最新的排在前面
    • +created_at:最旧的排在前面

返回值

一个由 prototype 任务对象 或 build 任务对象 组成的数组,与路径中的阶段相对应。


Keychain prototype 任务对象

prototype 任务会根据一张照片生成彩色的概念图。要将该图像转换为 3D 模型,请将该任务的 ID 作为 input_task_id 传递给build endpoint。

属性

Example Keychain Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-prototype",
  "name": "",
  "name_text": "Luna",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}
  • Name
    id
    Type
    string
    Description

    任务 ID。请勿依赖其具体格式。

  • Name
    type
    Type
    string
    Description

    任务类型,始终为 creative-lab-keychain-prototype。

  • Name
    name
    Type
    string
    Description

    你在创建任务时发送的 name;如果未发送,则为 ""。

  • Name
    name_text
    Type
    string
    Description

    Meshy 为钥匙扣添加的名称,已去除首尾空白并移除不可见的格式字符。如果你没有发送 name_text,则不会包含此字段。要检查你的 HTTP 客户端是否正确编码了文本,可将其与你发送的内容进行对比。

  • Name
    status
    Type
    string
    Description

    任务的状态。

    可用取值:

    • PENDING:在队列中等待
    • IN_PROGRESS:正在生成结果
    • SUCCEEDED:最终状态,已生成结果
    • FAILED:最终状态,失败原因在 task_error 中
    • CANCELED:最终状态,无结果
  • Name
    progress
    Type
    integer
    Description

    已完成工作的百分比,取值从 0 到 100。任务开始前为 0,成功完成后为 100。

  • Name
    created_at
    Type
    timestamp
    Description

    任务创建时间,单位为 Unix 毫秒。

  • Name
    started_at
    Type
    timestamp
    Description

    工作进程开始处理该任务的时间,单位为 Unix 毫秒。在此之前为 null。

  • Name
    finished_at
    Type
    timestamp
    Description

    任务达到最终状态的时间,单位为 Unix 毫秒。在此之前为 null。

  • Name
    expires_at
    Type
    timestamp
    Description

    任务结果的过期时间,单位为 Unix 毫秒。该时间为 finished_at 之后的 3 天;如果任务尚未完成,则为 created_at 之后的 3 天。对于会无限期保留 API 结果的企业版账户,该时间约为 100 年后。参见资产保留期。

  • Name
    preceding_tasks
    Type
    integer
    Description

    该任务在处于 PENDING 状态时在队列中的位置。1 表示它将是下一个开始的任务。任务离开队列后为 0,在列表结果中始终为 0。

  • Name
    task_error
    Type
    object
    Description

    任务失败的原因。除非 status 为 FAILED,否则为 null。参见 Errors。

  • Name
    consumed_credits
    Type
    integer
    Description

    该任务在扣除任何退款后所实际收取的积分数量。返回错误的请求不会被收费。失败的任务为 0,因为 Meshy 会对其进行退款。只有在任务处于 PENDING 状态时取消,才会退还该任务的积分。如果 Meshy 无法读取扣费信息,get 或 stream 响应会省略该字段,而 list 请求会返回 500。在这种情况下,请重试该请求。

  • Name
    image_urls
    Type
    array of strings
    Description

    概念图的下载 URL。任务成功后,该数组包含一个 URL;在此之前为空数组。


钥匙扣构建任务对象

构建任务会根据一个成功的原型任务生成 3D 钥匙扣。它会返回一个你所请求格式的模型文件。

属性

Example Keychain Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}
  • Name
    id
    Type
    string
    Description

    任务 ID。不要依赖其格式。

  • Name
    type
    Type
    string
    Description

    任务类型,始终为 creative-lab-keychain-build。

  • Name
    name
    Type
    string
    Description

    你在创建任务时发送的 name,如果未发送则为 ""。

  • Name
    status
    Type
    string
    Description

    任务的状态。

    可用值:

    • PENDING:在队列中等待
    • IN_PROGRESS:正在生成结果
    • SUCCEEDED:最终状态,附带结果
    • FAILED:最终状态,原因在 task_error 中
    • CANCELED:最终状态,无结果
  • Name
    progress
    Type
    integer
    Description

    已完成工作的百分比,从 0 到 100。任务开始前为 0,成功后为 100。

  • Name
    created_at
    Type
    timestamp
    Description

    任务创建的时间,以 Unix 毫秒表示。

  • Name
    started_at
    Type
    timestamp
    Description

    工作进程开始执行任务的时间,以 Unix 毫秒表示。在此之前为 null。

  • Name
    finished_at
    Type
    timestamp
    Description

    任务达到最终状态的时间,以 Unix 毫秒表示。在此之前为 null。

  • Name
    expires_at
    Type
    timestamp
    Description

    任务结果过期的时间,以 Unix 毫秒表示。该时间为 finished_at 之后 3 天,在任务完成之前则为 created_at 之后 3 天。对于会无限期保留 API 结果的企业账户,该时间约为 100 年后。参见资产保留期。

  • Name
    preceding_tasks
    Type
    integer
    Description

    任务在 PENDING 状态时在队列中的位置。1 表示它是下一个开始的任务。任务离开队列后为 0,在列表结果中始终为 0。

  • Name
    task_error
    Type
    object
    Description

    任务失败的原因。除非 status 为 FAILED,否则为 null。参见 Errors。

  • Name
    consumed_credits
    Type
    integer
    Description

    任务所扣除的积分数量(已扣除任何退款)。返回错误的请求不会被扣费。失败的任务为 0,因为 Meshy 会退还该费用。取消任务只有在任务处于 PENDING 状态时才会退款。如果 Meshy 无法读取扣费情况,get 或 stream 响应会省略该字段,list 请求则会返回 500。在这种情况下,请重试该请求。

  • Name
    model_urls
    Type
    object
    Description

    模型文件的下载链接,其中为你所请求的 output.format 提供一个条目。在任务成功之前为 {}。

    • Name
      glb
      Type
      string
      Description

      GLB 文件的下载链接。当 output.format 为 glb 时存在。

    • Name
      obj
      Type
      string
      Description

      包含 model.obj、model.mtl 和 texture.png 的 zip 文件的下载链接。当 output.format 为 obj 时存在。

    • Name
      bundle_zip
      Type
      string
      Description

      包含 Meshy 生成的所有文件的 zip 文件的下载链接。当 output.format 为 zip 时存在。