How to choose an AI video generation API: 12-point checklist
Choose an AI video generation API by how it handles jobs, retries, webhooks, spend caps, failures, and outputs: a checklist with Sume's answers.
To choose an AI video generation API, judge what happens after the request, not only which models it offers: async jobs, safe retries, signed webhooks, per-run spend caps, published prices, billing on failure, queueing, rate limits, error codes, model discovery, and how long output URLs last.
Each check says what to look for in any vendor's docs, then how Sume documents it, read on 2026-09-27. No other vendor is assessed or ranked.
What should an AI video API checklist cover?
Video jobs run for minutes and cost money, so most checks concern the job lifecycle, money, and failure.
| Check | What to look for | How Sume documents it |
|---|---|---|
| Async jobs | A durable job id in the first response, and statuses you can poll | Every submit mode returns the job id in its first response; a job's statuses are queued, processing, completed, failed, and canceled (Jobs and results). |
| Idempotent retries | A key that turns a retried submit into a replay, not a second charge | On a Format run, the same Idempotency-Key and body returns the original run with idempotency_hit: true; a different body is 409 idempotency_conflict (Create a run). |
| Signed webhooks | A signed push on completion, with retries | HMAC-SHA256 over <timestamp>.<raw_body>, sent as x-sume-webhook-signature: sume-v1=…; terminal events only, up to 10 attempts (Webhooks). |
| Wait limits | Stated limits on blocking calls and run length | sync waits at most 30 seconds and still returns the job id; a Format run is finalized as failed 90 minutes after created_at, or sooner if, past 25 minutes, it has been silent for 10 (Runs and results). |
| Per-run spend caps | A ceiling you set per request, enforced by the server | generation_spend_cap_usd up to the $500 platform maximum; a Format that never set a cap reports $400; Agent Completions require one (Create a run). |
| Published prices | Public rates, and a catalog your code can read | API pricing is the source of truth for prices; GET /v1/catalog returns pricing metadata without an API key (API reference). |
| Billing on failure | What happens to the money when a job fails | The estimate is reserved at submit, captured on success, and refunded on failure or cancellation before capture (Core concepts). |
| Queueing | Whether jobs past your concurrency limit wait or fail | Valid jobs past your concurrency wait as queued; only a full queue returns 429 queue_full (Generation admission). |
| Rate limits | Published budgets, and headers to pace on | Per-minute budgets per key, reads forty times the write budget; ratelimit-* headers, and retry-after on a 429 (Authentication). |
| Machine-readable errors | Stable codes and retry hints, not prose | One envelope: a lowercase code, retryable, next_action, and a request_id to quote to support (Errors and spend). |
| Model discovery | Per-model limits you can read first, and strict validation | GET /v1/videos/models lists supported_durations and supported_resolutions; an unsupported field such as size is a 400, not silently dropped (Video generation). |
| Durable outputs | How long output URLs live, and who can open them | A Format run's media comes back on durable media.sume.com URLs that do not expire and are public to anyone holding them (Runs and results). |
How do I test a shortlisted API before I commit?
Run the failure paths on purpose, with small jobs. On Sume that means:
- Replay a Format run create with the same
Idempotency-Keyand body: expect200,idempotency_hit: true, and no second charge. Idempotency keys for AI video APIs covers key design. - Send test, on the dashboard's Webhooks tab or
POST /v1/webhooks/test-deliveries, posts a signedwebhook.testpayload to a URL you type. - Verify signatures the way the docs require: during a secret rotation the header carries one
sume-v1=entry per live secret, and a delivery is valid when any entry matches. - Submit more jobs than your concurrency allows: the extras wait as
queued, which is not a failure. - After a failed job, read
GET /v1/usage?job_id=…: arefundedrow means the reservation was released.
What will Sume's answers not give you?
The docs also state these limits:
- No progress stream: there is no SSE or WebSocket, and
events_urlis polled, not streamed. Only completion is pushed, by webhook. - No queue position or ETA: only queue counts and remaining capacity.
syncandsubscribestop waiting at 30 seconds, which the docs call the wrong tool for most video work.POST /v1/imagesreturnsdata[].urlas a Sume-hosted, signed URL, not one the docs call durable, so copy an image you need to keep.- Credits are bought in the dashboard; the public API reads balance and usage but has no top-up endpoint.
Which Sume surface should I evaluate first?
The docs point most partners at the Format API: one call to a saved recipe that returns durable media plus JSON in your schema. Model endpoints such as POST /v1/videos are the layer underneath, for one invocation where you own the orchestration. Start with What is a Sume Format?
Sources
Related posts
More in Developers
- CORS error calling the Sume API from a browser: the fix
Browsers block direct calls from your site to api.sume.com, and API keys must never ship in frontend code. Call Sume from your server and proxy it.
- Sume API endpoints list: routes, scopes, idempotency
An index of the Sume API's public routes by family: which need no key, which scope each needs, where Idempotency-Key applies, and the post on each.
- Sume API error codes by surface: one index with next steps
Sume API error codes indexed by surface: common codes, paid generation, Formats, Scheduled runs, Agent Completions, media tools, and hosted MCP.
- Sume API glossary: Format run, spend cap, idempotency key
Sume API terms in one or two sentences each: Format, run, job, spend cap, idempotency key, wallet, agent fee, webhook, artifact, and more, with links.
Written by Sume