AI 영상 생성 API 진행 상황 업데이트: 푸시 스트림 없이

오래 걸리는 Sume 영상 작업의 진행 상황을 보여 주려면 API가 공개하는 것을 폴링하세요. 생성 Job의 수명주기 타임라인은 GET /v1/jobs/{id}/events, Format 실행의 phase 타임라인은 GET /v1/format-runs/{run_id}/events, 아바타 영상의 장면은 scene_previews에서 읽습니다. SSE나 WebSocket 스트림은 없으며, Sume는 Job별 ETA를 노출하지 않습니다.

자세한 내용은 2026-09-26에 확인한 Sume 문서 Job과 결과 (영문), 실행과 결과 (영문), 실행 기다리기 (영문)와 Sume API 레퍼런스에서 가져왔습니다.

진행 상황을 스트리밍하는 API가 있나요?

없습니다. 현재 Developer API에는 SSE나 WebSocket 전송이 없고, GET /v1/jobs/:id/events는 스트림이 아니라 pull 스냅샷입니다. Format 실행에도 진행 상황을 푸시하는 채널은 없습니다. 웹훅이 푸시하는 것은 진행 상황이 아니라 완료입니다.

• mode: "subscribe"는 sync의 별칭입니다. 최대 30초 동안 한 번 기다릴 뿐이며, 진행 이벤트는 없습니다.
• Job 웹훅은 종료 상태 전용으로, job.completed, job.failed, job.canceled뿐입니다. 진행 상황 웹훅이나 부분 웹훅은 없습니다.
• Agent Completions: 스트리밍은 아직 제공하지 않습니다.

생성 Job은 실행 중에 무엇을 보여 줄 수 있나요?

Job의 events_url인 GET /v1/jobs/{id}/events를 폴링하세요. 정제된(sanitized) 수명주기 타임라인을 반환합니다. 각 이벤트에는 type, source(sume 또는 webhook), status(info, pending, processing, succeeded, failed, canceled, retrying 중 하나), message, created_at이 담깁니다. 원본 프로바이더 task id와 프로바이더 URL은 빠져 있습니다.

상태 페이로드는 무엇을 더 알려 주나요?

GET /v1/jobs/{id}/status에는 진행 상황 화면이 분기할 때 쓰는 필드가 들어 있습니다. 폴링 루프 자체는 AI 영상 Job 상태를 폴링하는 방법에서 다룹니다.

• terminal과 result_ready: terminal이면 폴링을 멈추고, result_ready가 true가 되면 result_url을 읽으세요.
• next_poll_after_seconds: 다음 폴링까지 권장하는 최소 대기 시간이며, 종료 상태가 되면 null입니다.
• queue.state: waiting, deferred, runtime_unavailable, processing, completed, failed, canceled 중 하나이며, 프로바이더 중립적인 reason과 available_at이 함께 옵니다. available_at은 Job을 픽업하거나 재시도할 수 있는 가장 이른 시각입니다.
• queue.position: Sume가 실제 큐 순위를 계산하기 전까지는 null입니다. API는 가짜 위치를 반환하지 않습니다.
• logs_available: false입니다. 수명주기 진단 정보는 인라인 로그 대신 events_url로 제공됩니다.
• next_action: 실패하거나 취소된 Job에서는 inspect_events이므로, 실패 화면에서 이벤트 타임라인을 보여 줄 수 있습니다.

Format 실행의 진행 상황은 어떻게 보여 주나요?

영수증의 events_url인 GET /v1/format-runs/{run_id}/events를 읽으세요. 단계(preparing, running, finalizing)를 오래된 것부터 나열하며, 각 단계에는 at과 status가 있고 단계가 스스로 시간을 측정했다면 duration_ms도 있습니다. 에이전트 출력, 도구 호출, 샌드박스 내부 정보는 여기에 공개되지 않습니다. 마지막 항목의 at이 몇 분 동안 갱신되지 않으면 그 실행은 느린 것이 아니라 멈춘 것입니다. 그다음 일은 AI 영상 생성에 걸리는 시간에서 다룹니다.

TypeScript에서는 timeline: true를 주면 타임라인이 snapshot.timeline으로 onStatus에 전달되고, 기다리고 있지 않은 실행의 타임라인은 getFormatRunTimeline으로 읽습니다. 이 옵션을 켜면 대기 중 요청 빈도가 두 배가 되며, 타임라인 읽기가 실패하면 대기를 끝내지 않고 이전 타임라인을 유지합니다. Action과 Agent Completion 실행은 events_url: null을 보고합니다.

import { createSumeClient, subscribeFormatRun } from "@sume-com/sdk";

const client = createSumeClient({ apiKey: process.env.SUME_API_KEY! });

const run = await subscribeFormatRun({
  client,
  path: { handle: "acme", slug: "product-promo" },
  body: { input: { product_url: "https://example.com/p/123" } },
  timeline: true,
  onStatus: (status, snapshot) => {
    const phase = snapshot.timeline?.at(-1);
    console.log(status, phase?.phase, phase?.status);
  },
});

아바타 영상의 장면 프리뷰는 어떻게 보여 주나요?

Avatar Video Job은 GET /v1/jobs/{id}로 받는 Job 레코드에 scene_previews를 담고 있습니다. API 레퍼런스는 이 필드를 상태 폴링용으로 공개해도 안전한 Avatar Video 장면 프리뷰 메타데이터라고 설명하며, 프롬프트 텍스트, 대사, 프로바이더 세부 정보는 빠져 있습니다. 각 항목에는 index, status(queued, processing, ready, failed, canceled 중 하나), 그리고 가능한 경우 그 장면의 첫 프레임을 담은 preview_image_url이 있습니다. video_inputs[]에서 여러분이 지정한 장면 id와 start_time_seconds, end_time_seconds, duration_seconds도 담길 수 있습니다.

제안하는 UI는 이렇습니다. 장면마다 status를 보여 주고, preview_image_url이 채워지면 그 장면의 스틸도 보여 주세요. 프리뷰 스틸에는 자막이 절대 들어가지 않습니다. 전체 렌더 비용을 내기 전에 스틸을 승인하려면 아바타 영상 프리뷰를 사용하세요.

진행 상황 UI가 약속하면 안 되는 것은 무엇인가요?

UI에는 API가 보고하는 것만 담으세요.

• ETA나 큐 위치입니다. Sume는 큐 개수와 남은 수락 용량을 노출할 뿐, Job별 큐 위치나 ETA는 노출하지 않습니다.
• 로그나 에이전트 출력입니다. Job 이벤트는 정제되어 있고, Format 타임라인은 로그 스트림이 아닙니다.
• 실행 중간의 웹훅입니다. 웹훅은 마지막에 도착하므로, 누락된 전달에 대비해 폴링을 백업으로 계속 쓸 수 있게 두세요.
• Action이나 Agent Completion 실행의 단계입니다. 이 실행들에는 타임라인이 아니라 상태가 있습니다.
• 초 단위 업데이트입니다. 실행 문서는 매초 폴링해도 얻는 것이 없고 읽기 예산만 쓴다고 말합니다. 읽기에는 쓰기 숫자의 마흔 배인 분당 예산이 따로 있어 폴링이 생성 요청의 예산을 잡아먹을 수는 없지만, timeline: true는 그래도 읽기를 두 배로 늘립니다.