작업 기다리기

폴링, 웹훅, 종료 상태 확인입니다.

작업의 종류

종류만든 곳읽는 곳기다리는 법
이미지 작업POST /v1/imagesGET /v1/images/<id>폴링 또는 웹훅
영상 작업POST /v1/videosGET /v1/videos/<id>폴링 또는 웹훅
오디오 작업POST /v1/audioGET /v1/audio/<id>폴링 또는 웹훅
캔버스 실행MCP video_runvideo_run action get폴링

폴링

진행 중인 작업의 응답에 poll_after_seconds가 있으면 그만큼 기다렸다가 다시 조회합니다. 이미지는 응답 최상위(5초), 오디오는 job 안(10초)에 있습니다. 영상 응답에는 이 값이 없으니 10초 간격으로 부르세요. 캔버스 실행은 10초입니다. 이보다 촘촘히 부르면 읽기 한도만 소모합니다.
기다리는 루프 (종료 상태 확인) — js
// 조회 응답은 모두 body.job.status 에 상태가 있습니다.
async function waitFor(get, isDone) {
  for (;;) {
    const body = await get();
    if (isDone(body)) return body;
    const wait = body.poll_after_seconds ?? body.job?.poll_after_seconds ?? 10;
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
}
​
const imageDone = (body) => ["done", "failed"].includes(body.job.status);
const otherDone = (body) => ["succeeded", "failed"].includes(body.job.status);

이미 가진 작업 id

접수 응답을 잃었다면 목록 경로(GET /v1/images, GET /v1/videos)로 최신순 작업을 찾습니다. 오디오에는 목록 경로가 없습니다. 같은 idempotencyKey와 같은 본문으로 다시 접수하면 같은 작업을 돌려주므로 중복 과금 없이 되찾을 수 있습니다.

끝났다고 성공은 아닙니다

종료 상태는 성공과 실패 둘입니다. 항상 상태를 확인하세요. 이미지는 done, 영상과 오디오는 succeeded가 성공이고 모두 failed가 실패입니다. 취소된 작업도 failed이고 사유 코드가 canceled입니다. 영상의 stalled가 true면 실행 제한 시간을 넘긴 작업이라는 표시입니다. 결과 링크는 15분 뒤 만료되므로 필요할 때 다시 조회합니다. 실패 코드와 환불은 오류와 지출에 있습니다.

웹훅 우선

작업이 많거나 오래 걸리면 폴링보다 웹훅이 낫습니다. 웹훅은 종료 사실만 알려 주고 결과 링크는 담지 않으므로 알림을 받은 뒤 작업을 한 번 조회해 결과를 가져옵니다. 직접 취소한 작업은 알림이 없으니 취소는 조회로 확인합니다. 알림이 늦거나 실패할 수 있으니, 오래 소식이 없는 작업은 가끔 조회로 확인하세요.

관련