2026-09-26개발자

영상 생성 API 동기 vs 비동기: Sume의 네 가지 제출 모드

Sume의 제출 모드는 async, sync, subscribe, webhook입니다. sync와 subscribe는 최대 30초만 기다리므로, 영상은 async로 제출해 폴링하거나 웹훅을 받으세요.

읽는 시간 5분Sume

Sume에서 영상을 생성할 때는 sync가 아니라 async나 웹훅을 쓰세요. sync는 요청을 최대 30초까지만 열어 두는데, 영상 작업은 대부분 그보다 오래 걸립니다. 제출 모드는 Job의 결과를 알게 되는 방식만 바꿀 뿐 Job 자체나 비용, 실행 시간은 바꾸지 않으며, POST /v1/videos는 항상 비동기입니다.

이 규칙은 Sume의 Job과 결과 (영문) 페이지에서, 경로별 세부 사항은 이미지 생성 (영문), Video Generation (영문), 라이브 OpenAPI 레퍼런스에서 가져왔으며, 모두 2026-09-26에 확인했습니다.

네 가지 제출 모드는 무엇인가요?

제출 엔드포인트는 OpenAPI 스키마에 문서화된 곳에서 mode, webhook_url, wait_timeout_seconds를 받습니다. POST /v1/videos는 이 셋 중 어느 것도 받지 않습니다. 아래 경로 섹션을 참고하세요.

mode를 생략하면 async가 됩니다. 단, POST /v1/images는 기본값이 sync입니다. mode 없이 webhook_url(또는 별칭 callback_url)을 보내면 webhook이 됩니다.
Sume의 Job 봉투로 응답하는 경로에서는 모든 모드가 첫 응답에 Job ID를 돌려줍니다. 2xx 봉투는 Job이 끝났다는 뜻이 아니라 Job이 존재하고 유료 작업이 진행 중이라는 뜻입니다. 끝났는지는 terminal과 result_ready로 확인하세요.

Job과 결과 (영문) 기준 통신 모드, 2026-09-26 확인.
모드	첫 응답	서버 대기	다음에 할 일
`async`(기본값)	Job 봉투와 폴링 URL이 담긴 `202`	아니요	`terminal`이 true가 될 때까지 `status_url`을 폴링한 뒤 `result_url` 읽기
`sync`	종료 상태를 최대 `wait_timeout_seconds`까지 기다린 뒤 보내는 같은 봉투	최대 30초. waiter 용량이 없으면 더 짧음	종료 상태면 응답에서 Job 읽기. 아니면 폴링하고 다시 제출하지 않기
`subscribe`	`sync`와 동일	`sync`와 같음	`sync`와 같음
`webhook`	Job 봉투가 담긴 `202`. 콜백은 저장됨	아니요	서명된 종료 콜백을 기다리고, 백업으로 폴링 유지

30초 대기는 무엇을 제한하나요?

wait_timeout_seconds는 0–30으로 클램프됩니다. 이 값은 Job이 걸릴 수 있는 시간이 아니라 HTTP 요청이 블로킹되는 시간을 제한합니다. 이미지 Job은 그 안에 끝나는 경우가 많지만, 영상, 아바타 영상, 페이스 스왑 Job은 대개 그렇지 않습니다.

대기 예산이 소진되거나, API 프로세스에 waiter 용량이 없어 대기를 건너뛰어도 응답은 여전히 Job ID가 담긴 2xx입니다. 여기에는 status_url, result_url, events_url, cancel_url과 sync 객체가 담깁니다. 대기 소진은 접수 실패가 아닙니다.

sync 객체는 어떻게 읽나요?

sync는 대기가 어떻게 끝났는지 알려 줍니다. async와 webhook 응답에서는 null입니다.

종료 상태가 아니라면 GET status_url로 이어 가고, next_poll_after_seconds가 있으면 그 값을 따르세요.
같은 의도로 새 유료 Job을 제출하지 마세요. 제출 자체를 재시도한다면 같은 Idempotency-Key를 재사용해 재시도가 원래 Job을 돌려받게 하세요. AI 영상 API 멱등성 키를 참고하세요.

