Shotstack

Shotstack

Shotstack is a JSON-timeline video API. You build or load a timeline, submit a render (async), poll until done, then read the output URL. Media can be ingested from public URLs, generated with AI, or referenced directly in a timeline.

API families (different hosts, same API key)

Four host families share one API key. Toggle sandbox mode on the credential to route to staging hosts; production keys only work on production hosts.

• Edit — templates, render jobs, media probe.
• Ingest — fetch remote files into Shotstack storage.
• Serve — CDN assets after render or transfer.
• Create — async AI generation (text-to-image, TTS, image-to-video).

Sandbox keys only work when the credential sandbox toggle is on; production keys only on production hosts.

Data model

• Templates — saved timelines with optional {{merge}} placeholders.
• Sources — ingested files (queued → ingesting → ready / failed).
• Renders — async edit jobs (queued → rendering → done / failed). Output URL on the render when done.
• Assets — hosted CDN files (video, thumbnail, poster). Asset id ≠ render id. One render can yield multiple assets.
• Transfers — starting a Serve transfer returns a transfer_id (your client UUID). Poll assets-by-render with render_id=transfer_id; the real CDN asset_id is in assets[0].asset_id. Direct GET by transfer_id alone 404s until you resolve via render lookup.
• Generated assets — Create API jobs with their own asset id and async status.

Operational order

1. List or load templates/sources when you need ids; probe unknown media URLs before building timelines.
2. Ingest or generate media if you need Shotstack-hosted URLs.
3. Submit a render (timeline JSON, template + merge, or convenience combine/crop tools).
4. Wait for render completion with the render wait tool, then read url.
5. For thumbnails/posters or CDN metadata, look up assets by render id (or transfer_id for Serve transfers).
6. Transfers: call the transfer wait tool with the transfer_id, then use assets[0].asset_id for get/delete.

Wait tools (preferred over manual polling)

Submit tools return ids and a poll_with hint. Use the matching wait tool instead of looping get calls:

• Render wait — after any render submit (video, template, combine, crop).
• Ingest wait — after source ingest.
• Generated-asset wait — after AI asset generation.
• Transfer wait — after Serve transfer submit.

Each accepts timeout_seconds (10–7200, default 1800) and poll_interval_seconds (1–60, default 5). One-off status checks still use the get tools for renders, sources, and generated assets.

Gotchas

• Async everything: renders, ingest, and Create API jobs all need waiting or polling.
• No render list API: you must keep the render_id from the submit response.
• No asset list API: use render id or a known asset id.
• Rate limit: ~30 requests/minute; leave a few seconds between poll calls.
• Generative clips: text-to-image and similar can be inline timeline assets or pre-generated via Create API.
• Destinations: render output can target S3, Mux, Vimeo, etc. via the render payload — default is Shotstack CDN.