Sume API status values: jobs, runs, queues, and webhooks
Sume API status values in one place: jobs, /v1/videos, Format and Agent runs, bulk queues, webhook deliveries, usage rows, grants, and balance.
Developers
Building on the Sume API: keys and hosts, jobs and runs, polling, webhooks, idempotency, errors and rate limits, the SDK, the CLI, and MCP auth.
Start with: Sume API quickstart: your first video generation call in five steps
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 pagination: cursor, starting_after, and page limits
How each Sume list endpoint pages: cursor and has_more on Formats and runs, starting_after on /v1/jobs, and limit-only lists that have no cursor.
Sume API headers: auth, idempotency, If-Match, rate limits
Every HTTP header the Sume API reads or sends: the API key, Content-Type, Idempotency-Key, If-Match, request ids, rate limits, and webhook signatures.
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.
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.
Do AI-generated video URLs expire? How Sume stores outputs
Not for Format runs and Agent Completions: Sume returns their media on media.sume.com URLs that do not expire, and anyone holding a link can open it.
Download a generated video from the Sume API: 401s and 302s
Sume unsigned_urls need your API key and answer with a 302 redirect. Download the MP4 with curl -L or code, and fix each 401, 404, or 409.
Webhook URL rejected as invalid? Sume's webhook URL rules
Sume answers 400 invalid_request when a webhook URL is not public HTTPS. The rules for scheme, host, port, and credentials, and the check at delivery.
Sume API media URL rules: which URLs each endpoint accepts
Sume generation endpoints fetch public HTTPS media URLs. Trim, filter, frames, inspect, and Timeline take only your workspace's media.sume.com URLs.
Sume job types and concurrency: which calls take a slot
Each Sume endpoint's job type and slot use: every generation job, trims and Timeline included, takes a concurrency slot; frames and inspect don't.
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 output file formats: MP4, PNG, WebP, WAV, MP3
The file each Sume API endpoint returns: MP4 from Timeline and the editing tools, PNG, JPEG, or WebP images, WAV or MP3 audio, and JSON transcripts.
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.
MCP server OAuth flow on Sume: discovery, consent, PKCE, and scopes
Sume's hosted MCP server runs its own OAuth: a 401 points to discovery metadata, the user consents on mcp.sume.com, and PKCE S256 yields a one-hour token.
Fix MCP insufficient_scope on Sume: scopes, missing tools, timeouts
An MCP insufficient_scope error on Sume means the OAuth session lacks mcp:write. Start with mcp_health, then fix scopes, missing tools, and timeouts.
Sume agent run errors: action_run_in_progress, agent_run_not_found
409 action_run_in_progress means a schedule run is already active and you sent reject. 404 agent_run_not_found means the id is not your Agent Completion run.
How to run the Sume CLI in CI and on headless servers
Run the Sume CLI in CI with a pinned release binary, SUME_API_KEY from your secret store, an isolated SUME_CONFIG_DIR, a doctor preflight, and --json output.
Sume CLI commands: a reference for account, jobs, assets, and skills
The Sume CLI commands beyond generation: login and account, health and doctor checks, schema discovery, jobs, assets, batch helpers, skills, and aliases.
Sume CLI not working? Fixes for login, API base, jobs, and media
When the Sume CLI is not working, run four read-only checks, then fix the cause: a missing key, a wrong API base, an unfinished job, or a rejected media URL.
List video generation models via API: GET /v1/videos/models
GET /v1/videos/models lists every Sume video model with its resolutions, aspect ratios, durations, frame and reference types, audio flag, and pricing SKUs.
How to poll a video generation job status API: Sume's /v1/jobs
Poll GET /v1/jobs/{id}/status until terminal is true, wait next_poll_after_seconds between reads, then fetch /result once result_ready is true.
Sync vs async API for video generation: Sume's four submit modes
Sume's submit modes are async, sync, subscribe, and webhook. sync and subscribe wait 30 s at most, so for video, submit async and poll, or take a webhook.
Sume TypeScript SDK quickstart: install, client, errors, retries
Install @sume-com/sdk, create one client with createSumeClient, and call typed operations that return errors instead of throwing, with retries built in.
Why did my AI video generation job fail? Reading the job error
A failed Sume job carries a public error: category, stage, retryable, public_reason, and next_action. Where to read it, and what each field tells you to do.
Wait for a Sume job or run to finish in the TypeScript SDK
waitForJob, waitForRun, and subscribeFormatRun poll a Sume job or run until it ends. Here are their default timeouts, the errors they throw, and retries.
List jobs API: filter video jobs by status and recover lost job ids
GET /v1/jobs lists a workspace's jobs newest first, up to 100 per page, filtered by status, type, or run_id. Page with starting_after; join on idempotency_key.
Sume API catalog: list available models, endpoints, and prices
GET /v1/catalog lists Sume API capabilities with their model ids, invoke URLs, availability, runtime readiness, and pricing. It needs no API key.
Sume API OpenAPI spec: download it, browse it, generate a client
Download the Sume API's live OpenAPI spec from api.sume.com/reference/json, browse it in Swagger UI, and generate a client for languages beyond TypeScript.
Sume job vs run: generation jobs and Format, Action, Agent runs
A Sume job is one generation request tracked at /v1/jobs; a run is one agent turn from a Format, schedule, or Agent Completion. Ids, webhooks, and waits differ.
Sume webhook not received? How to debug delivery and signatures
When a Sume webhook does not arrive, read webhook_delivery on the job or run, prove your endpoint with a test delivery, then redeliver the real event.
How long does AI video generation take? Sume jobs, runs, and limits
Sume's docs put one video job at 30 seconds to several minutes and a long-form Format run at 15 to 30 minutes. Here are the phases, stall signs, and limits.
AI video generation API progress updates without a push stream
Sume has no SSE or WebSocket progress stream. Poll job events or a Format run's phase timeline, show avatar scene stills, and promise no ETA.
How to cancel an AI video generation job or run with the Sume API
A Sume generation job cancels only before generation starts; Format, Action, and Agent run cancels are idempotent. Routes, responses, billing, webhooks.
Video generation API timeouts: Sume's wait caps, SDK defaults, expiry
A Sume sync submit waits 30 s at most and SDK waits default to 10–20 minutes, but a client timeout never cancels the job. Every limit, and your own deadline.
Video generation API 400 errors: unsupported parameter and fixes
Why POST /v1/videos answers 400: invalid_request, unsupported_parameter for size, seed, or provider.options, and unsupported_capability. Causes and fixes.
Sume request_id vs job_id vs run_id: which ID to store and quote
Store the job or run id, dedupe webhooks on job_id or the run envelope's request_id, and quote the req_ request id with the job or run id to Sume support.
Sume API quickstart: your first video generation call in five steps
Create a Sume API key, send one POST /v1/videos request with sume/auto, poll the job, and download the video. Five short steps, then where to go next.
Sume developer dashboard: API keys, usage, jobs, billing, playground
Sume's developer dashboard, page by page: create API keys, buy credits on Billing & subscription, inspect Jobs and Usage, and try Avatar in the playground.
Idempotency keys for AI video APIs: retry without paying twice
An idempotency key makes a retried create return the original run or job instead of a second paid one. How Sume's Idempotency-Key works on each API.
Spend caps for unattended AI agents: how Sume bounds each run
An unattended agent has no one to approve spend, so Sume caps generation per run: required on Agent Completions, and up to $500 on Format runs.
Video API media inputs and outputs: public URLs in, Sume URLs out
Sume generation requests take media as public HTTPS URLs in named fields, with no separate upload step, and return Sume-hosted media.sume.com URLs to store.
How to generate avatar video from the terminal with the Sume CLI
Install the Sume CLI, sign in through the browser, and submit talking avatar videos. Image, Video, and Music 1.0 have no CLI submit command yet.
How Sume API keys work: scopes, auth headers, hosts, and rotation
A Sume API key is a workspace-scoped secret sent as Bearer or x-api-key, never both. Scopes are fixed at creation, and a key works only on its own host.
Video job concurrency and queueing on Sume: limits and queue_full
Sume accepts valid paid jobs as queued and runs them under a plan concurrency limit. A submit fails with 429 queue_full only when the queue is also full.
Sume API errors and rate limits: codes, 429s, and when to retry
Sume API errors share one envelope with a stable code and a request id. Reads and writes have separate per-minute budgets; queue_full is not a rate limit.
Signed webhooks for Sume video runs: events, retries, verification
Sume sends one HMAC-SHA256 signed POST when a Format, Action, or Agent Completion run completes or fails. Verify the raw body and dedupe on request_id.
Connect Claude Code, Cursor, or Codex to Sume with hosted MCP
Sume's hosted MCP server at mcp.sume.com/mcp lets coding agents generate images, video, audio, and avatars. Setup, OAuth scopes, and spend gates.