用代码给 3D 模型自动绑骨

快速开始#

从登录到拿到绑好骨骼的模型，只需三步。需要 Node.js 18.17 或更新版本。

1. 01

   创建密钥

   用 Google 登录你的 afk.ai 账号，在 API keys（API 密钥）下创建一个。它以 afk_ 开头，只显示一次；随时可以在那里吊销。不要把它放进网页或供人下载的应用里。

2. 02

   放进环境变量

   shell复制

   export AFK_API_KEY=afk_...   # from afk.ai/account#api

3. 03

   给模型绑骨

   clinode.jsclaude codemcp.json复制

   npx afk-rig knight.glb --type human -o knight.rigged.glb

   绑骨在我们的 GPU 上运行，通常需要 1 到 2 分钟；CLI 和客户端会等待完成。使用 MCP 客户端时，可以这样问：“把 models/fox.glb 按四足动物绑骨”。

从图片生成#

还没有 3D 模型？那就发送一张角色图片：一次调用会根据图片生成带纹理的 3D 模型，然后为它绑骨并加上该体型的全部动画，都在一个 GLB 里，约需 2 到 3 分钟。

每个角色从你的积分中扣 25¢：包含 3D 模型、骨骼绑定和全部动画；失败则退款。免费绑骨不包括角色生成。任务的 billing 会显示扣费情况：运行时为 held，然后是 charged 或 refunded；CLI 会打印扣了多少以及剩余积分。

npx afk-rig character knight.png -o knight.glb
# Done in 135 s: 593 animations, 15.2 MB, charged $0.25 from your API credits. $4.75 of credits left.

最好是一张清晰、光线充足的图片，只有一个完整的角色，背景干净。模型的纹理（颜色、金属度和粗糙度）会与图片匹配；闲置一段时间后的第一个请求可能需要最多 5 分钟，因为 GPU 需要启动。使用 MCP 客户端时，可以这样问：“用 art/knight.png 生成一个绑好骨骼的角色”。更多内容见我们的图片转绑骨角色 API 指南。

体型#

通过 --type 传入其中一种。afk.ai 会匹配为它打造的骨架、计算蒙皮权重，并加上为该骨架制作的全部动画：所有类型共 933 个。afk-rig types <type> 会列出某个类型的动画。

human593 个片段

人、机器人、僵尸，任何用两条腿站立的角色。含手指。

fox128 个片段

狗、猫、狐狸、狼

horse22 个片段

马、鹿、牛

bird19 个片段

翅膀加两条腿

dragon20 个片段

翅膀加四条腿

kaiju18 个片段

直立，带尾巴

spider18 个片段

六条或八条腿，没有翅膀

snake15 个片段

没有腿，一条长脊柱

fish16 个片段

鱼、鲨鱼、鲸

CLI#

用 npx afk-rig 运行，或用 npm i -g afk-rig 全局安装。进度输出到 stderr，写出的文件路径输出到 stdout，便于在脚本中组合使用。

选项

退出码

Node.js#

同一个包也是一个带类型定义的客户端：import { AfkRig } from 'afk-rig'。new AfkRig() 会读取 AFK_API_KEY，也可以传入 { apiKey }。

分步操作

import { AfkRig } from 'afk-rig'

const afk = new AfkRig()

const started = await afk.startRig('fox.glb', { type: 'fox', facing: 'auto' })
// { id: 'rig_…', status: 'queued', billing: { charge: 'credits', state: 'held', … } }

const done = await afk.waitForRig(started.id, {
  onUpdate: (job) => console.log(job.status, job.stage), // rigging skeleton, rigging fit, …
})

const glb = await afk.downloadRig(done.id) // Uint8Array, for 24 hours

错误为 AfkRigError，包含 HTTP status、来自下表的 code，以及被限流时以秒为单位的 retryAfter。

MCP 服务器#

npx -y afk-rig mcp 会把它作为 stdio 上的 MCP 服务器运行，这样 Claude Code、Cursor、Windsurf、Claude Desktop 和其他 MCP 客户端就能给它们生成的模型绑骨。在它的环境变量中提供 AFK_API_KEY。

claude mcp add afk-rig -e AFK_API_KEY=afk_... -- npx -y afk-rig mcp

{
  "mcpServers": {
    "afk-rig": {
      "command": "npx",
      "args": ["-y", "afk-rig", "mcp"],
      "env": { "AFK_API_KEY": "afk_..." }
    }
  }
}

工具

绑骨生命周期#

绑骨是一个异步任务。上传模型后会立即拿到它的 id；它会依次经过以下状态，CLI 和客户端会替你轮询。

付费绑骨运行时 billing.state 为 held，文件就绪后为 charged，失败则为 refunded，所以失败的绑骨不花一分钱。billing.charge 说明付费方式：free、rerig、credits 或 character。从图片生成的角色在进入绑骨阶段之前处于 generating（正在生成它的 3D 模型）。一个已完成的任务，用 afk-rig status <id> --json 打印出来是这样的：

{
  "id": "rig_Xq3v9KfL2mTz8RbA1cWd",
  "status": "succeeded",
  "stage": null,
  "type": "human",
  "file": "knight.glb",
  "animations": "all",
  "facing": null,
  "created_at": "2026-10-26T17:02:11Z",
  "finished_at": "2026-10-26T17:03:35Z",
  "billing": { "charge": "credits", "amount_usd": "0.05", "state": "charged" },
  "error": null,
  "result": {
    "download_url": "https://…/v1/rigs/rig_Xq3v9KfL2mTz8RbA1cWd/model.glb",
    "bytes": 7412032,
    "animations": 593,
    "expires_at": "2026-10-27T17:03:35Z"
  }
}

错误#

被 API 拒绝的请求会返回 HTTP 状态码和一个 code；这些请求不收费。

绑骨失败时

已被接受但无法绑骨的任务，最终会以 status: "failed" 结束，并在 error.code 中给出以下之一。不收费。

限制#

价格#

每次绑骨 5¢，统一价格。一次绑骨就是全部产出：骨架、蒙皮权重和该体型的全部动画。从图片生成角色为 25¢。不按动画收费，无需订阅。

每月花费

与其他绑骨 API 对比#

我们找到的所有绑骨 API 中，按量付费价格最低。以下是公开的 API 价格，积分已按各家常规方案换算成美元。如果预付一年，Ludo.ai 的单纯绑骨更便宜；而一个带十个动画的人形角色，在这里比我们算过的任何其他 API 都便宜。计算过程见我们的自动绑骨 API 价格对比。

价格核实于 2026年10月，来自各家自己的页面，仅计常规方案（不含新用户优惠）：Ludo.ai、Meshy API、Meshy 方案、Uthana、Tripo、Anything World、Mixamo FAQ。价格会变动，决定前请先核实。

常见问题#