Sume API quickstart: your first video generation call in five steps

Your first Sume API call takes five steps: create an API key in the dashboard, send one POST https://api.sume.com/v1/videos request with model: "sume/auto" and a prompt, poll the returned polling_url until the job finishes, download the video from unsigned_urls, and then choose what to build next.

Each step follows Sume's Video Generation, Authentication, and API overview docs, read on 2026-09-26. Video generation is an asynchronous job: the call returns an id at once, and the video arrives later.

Step 1: How do I create a Sume API key?

Create a key in the API Keys dashboard. Keys are workspace-scoped, and the dashboard reveals the full secret only when the key is created, so store it in a secret manager right away.

Keep the key on your server, never in frontend JavaScript or a mobile app. Send it as Authorization: Bearer or as x-api-key, not both: a request carrying both is 401 unauthorized. GET /v1/me verifies the key and the workspace it resolves to. How Sume API keys work has the details.

export SUME_API_KEY="sume_live_..."

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

Step 2: How do I send my first video request?

POST /v1/videos requires model and prompt. Send sume/auto to let Sume pick the model; Auto defaults to 720p and 8 seconds and takes 3–10 second clips at 16:9 or 9:16. To pin a model instead, send a bare catalog id from GET /v1/videos/models, such as seedance-2. An Idempotency-Key header makes retries safe: a replay returns the original job.

curl -sS -X POST "https://api.sume.com/v1/videos" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-video-001" \
  -d '{
    "model": "sume/auto",
    "prompt": "A golden retriever playing fetch on a sunny beach",
    "aspect_ratio": "16:9",
    "duration": 5
  }'

Step 3: How do I know when the video is ready?

The submit answers 202 Accepted with an id, a polling_url, status: "pending", and a model field that echoes sume/auto. Poll the polling_url, GET /v1/videos/{jobId}, until status is completed, failed, or cancelled. The docs suggest about 30 seconds between polls; video generation typically takes 30 seconds to several minutes, depending on the model and parameters. More in how long AI video generation takes.

To skip polling, send callback_url, an HTTPS URL, and Sume POSTs a signed webhook once the job reaches a terminal state. The same job is also visible at GET /v1/jobs/{id}/status. If your client disconnects or times out, keep the id and recover with the jobs API instead of submitting duplicate paid work.

Step 4: How do I get the finished video?

When status is completed, unsigned_urls holds the download URLs. You can also call the content endpoint directly; index defaults to 0 and selects an output when a model returns more than one. The poll response also reports usage.cost, the Sume billable amount, which is reserved from your workspace USD balance at submit.

On failed, the docs' troubleshooting list says to read the error field, keep the prompt within model guidelines, and check that any reference images are reachable over public HTTPS in supported formats.

curl "https://api.sume.com/v1/videos/job_123/content?index=0" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  --output video.mp4

Step 5: Where should I go after the first call?

Pick the next page by what you are building:

• A packaged workflow instead of one clip. Most partner integrations are one call to a saved recipe, a Format: start with What is a Sume Format?
• A person in the loop. Brief the agent in the Agents tab, with nothing to install, then save the recipe; see What is a video agent?
• Model limits. GET /v1/videos/models lists each model's resolutions, aspect ratios, durations, and pricing SKUs; see list video models.
• TypeScript. @sume-com/sdk covers every operation in the public OpenAPI schema; see the TypeScript SDK quickstart.
• Exact fields. The live schema is https://api.sume.com/reference/json, with Swagger UI at api.sume.com/reference.
• Older code. Video 1.0 is retiring soon; new integrations use POST /v1/videos with sume/auto (migration guide).

What if the first call fails?

The common first-call errors, with the full list in Sume API errors and rate limits:

• 401 unauthorized: the key is missing, malformed, or revoked, or the request sent both auth headers.
• 400 unsupported_parameter: /v1/videos got size or a non-empty provider.options. Use resolution and aspect_ratio instead of size; seed is rejected too.
• 404 model_not_found: the model id does not exist. Sume uses bare catalog ids, not org/slug.
• 402 insufficient_credits: the workspace balance cannot cover the estimated cost. Buy credits under Billing & subscription.
• 429 queue_full or 429 rate_limited: the workspace has no accepted-job capacity left, or the request budget is spent. Wait, then retry with the same Idempotency-Key.