自动绑定与动画
POST/v1/assets/{id}/animate
为人形(使用 PB Animation 时也包括四足及其他角色)自动绑定骨骼,并可按需将预设片段重定向到模型上。无需手动绘制权重。
路径中的 {id} 是源模型。结果(经过绑定的网格,若使用 -rig-animate 则还带有动画)会写入一个新资产。
参数
| 参数 | 说明 |
|---|---|
| engine可选 string | 使用哪个绑定引擎,例如 tripo-rig-animate、tripo-rig、meshy-rig-animate、meshy-rig、pb-rig、pb-rig-animate、pb-retarget。-rig 引擎仅进行绑定;-rig-animate 引擎在绑定的同时应用预设片段;-retarget 引擎只把片段应用到已由同一引擎绑定好的资产上({id} 即该资产)。省略则使用默认值(tripo-rig)。列表与积分费用:GET /v1/models?category=animate。 |
| preset可选 string | -rig-animate 和 -retarget 引擎使用的动画预设 id(例如 walk),最多 64 个字符。请从同一引擎的 GET /v1/animations 中选择——引擎前缀会自动加上,带有其他引擎前缀(preset:、meshy:、pb:)的预设会返回 400。PB 引擎只接受 GET /v1/animations?engine=pb 列表中的 id,其他 id 会返回 400。pb-rig-animate 和 pb-retarget 必须带预设;仅绑定的 pb-rig 不接受预设。若只需绑定,请使用 -rig 引擎——向 Tripo、Meshy 的 -rig-animate 引擎不带预设发送虽然也只做绑定,但按 -rig-animate 的价格计费。 |
| body可选 string | 仅限 PB Animation——要绑定对象的身体类型:humanoid(默认)、quadruped(四足)或 other(其他)。只有会新建骨骼的 pb-rig 和 pb-rig-animate 接受此参数。传给其他引擎会返回 400:Tripo、Meshy 只绑定人形,pb-retarget 沿用源资产绑定时的身体类型。目前 quadruped 和 other 仅支持绑定——请使用 pb-rig(参见 PB Animation)。 |
| license可选 string | 结果的使用权限。默认为私有(保留所有权利)。 |
| callbackUrl可选 string | 将完成的资产推送到您的服务器,而非轮询获取。参见 Webhook。 |
源模型必须可绑定 自动绑定需要清晰的人形或动物形态。道具、场景和抽象形状会返回
400 及 error.code 13008 而失败。请求
请求
curl -X POST https://api.picoberry.ai/v1/assets/019…/animate \
-H "Authorization: Bearer pb_live_xxx" -H "Content-Type: application/json" \
-d '{"engine":"tripo-rig-animate","preset":"walk"}'requests.post(f"{BASE}/v1/assets/{id}/animate", headers=headers,
json={"engine": "tripo-rig-animate", "preset": "walk"})await fetch(`${BASE}/v1/assets/${id}/animate`, { method: "POST",
headers: { ...headers, "Content-Type": "application/json" },
body: JSON.stringify({ engine: "tripo-rig-animate", preset: "walk" }) });PB Animation
PicoBerry 自研的绑定器会按 body 选择的身体类型为骨骼命名,因此不止能绑定人形:
- 人形 —
pb-rig仅绑定,pb-rig-animate绑定并应用一个动作。要再加动作,请对已绑定的资产调用pb-retarget——它沿用该骨骼,不会重新绑定。 - 四足 — 对
pb-rig传"body": "quadruped"。四足动作尚未开放(与 picoberry.ai 相同),因此四足目前仅支持绑定:对四足身体或四足骨骼请求动作,或传入quad_*动作,都会在扣除积分之前返回400。 - 其他 — 其余形态对
pb-rig传"body": "other"。它没有专属动作。
PB 动作从 GET /v1/animations?engine=pb 中选择——与 picoberry.ai 上的列表相同。不在列表中的动作会在扣除积分之前返回 400。
四足绑定
curl -X POST https://api.picoberry.ai/v1/assets/019…/animate \
-H "Authorization: Bearer pb_live_xxx" -H "Content-Type: application/json" \
-d '{"engine":"pb-rig","body":"quadruped"}'requests.post(f"{BASE}/v1/assets/{id}/animate", headers=headers,
json={"engine": "pb-rig", "body": "quadruped"})await fetch(`${BASE}/v1/assets/${id}/animate`, { method: "POST",
headers: { ...headers, "Content-Type": "application/json" },
body: JSON.stringify({ engine: "pb-rig", body: "quadruped" }) });动画预设
GET/v1/animations?engine=tripo|meshy|pb
列出某个引擎可用的预设片段。预设是引擎专属的:Tripo 的预设无法在 Meshy 或 PB 引擎上运行,因此请始终从用于生成动画的同一引擎中选择。
请求
curl "https://api.picoberry.ai/v1/animations?engine=tripo" \
-H "Authorization: Bearer pb_live_xxx"requests.get("https://api.picoberry.ai/v1/animations", headers=headers,
params={"engine": "tripo"})await fetch(`${BASE}/v1/animations?engine=tripo`, { headers });响应 · 200
{ "success": true, "data": [
{ "id": "walk", "name": "Walk", "category": "Movement" },
{ "id": "run", "name": "Run", "category": "Movement" },
{ "id": "slash", "name": "Slash", "category": "Combat" }
] }每个预设都带有 id(在 /animate 中作为 preset 传入)、用于显示的 name 以及 category。类别为 Movement、Combat、Emotion、Dance、Sports、Daily 或 Gesture 之一。
使用 engine=pb 时返回 PB Animation 的动作——与 picoberry.ai 上显示的列表相同,那里隐藏的动作这里也没有。每个动作都带有 body,即该动作所适用骨骼的身体类型。由于四足动作尚未开放,目前列表中的动作均为 humanoid。PB 动作有自己的类别(Walk、Run、Knight、Dance …)。
响应 · 200 · engine=pb
{ "success": true, "data": [
{ "id": "walk", "name": "Walk", "category": "Movement", "engine": "pb", "body": "humanoid" },
{ "id": "run", "name": "Run", "category": "Movement", "engine": "pb", "body": "humanoid" }
] }响应
响应 · 200
{ "success": true, "data": { "id": "019…", "taskStatus": 0 } }轮询 GET /v1/assets/{id},直到 taskStatus 变为 2;完成后的 files.model 中包含绑定和已烘焙的片段。参见 异步与轮询。
预设是引擎专属的 Tripo 的预设无法在 Meshy 或 PB 引擎上运行,反之亦然。请从用于生成动画的同一引擎中选择预设。