비동기 & 폴링
생성 호출은 자산과 작업 상태를 담아 즉시 응답합니다. 완료될 때까지 폴링하거나 웹훅을 등록하세요.
1 · POST
생성
→ id · taskStatus 0
→
2 · 폴링 / 웹훅
대기
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} · 성공
{ "success": true, "data": {
"id": "019f3a39-…",
"type": "model_3d",
"taskStatus": 2,
"progress": 100,
"files": {
"model": "https://…/model.glb?signed",
"thumbnail": "https://…/thumb.webp?signed"
}
} }완료될 때까지 폴링
폴링
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를 반환하며, 원본은 절대 변경하지 않습니다.