AI 영상 생성을 코드로 자동화하는 방법

AI 영상 생성을 자동화하려면 원하는 영상이 이미 나오는 브리프를 재사용할 수 있는 레시피로 저장하고, 그 레시피를 코드에서 시작한 뒤, 완성된 영상은 화면을 지켜보는 대신 웹훅으로 받으세요. 각 실행을 무엇이 시작할지는 작업에 따라 다릅니다. 제품 안에서 일어난 이벤트일 수도, 차례로 처리할 목록일 수도, 시계일 수도 있습니다.

아래 Sume 관련 내용은 2026-09-27에 확인한 Format API (영문) 문서와 실행 만들기 (영문), 대량 실행, Scheduled 페이지에서 가져왔습니다.

자동화된 영상 파이프라인에는 무엇이 필요한가요?

어떤 서비스가 영상을 만들든 다섯 가지가 필요합니다.

• 고정된 레시피. 스타일, 길이, 규칙은 모든 실행에서 같고 데이터만 바뀝니다.
• 트리거. 무언가 일어났을 때 호출하는 백엔드, 목록을 처리하는 배치 작업, 또는 스케줄입니다.
• 실행별 지출 한도. 비싼 단계를 승인해 줄 사람이 없기 때문입니다.
• 결과 채널. 영상이 준비됐다고 시스템에 알려 주는 웹훅이며, 폴링을 백업으로 둡니다.
• 재시도 규칙. 네트워크 타임아웃 때문에 두 번째 유료 영상이 시작되어서는 안 됩니다. 멱등성 키를 쓰면 재시도한 생성 요청이 첫 번째 실행을 돌려줍니다.

잘 되는 프롬프트를 코드에서 호출하려면 어떻게 하나요?

Sume에서는 그 레시피가 Format입니다. 백엔드가 이름으로 호출하는, 저장된 제작 레시피입니다. Format은 사람이 초안을 검토하는 에이전트 채팅에서 작성하고, 결과가 제대로 나오면 에이전트에게 레시피를 저장해 달라고 요청합니다. 그다음부터는 POST /v1/formats/{handle}/{slug}/runs 한 번으로 실행이 시작되며, 이 요청에 input에 담은 데이터, 실행별 지출 상한, 웹훅을 함께 보냅니다. 이 객체 자체는 Sume Format이란?에서 설명합니다.

더 좁은 경우에 맞는 진입점도 두 가지 있습니다. 작업이 호출마다 바뀌고 저장할 만한 것이 없다면, Agent Completion(POST /v1/agent/completions)이 매번 보내는 지시문으로 같은 에이전트를 실행합니다. 모델 하나에서 클립 하나만 필요하다면 POST /v1/videos가 비동기 모델 호출 한 번입니다.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-promo/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8823-v1" \
  -d '{
    "instruction": "Vertical 9:16 promo for this product.",
    "input": { "product_url": "https://example.com/p/8823" },
    "generation_spend_cap_usd": 20,
    "communication": { "webhook_url": "https://example.com/hooks/sume" }
  }'

각 영상은 어떤 트리거로 시작해야 하나요?

무엇이 작업을 시작하는지에 따라 고르세요. 문서는 이벤트와 시계 사이에 선을 긋습니다. 사용자가 무언가를 했을 때는 백엔드에서 Format을 호출하고, 시계 말고는 작업을 촉발하는 것이 없을 때 스케줄을 쓰세요.

실행을 지켜보는 사람이 없으면 어떻게 되나요?

채팅에서 작성한 레시피는 사람을 기다리며 멈출 수 있습니다. 영상에 비용을 쓰기 전에 스틸을 승인받는 경우가 그 예입니다. API에는 그 자리에 아무도 없으므로, 실행은 그런 승인이 이미 부여됐다는 안내를 받고 지출 상한 안에서 유료 단계까지 계속 진행합니다.

사람 없이는 정말로 끝낼 수 없는 실행은 반쯤 끝난 completed가 아니라 unattended_blocked 코드와 함께 failed로 돌아옵니다. 입력이나 브리프를 고친 뒤 새 Idempotency-Key로 다시 시도하세요. Format 실행은 유효 상한을 넘겨 지출할 수 없으므로, 모든 생성 요청에 generation_spend_cap_usd를 설정하세요. 상한을 얼마로 잡을지는 무인 AI 에이전트 지출 상한에서 다룹니다.

완성된 영상을 폴링 없이 받으려면 어떻게 하나요?

생성 요청에 communication.webhook_url을 보내세요. 실행이 완료되거나 실패하면 Sume가 종료 영수증을 한 번 POST하며, 타임스탬프와 원본 본문에 대한 HMAC-SHA256으로 서명합니다. 화면에 보여 줄 것은 영수증의 primary_output_url 하나이며, 미디어 URL은 만료되지 않는 내구성 있는 media.sume.com HTTPS URL입니다.

엔드포인트가 다운되는 날에 대비해 result_url 읽기를 백업으로 두고, 취소되거나 건너뛴 실행은 웹훅을 보내지 않는다는 점을 기억하세요. 검증 방법은 영상 실행용 서명된 웹훅에서 차례로 설명합니다.

이 방식으로 자동화할 수 없는 것은 무엇인가요?

• 스케줄 만들기와 수정. Developer API로는 스케줄을 나열하고, 실행을 시작하고, 실행을 모니터링할 수 있지만, 스케줄을 만들거나 수정할 수는 없습니다. 그 작업은 대시보드에서 하거나 채팅에서 에이전트에게 요청해서 합니다.
• 실시간 진행 상황. 진행 상황을 푸시하는 채널은 없습니다. Format 실행의 events_url은 폴링으로 읽는 phase 타임라인이며, 에이전트 출력이 아닙니다.
• 영상이 맞는지 판단하기. primary_output_url이 null이 아니라는 것은 결과물이 존재한다는 뜻이지, 결과물이 맞다는 뜻은 아닙니다. 레시피를 대규모로 돌리기 전에 샘플을 검토하세요. Sume가 무엇을 확인하는지는 실행 출력 확인하기에 정리되어 있습니다.
• 즉시 나오는 결과. 영상을 만드는 실행은 몇 초가 아니라 몇 분이 걸리며, 긴 호스트 영상은 보통 15분에서 30분 사이에 끝납니다.