创意工坊 — 钥匙扣 API

把你的照片变成可 3D 打印的徽章式钥匙扣挂件 —— 一枚带浮雕的彩色圆牌。 整个流程分两段：prototype 用源照片生成一张上色后的概念图，build 再 把概念图转成浮雕 3D 模型。两段通过 input_task_id 串联。

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

创建钥匙扣 Prototype 任务

从源照片生成一张上色后的钥匙扣概念图。返回的任务 ID 即作为后续 build 端点的 input_task_id。响应结构详见 Prototype 任务对象。

参数

  • Name
    image_url
    Type
    string
    必选
    Description

    提供给 Meshy 用于钥匙扣概念图上色的源照片。目前支持 .jpg、.jpeg、.png、.webp 格式。

    可通过两种方式提供图片：

    • 公网可访问 URL：可从公网访问的 URL。
    • Data URI：图片的 base64 编码 data URI，示例：data:image/jpeg;base64,<your base64-encoded image data>。
  • Name
    name
    Type
    string
    Description

    可选的任务名称，仅用于展示。最长 100 个字符。

返回值

响应的 result 字段返回新创建的 keychain prototype 任务的 id。轮询 查询任务 或订阅 流式更新 直到任务状态变为 SUCCEEDED，再把该 ID 作为 build 端点 的 input_task_id 传入。

失败场景

  • Name
    400 - Bad Request
    Description

    请求不合法，常见原因：

    • 缺少参数：image_url 必传。
    • 图片格式不支持：image_url 不是受支持的格式（.jpg、.jpeg、.png、.webp）。
    • 图片尺寸不合法：图片过小、文件超过最大体积上限，或像素数超过上限。
    • URL 无法访问：image_url 下载失败（404 或超时）。
    • Data URI 不合法：base64 字符串格式错误。
    • 内容被审核拦截：图片被 NSFW 或知识产权审核标记。
  • Name
    401 - Unauthorized
    Description

    身份验证失败，请检查 API key。

  • Name
    402 - Payment Required
    Description

    积分不足，无法创建任务。

  • Name
    429 - Too Many Requests
    Description

    请求超出速率限制。

Request

POST
/openapi/creative-lab/keychain/v1/prototype
# Stage 1：生成钥匙扣的上色概念图
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
Prototype 示例
从源照片开始，生成钥匙扣 build 阶段会使用的 prototype 图。
作为 Creative Lab 钥匙扣输入的源照片
Prototype 输入
由源照片生成的 Creative Lab 钥匙扣 prototype 输出图
Prototype 输出
POST/openapi/creative-lab/keychain/v1/build

创建钥匙扣 Build 任务

基于已成功的 prototype 任务，生成最终的可 3D 打印的钥匙扣挂件。Build 在 prototype 的上色概念图之上运行深度图浮雕管线，并按调用方指定的格式产出 一个网格文件。响应结构详见 Build 任务对象。

参数

  • Name
    input_task_id
    Type
    string
    必选
    Description

    通过同一个 OpenAPI 端点创建的 prototype 任务的 ID。该 prototype 必须由同一 API key 创建、状态已变为 SUCCEEDED，且产出恰好一张候选图。

    通过 webapp 创建的 prototype 任务不接受 —— build 端点只接受由 POST /openapi/creative-lab/keychain/v1/prototype 产生的任务，其它来源一律返回 404。

  • Name
    name
    Type
    string
    Description

    可选的任务名称，仅用于展示。最长 100 个字符。

options

