2026-09-29

Choosing an AI video API as a developer: a technical checklist

Choose an AI video API on job model, not demos: async submit and poll, idempotent retries, webhooks, live capability discovery, a billing model you can read

5 min readSume

All posts

When you pick an AI video API for a product, check the plumbing before the clips: is it asynchronous, can you retry safely, can it call you back, can you discover model limits at runtime, and is the price reserved before the work starts. This is a checklist, not a ranking. Here is how Sume's /v1/videos answers each item, per its docs read 2026-09-29.

Source: Video generation.

What should the checklist cover?

Developer checklist and Sume's answer, from the video docs, read 2026-09-29.
Question	Sume `/v1/videos`
Async job model	`POST /v1/videos`, then `GET /v1/videos/{id}` and `/content`
Safe retries	`Idempotency-Key` header; a replay returns the original job
Webhooks	`callback_url` (HTTPS), signed with `x-sume-webhook-signature`
Capability discovery	`GET /v1/videos/models`
Wire shape	OpenRouter video shape, bare model ids
Cost visibility	Reserved on submit at provider list × 1.25; `usage.cost` on the job
Unsupported fields	`size`, `seed`, `provider.options` return 400 `unsupported_parameter`

How do I submit and poll?

curl -X POST https://api.sume.com/v1/videos \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: job-123" \
  -d '{"model":"sume/auto","prompt":"A sailboat at dawn","duration":5}'

curl https://api.sume.com/v1/videos/$JOB_ID \
  -H "Authorization: Bearer $SUME_API_KEY"

What else should I test?

Failure paths: send an unsupported value and read the error.
Retry with the same Idempotency-Key and confirm you get one job.
Poll until a terminal state and time-box the wait.
Check the price of your real clip before scaling.

Do I need to pin a model?

Not to start. sume/auto lets Sume pick; pin an id once you need a specific input. See sume/auto or a pinned video model.

Sources

Video generation