AI 영상 생성 API 고르는 법: 12가지 체크리스트
AI 영상 생성 API는 Job, 재시도, 웹훅, 지출 상한, 실패, 출력물을 어떻게 다루는지를 보고 고르세요. 항목마다 Sume의 답을 붙인 체크리스트입니다.
AI 영상 생성 API를 고를 때는 어떤 모델을 제공하는지만 보지 말고, 요청 이후에 무슨 일이 일어나는지를 따져 보세요. 비동기 Job, 안전한 재시도, 서명된 웹훅, 실행별 지출 상한, 공개된 가격, 실패 시 과금, 큐잉, 요청 한도, 오류 코드, 모델 탐색, 출력 URL의 유지 기간이 그 대상입니다.
각 항목은 어느 공급사의 문서에서든 확인할 점을 먼저 적고, 이어서 2026-09-27에 확인한 Sume 문서가 이를 어떻게 설명하는지 적었습니다. 다른 공급사는 평가하거나 순위를 매기지 않습니다.
AI 영상 API 체크리스트에는 무엇이 들어가야 하나요?
영상 Job은 몇 분씩 실행되고 비용이 들기 때문에, 대부분의 항목은 Job 수명주기, 비용, 실패에 관한 것입니다.
| 항목 | 확인할 점 | Sume 문서의 설명 |
|---|---|---|
| 비동기 Job | 첫 응답에 담긴 내구성 있는 Job ID, 폴링할 수 있는 상태 | 모든 제출 모드가 첫 응답에 Job ID를 돌려줌. Job 상태는 queued, processing, completed, failed, canceled(Job과 결과 (영문)) |
| 멱등한 재시도 | 재시도한 제출을 두 번째 과금이 아니라 재전송으로 바꾸는 키 | Format 실행에서 같은 Idempotency-Key와 같은 본문을 보내면 idempotency_hit: true와 함께 원래 실행이 돌아옴. 본문이 다르면 409 idempotency_conflict(Format 호출하기 (영문)) |
| 서명된 웹훅 | 완료 시 서명된 푸시, 재시도 포함 | <timestamp>.<raw_body>에 대한 HMAC-SHA256을 x-sume-webhook-signature: sume-v1=…로 보냄. 종료 이벤트만, 최대 10회 시도(웹훅 (영문)) |
| 대기 한도 | 블로킹 호출과 실행 길이에 대해 명시된 한도 | sync는 최대 30초 기다리며, 그래도 Job ID를 돌려줌. Format 실행은 created_at에서 90분이 지나면 failed로 마무리되고, 25분이 지난 뒤 10분 동안 아무 신호가 없으면 더 일찍 마무리됨(실행과 결과 (영문)) |
| 실행별 지출 상한 | 요청마다 정하고 서버가 강제하는 상한 | generation_spend_cap_usd는 플랫폼 최대치 $500까지. 상한을 정한 적 없는 Format은 $400으로 보고됨. Agent Completions에서는 필수(Format 호출하기 (영문)) |
| 공개된 가격 | 공개 요율, 코드가 읽을 수 있는 카탈로그 | 가격의 기준은 API 요금. GET /v1/catalog는 API 키 없이 가격 메타데이터를 돌려줌(API 레퍼런스) |
| 실패 시 과금 | Job이 실패하면 돈이 어떻게 되는지 | 추정 금액은 제출 시 예약되고, 성공하면 확정되며, 확정 전에 실패하거나 취소되면 환불됨(핵심 개념) |
| 큐잉 | 동시성 한도를 넘은 Job이 기다리는지, 실패하는지 | 동시성을 넘은 유효한 Job은 queued로 대기함. 429 queue_full은 큐가 가득 찼을 때만 돌아옴(Generation admission) |
| 요청 한도 | 공개된 예산, 요청 속도를 맞출 수 있는 헤더 | 키별 분당 예산. 읽기 예산은 쓰기 예산의 마흔 배. ratelimit-* 헤더가 있고, 429에는 retry-after가 옴(인증) |
| 기계가 읽을 수 있는 오류 | 문장이 아니라 안정적인 코드와 재시도 힌트 | 오류 봉투 하나에 소문자 code, retryable, next_action, 지원팀에 알려 줄 request_id가 담김(오류와 비용 (영문)) |
| 모델 탐색 | 미리 읽어 볼 수 있는 모델별 한도, 엄격한 검증 | GET /v1/videos/models가 supported_durations와 supported_resolutions를 나열함. size처럼 지원하지 않는 필드는 조용히 버려지지 않고 400(영상 생성 (영문)) |
| 내구성 있는 출력물 | 출력 URL이 얼마나 유지되고 누가 열 수 있는지 | Format 실행의 미디어는 만료되지 않고 URL을 가진 누구에게나 공개되는, 내구성 있는 media.sume.com URL로 돌아옴(실행과 결과 (영문)) |
최종 후보 API는 결정하기 전에 어떻게 테스트하나요?
작은 Job으로 실패 경로를 일부러 실행해 보세요. Sume에서는 다음과 같습니다.
- 같은
Idempotency-Key와 같은 본문으로 Format 실행 생성 요청을 다시 보내세요.200과idempotency_hit: true가 돌아오고, 두 번째 과금은 없어야 합니다. 키 설계는 AI 영상 API 멱등성 키에서 다룹니다. - 대시보드 웹훅 탭의 Send test나
POST /v1/webhooks/test-deliveries는 직접 입력한 URL로 서명된webhook.test페이로드를 POST합니다. - 서명은 문서가 요구하는 방식대로 검증하세요. 시크릿을 교체하는 동안에는 헤더에 살아 있는 시크릿마다
sume-v1=항목이 하나씩 담기며, 그중 하나라도 일치하면 유효한 전달입니다. - 동시성이 허용하는 것보다 많은 Job을 제출해 보세요. 넘친 Job은
queued로 대기하며, 이는 실패가 아닙니다. - Job이 실패한 뒤
GET /v1/usage?job_id=…를 읽으세요.refunded행이 있으면 예약이 해제된 것입니다.
Sume의 답으로 알 수 없는 것은 무엇인가요?
문서는 다음과 같은 한계도 밝힙니다.
- 진행 상황 스트림이 없습니다. SSE나 WebSocket이 없고,
events_url은 스트리밍이 아니라 폴링으로 읽습니다. 푸시되는 것은 웹훅으로 전달되는 완료 알림뿐입니다. - 큐 위치나 예상 완료 시간(ETA)이 없습니다. 큐에 있는 Job 수와 남은 용량만 알 수 있습니다.
sync와subscribe는 30초에서 대기를 멈추며, 문서는 이 방식이 대부분의 영상 작업에 맞지 않는 도구라고 설명합니다.POST /v1/images는data[].url을 Sume가 호스팅하는 서명된 URL로 돌려주며, 문서는 이를 내구성 있는 URL이라고 부르지 않습니다. 보관해야 할 이미지는 복사해 두세요.- 크레딧은 대시보드에서 구매합니다. 공개 API로는 잔액과 사용량을 읽을 수 있지만 충전 엔드포인트는 없습니다.
Sume에서는 어떤 표면부터 평가해야 하나요?
문서는 대부분의 파트너에게 Format API를 권합니다. 저장된 레시피를 한 번 호출하면 내구성 있는 미디어와 직접 정한 스키마의 JSON이 돌아옵니다. POST /v1/videos 같은 모델 엔드포인트는 그 아래 계층으로, 오케스트레이션을 직접 맡으면서 모델을 한 번 호출할 때 씁니다. Sume Format이란?에서 시작하세요.
출처
관련 글
개발자 카테고리의 다른 글
- 브라우저에서 Sume API 호출 시 CORS 오류: 해결 방법
브라우저는 내 사이트에서 api.sume.com으로 직접 보내는 호출을 차단하며, API 키는 프론트엔드 코드에 절대 넣으면 안 됩니다. 서버에서 Sume를 호출해 프록시하세요.
- Sume API 엔드포인트 목록: 경로, 스코프, 멱등성
Sume API의 공개 경로를 계열별로 정리한 색인입니다. 키가 필요 없는 경로, 계열별 스코프, Idempotency-Key 적용 위치, 계열별 설명 글을 담았습니다.
- Sume API 오류 코드 총정리: 표면별 색인과 다음 조치
Sume API 오류 코드를 표면별로 정리했습니다. 공통 코드, 유료 생성, Format, Scheduled 실행, Agent Completions, 미디어 도구, 호스팅 MCP를 다룹니다.
- Sume API 용어집: Format 실행, 지출 상한, 멱등성 키
Sume API 용어를 한두 문장씩 설명합니다. Format, 실행, Job, 지출 상한, 멱등성 키, 지갑, 에이전트 수수료, 웹훅, 아티팩트 등을 관련 글 링크와 함께 정리했습니다.
작성자 Sume