可选的浮雕几何调参字段。每个字段都有合理的默认值 —— 只需传入你想覆盖的字段即可。

  • Name
    badge_shape
    Type
    string
    默认值 circle
    Description

    钥匙扣挂件的外形轮廓。可选值：

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

    钥匙扣外接正方形的边长，单位毫米。取值范围：(0, 400]。

  • Name
    relief_height_mm
    Type
    number
    默认值 2.2
    Description

    浮雕相对底板的最大凸起高度，单位毫米。取值范围：[0, 20]。

  • Name
    relief_offset_mm
    Type
    number
    默认值 0
    Description

    浮雕在挤出前的整体垂直偏移量，单位毫米。取值范围：[0, 20]。

  • Name
    base_thickness_mm
    Type
    number
    默认值 0.1
    Description

    浮雕背后底板的厚度，单位毫米。取值范围：[0, 20]。

  • Name
    has_closed_back
    Type
    boolean
    默认值 true
    Description

    是否将挂件背面闭合为封闭曲面。设为 false 时输出开壳模型。

  • Name
    relief_curve
    Type
    string
    默认值 linear
    Description

    将深度图值映射到浮雕高度的传递曲线。可选值：

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

    传递曲线的形状参数（仅当 relief_curve 为 gamma 时生效）。取值范围：(0, 10]。

  • Name
    invert_depth
    Type
    boolean
    默认值 false
    Description

    反转深度图的解释方向，使更暗的区域对应更高的浮雕。

  • Name
    smoothing
    Type
    number
    默认值 0.24
    Description

    在提取浮雕之前对深度图做平滑的强度。取值范围：[0, 10]。

  • Name
    relief_scale
    Type
    number
    默认值 1.0
    Description

    叠加在 relief_height_mm 之上的垂直缩放系数。取值范围：(0, 10]。

  • Name
    depth_threshold
    Type
    number
    默认值 0.1
    Description

    深度图低通阈值；低于该值的样本被截断为 0。取值范围：[0, 1]。

  • Name
    remove_background
    Type
    boolean
    默认值 true
    Description

    在做浮雕之前自动抠掉 prototype 概念图的背景。

  • Name
    export_resolution
    Type
    integer
    默认值 512
    Description

    导出网格时使用的分辨率。取值范围：[64, 2048]。

output

可选的产物格式选择，默认 glb。

  • Name
    format
    Type
    string
    默认值 glb
    Description

    Build 返回的产物包形式。可选值：

    • glb（默认）—— 返回单个 model.glb，放在 model_urls.glb 下。
    • obj —— 将 model.obj + model.mtl + texture.png 打包成 zip，放在 model_urls.obj 下。
    • zip —— 将生成器产出的全部产物打包成 zip，放在 model_urls.bundle_zip 下。

返回值

响应的 result 字段返回新创建的 keychain build 任务的 id。轮询 查询任务 或订阅 流式更新 直到任务状态变为 SUCCEEDED，即可从 model_urls 中唯一一条条目下载产物。

失败场景

  • Name
    400 - Bad Request
    Description

    请求不合法，常见原因：

    • 缺少参数：input_task_id 必传。
    • UUID 不合法：input_task_id 不是合法 UUID。
    • 父任务未成功：引用的 prototype 任务尚未达到 SUCCEEDED。
    • 没有候选图：prototype 任务虽然成功，但未产出任何候选图。
    • 参数超出范围：options 中某个字段超出了允许的范围或枚举集合。
  • Name
    401 - Unauthorized
    Description

    身份验证失败，请检查 API key。

  • Name
    402 - Payment Required
    Description

    积分不足，无法创建任务。

  • Name
    404 - Not Found
    Description

    引用的 prototype 任务不存在、属于其他用户，或是 webapp 创建的（只接受 API 模式的 prototype 任务）。

  • Name
    429 - Too Many Requests
    Description

    请求超出速率限制。

Request

POST
/openapi/creative-lab/keychain/v1/build
# Stage 2：基于已成功的 prototype 任务串联 build
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 示例
Build 任务会把选中的 prototype 图转成可 3D 打印的钥匙扣模型。
Creative Lab 钥匙扣 build 模型预览图
Build 模型预览
GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id

查询钥匙扣任务

根据合法的任务 id 查询 prototype 或 build 任务。URL 路径必须与任务所属的 stage 一致 —— 通过 /prototype/:id 查询一个 build 任务会返回 404，反之亦然。

响应结构详见 钥匙扣 Prototype 任务对象 和 钥匙扣 Build 任务对象。

