非同期とポーリング
生成呼び出しは、アセットとそのタスク状態を返してすぐに応答します。完了するまでポーリングするか、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秒かかります。数秒間隔でポーリングし、処理が停止したと判断する前に1分を十分に超えてポーリングを続けてください。
次のステップにつなげる
完了したアセットのidは、あらゆる仕上げ処理の入力になります — 再アップロードも、形式の変換も不要です。後処理も非同期です。各処理はまったく同じ方法でポーリングする新しいアセットidを返し、元のアセットは決して変更しません。