异步与轮询
创建调用会立即返回一个资产及其任务状态。请轮询至任务完成，或注册一个 Webhook。
1 · POST
创建
→ id · taskStatus 0
→
2 · 轮询 / webhook
等待
0 → 1 → 2 / 3
→
3 · files
结果
签名 URL
↺
按 id 串联
精修
remesh · texture · rig
0 排队中1 处理中2 成功3 失败
任务生命周期
| taskStatus | 状态 | 终止? |
|---|---|---|
| 0 | 排队中 — 已受理，正在等待引擎。 | 否 |
| 1 | 处理中 — 生成正在运行，progress 从 0 → 100 递增。 | 否 |
| 2 | 成功 — 结果保存在 files 中。 | 是 |
| 3 | 失败 — 积分已退还；请查看 errorCategory / errorDetail。 | 是 |
让轮询循环面向未来 请将
0 或 1 以外的任何值都视为终止状态(taskStatus >= 2)。这样即使日后新增了状态值，循环也永远不会一直等待下去。成功后，files 中会保存输出的短期签名 URL — model(GLB),以及在适用时的 image、thumbnail 和 textures。签名会过期，请尽快获取。
GET /v1/assets/{id} · succeeded
{ "success": true, "data": {
"id": "019f3a39-…",
"type": "model_3d",
"taskStatus": 2,
"progress": 100,
"files": {
"model": "https://…/model.glb?signed",
"thumbnail": "https://…/thumb.webp?signed"
}
} }轮询至完成
poll
curl https://api.picoberry.ai/v1/assets/019f3a39-… \
-H "Authorization: Bearer pb_live_xxx"import time, requests
while True:
a = requests.get(f"https://api.picoberry.ai/v1/assets/{id}", headers=headers).json()["data"]
if a["taskStatus"] in (2, 3): break
time.sleep(4)
model_url = a["files"]["model"]let a;
do {
a = (await (await fetch(`${BASE}/v1/assets/${id}`, { headers })).json()).data;
if (a.taskStatus < 2) await new Promise(r => setTimeout(r, 4000));
} while (a.taskStatus < 2);
const modelUrl = a.files.model;设置足够宽裕的超时 一个 3D 任务通常耗时约 60–120 秒。请每隔几秒轮询一次,并在判定任务卡住之前,持续轮询远超过一分钟。
串联下一步
已完成资产的 id 就是每一次精修的输入 — 无需重新上传,也无需转换格式。后处理任务同样是异步的:每个任务都会返回一个新的资产 id,你用完全相同的方式轮询它,而且绝不会改动原始资产。