参数

  • Name
    id
    Type
    path
    Description

    要查询的 keychain 任务的唯一标识。

返回值

返回 keychain 任务对象，具体形状取决于请求的 stage。

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": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}
DELETE/openapi/creative-lab/keychain/v1/(prototype|build)/:id

删除钥匙扣任务

取消一个 keychain 任务。如果任务仍处于 PENDING，创建时扣除的积分会自动退还。 已经进入 IN_PROGRESS 的任务可以取消但不退款（worker 可能已经在消耗算力）。 已经处于终态（SUCCEEDED、FAILED、CANCELED）的任务无法取消。

URL 路径必须与任务所属的 stage 一致 —— 用 /prototype/:buildId 发 DELETE 会返回 404。

路径参数

  • Name
    id
    Type
    path
    Description

    要取消的 keychain 任务的唯一标识。

返回值

成功时返回 204 No Content，响应体为空。

失败场景

  • Name
    400 - Bad Request
    Description

    任务已经处于终态，无法取消。

  • Name
    404 - Not Found
    Description

    任务不存在、属于其他用户，或所属 stage 与 URL 路径不一致。

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

// 成功时返回 204 No Content，响应体为空。
GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id/stream

流式订阅钥匙扣任务

通过 Server-Sent Events（SSE）实时订阅 keychain 任务更新。URL 路径必须与任务所属的 stage 一致 —— 在 /prototype/:buildId/stream 上打开 stream 会立刻返回一条 event: error、status_code: 404 的 SSE 事件并关闭连接。

参数

  • Name
    id
    Type
    path
    Description

    要订阅的 keychain 任务的唯一标识。

返回值

返回一串 钥匙扣 Prototype 或 钥匙扣 Build 任务对象的 Server-Sent Events。 对 PENDING 或 IN_PROGRESS 状态的任务，事件流只会包含必要的 progress 与 status 字段。

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

// 错误事件示例（stage 不匹配或任务不存在）
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// 消息事件示例：表示任务进度。
// PENDING / IN_PROGRESS 状态下，事件流不包含全部字段。
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": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}
GET/openapi/creative-lab/keychain/v1/(prototype|build)

列出钥匙扣任务

按阶段分页列出当前 API key 名下的钥匙扣任务。URL 路径决定阶段—— /prototype 返回 Prototype 任务；/build 返回 Build 任务。 跨阶段的任务不会出现在另一边的响应中。

路径参数

  • Name
    stage
    Type
    path
    必选
    Description

    必须为 prototype 或 build。集合只返回与 URL 阶段一致的任务—— /prototype 永远不会返回 Build 任务，反之亦然。

查询参数

  • Name
    page_num
    Type
    integer
    默认值 1
    Description

    分页页码。

  • Name
    page_size
    Type
    integer
    默认值 10
    Description

    每页条目数。最大 50。

  • Name
    sort_by
    Type
    string
    默认值 -created_at
    Description

    排序字段。可选值：

    • +created_at：按创建时间升序排序。
    • -created_at：按创建时间降序排序。

返回值

返回按阶段过滤的任务对象分页列表 —— 列出 /prototype 时返回 钥匙扣 Prototype 任务对象， 列出 /build 时返回 钥匙扣 Build 任务对象。

请求

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

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

响应（列出 Prototype 任务）

[
  {
    "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=***"
    ]
  }
]

钥匙扣 Prototype 任务对象

钥匙扣 Prototype 任务是 Meshy 用来跟踪「从源照片生成上色概念图」这一阶段的工作单元。 该阶段的输出通过 input_task_id 链入 Build 阶段。