Job과 결과 (영문)와 OpenAPI 레퍼런스 기준 `sync` 객체, 2026-09-26 확인.
필드	의미
`timed_out`	Job이 종료 상태에 도달하기 전에 대기가 반환됨
`capacity_exhausted`	프로세스별 waiter 예산이 가득 차 Sume가 블로킹 대기를 건너뜀. 대신 `status_url`을 폴링
`terminal`	Job이 `completed`, `failed`, `canceled` 중 하나
`succeeded`, `failed`, `canceled`	종료 상태마다 하나씩. `succeeded`는 `completed`를 뜻함
`result_ready`, `completed`	`result_url`에 GET하면 완료된 결과를 받을 수 있음. `completed`는 하위 호환용 성공 플래그
`wait_timeout_seconds`	요청한 대기 예산

subscribe는 스트림인가요?

아닙니다. sync와 subscribe는 같은 제한 waiter를 돌리고 같은 봉투를 돌려줍니다. subscribe는 다른 큐 API에서 넘어온 클라이언트가 이 이름을 먼저 찾기 때문에 있습니다. 오래 유지되는 구독도, 이벤트 스트림도, 더 긴 대기도 아니며, 진행 이벤트도 주지 않습니다. 현재 Developer API에는 SSE나 WebSocket 전송이 없고, GET /v1/jobs/{id}/events는 pull 스냅샷입니다.

Sume에서 이 단어는 세 가지를 뜻하며, 어느 것도 푸시 스트림이 아닙니다.

Job mode: "subscribe": sync의 별칭이며, 상한은 30초입니다.
SDK subscribeFormatRun(): Format 실행을 만든 뒤 클라이언트 쪽에서 몇 분 동안 폴링합니다.
실행의 communication.mode: 값은 async와 webhook뿐이며 둘의 동작은 같습니다. 전달을 실제로 켜는 것은 webhook_url을 넣는 일입니다.

어떤 경로가 다르게 동작하나요?

POST /v1/videos는 항상 비동기입니다. 요청 스키마에 mode, webhook_url, wait_timeout_seconds가 없습니다. Job ID와 폴링 URL을 담아 202로 응답하며, 종료 웹훅용으로 callback_url을 받습니다.

POST /v1/images는 기본값이 sync이고, 이 경로에서는 wait_timeout_seconds의 기본값이 30입니다. 대기 안에 이미지가 끝나면 이미지와 함께 200을, 대기 안에 생성이 실패하면 502를, 대기가 끝나거나 mode: "async"(또는 webhook_url과 함께 "webhook")를 보내면 표준 Job 봉투와 함께 202를 돌려줍니다. 본문 형태가 아니라 상태 코드를 확인하세요. 다음 요청은 Job 봉투를 곧바로 요청합니다.

curl -X POST "https://api.sume.com/v1/images" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sume/auto",
    "prompt": "Product hero shot of a matte black bottle on marble",
    "mode": "async"
  }'

영상에는 어떤 모드를 써야 하나요?

sync와 subscribe는 계속 지원되며 없어지지 않습니다. 하지만 30초를 넘길 수 있는 작업에는 아래 두 가지 방법 중 하나를 쓰세요. 직접 정하는 마감 시간을 어디에 둘지는 AI 영상 API 타임아웃에서 다룹니다.

async와 폴링 루프: 대기가 클라이언트 안에서 일어나므로, 필요하면 몇 분이라도 기다릴 수 있습니다. 영상 생성 Job 폴링하는 방법을 참고하세요.
webhook, 또는 POST /v1/videos의 callback_url: Sume는 종료 이벤트(job.completed, job.failed, job.canceled)만 HMAC SHA-256으로 서명해 공개 HTTPS URL로 보냅니다. 누락된 전달에 대비해 폴링은 유지하세요. 서명된 웹훅을 참고하세요.

출처

작성자 Sume