字段

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    任务类型，值为 creative-lab-keychain-prototype。

  • Name
    name
    Type
    string
    Description

    创建任务时传入的任务名称。未传入时为空字符串。

  • Name
    status
    Type
    string
    Description

    任务状态。可能值：PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED。

  • Name
    progress
    Type
    integer
    Description

    任务进度。任务未开始时为 0，成功后为 100。

  • Name
    created_at
    Type
    timestamp
    Description

    任务创建时间戳，单位毫秒。

    时间戳是自 1970 年 1 月 1 日 UTC 起经过的毫秒数，遵循 RFC 3339 标准。 例如，2023 年 9 月 1 日（星期五）UTC 12:00:00 表示为 1693569600000。 Meshy API 中所有时间戳都遵循此规则。

  • Name
    started_at
    Type
    timestamp
    Description

    任务开始时间戳，单位毫秒。任务未开始时为 0。

  • Name
    finished_at
    Type
    timestamp
    Description

    任务完成时间戳，单位毫秒。任务未完成时为 0。

  • Name
    expires_at
    Type
    timestamp
    Description

    任务结果过期时间戳，单位毫秒。

  • Name
    preceding_tasks
    Type
    integer
    Description

    前面尚未处理的任务数。

    仅当任务状态为 PENDING 时该字段有意义。

  • Name
    task_error
    Type
    object
    Description

    失败任务的错误详情。task_error 对象的完整字段定义详情请参阅 Errors。

  • Name
    consumed_credits
    Type
    integer
    Description

    该任务消耗的积分数。状态为 PENDING、IN_PROGRESS、SUCCEEDED 时存在；FAILED 时返回 0（失败任务会退款）。

  • Name
    image_urls
    Type
    string[]
    Description

    该 prototype 任务产出的概念图候选 URL 数组。目前 API 始终只返回一张候选；保留数组形态，方便未来在不破坏兼容性的前提下扩展到多候选。

钥匙扣 Prototype 任务对象示例

{
  "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 任务对象

钥匙扣 Build 任务是 Meshy 用来跟踪「从已成功的 prototype 任务生成最终钥匙扣 3D 网格」这一阶段的工作单元。Build 在 prototype 的概念图之上运行深度图浮雕 管线，并按调用方指定的格式产出一个网格文件。

字段

  • Name
    id
    Type
    string
    Description

    任务的唯一标识。

  • Name
    type
    Type
    string
    Description

    任务类型，值为 creative-lab-keychain-build。

  • Name
    name
    Type
    string
    Description

    创建任务时传入的任务名称。未传入时为空字符串。

  • Name
    status
    Type
    string
    Description

    任务状态。可能值：PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED。

  • Name
    progress
    Type
    integer
    Description

    任务进度。任务未开始时为 0，成功后为 100。

  • Name
    created_at
    Type
    timestamp
    Description

    任务创建时间戳，单位毫秒。

  • Name
    started_at
    Type
    timestamp
    Description

    任务开始时间戳，单位毫秒。

  • Name
    finished_at
    Type
    timestamp
    Description

    任务完成时间戳，单位毫秒。

  • Name
    expires_at
    Type
    timestamp
    Description

    任务结果过期时间戳，单位毫秒。

  • Name
    preceding_tasks
    Type
    integer
    Description

    前面尚未处理的任务数。仅当任务状态为 PENDING 时有意义。

  • Name
    task_error
    Type
    object
    Description

    失败任务的错误详情。task_error 对象的完整字段定义详情请参阅 Errors。

  • Name
    consumed_credits
    Type
    integer
    Description

    该任务消耗的积分数。FAILED 时返回 0（失败任务会退款）。

  • Name
    model_urls
    Type
    object
    Description

    按产物名称作为 key 的下载 URL 字典。始终只包含一条 —— 即 build 请求中 output.format 所指定的格式，key 与请求的格式名一致：

    • Name
      glb
      Type
      string
      Description

      GLB 文件的下载 URL。当 output.format 为 glb（默认）时返回此 key。

    • Name
      obj
      Type
      string
      Description

      包含 model.obj、model.mtl 与 texture.png 的 zip 包下载 URL。当 output.format 为 obj 时返回此 key。

    • Name
      bundle_zip
      Type
      string
      Description

      生成器产出的全部产物打包成 zip 后的下载 URL。当 output.format 为 zip 时返回此 key。

钥匙扣 Build 任务对象示例

{
  "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": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}