Shotstack

Delete one hosted asset by its asset id, via DELETE /assets/{id} on the Serve API. Answers 204 with an empty body. Each asset is deleted individually: a render that produced a video plus a thumbnail and a poster needs three calls, one per asset id. The hosted file stops being served; copies already sent to an external destination are not touched.

Delete an ingested source file by its id, via DELETE /sources/{id} on the Ingest API. Answers 204 with an empty body. The stored file and its renditions stop being served; edits that already referenced it by URL will fail to fetch it on their next render.

Delete a template by its template id, via DELETE /templates/{id} on the Edit API. Answers 204 with an empty body. Shotstack has no recycle bin for templates: after this the id is gone and `shotstack_get_templates_by_id` answers 404, so the edit is unrecoverable unless it was saved elsewhere. Renders already produced from the template are not affected.

Get one hosted asset -- a rendered video, image, audio file, thumbnail or poster -- by its ASSET id, via GET /assets/{id} on the Serve API. An asset id is not a render id: one render can produce several assets, and `shotstack_get_assets_render_by_id` is the way in from a render id.

Look up every asset a render produced, by RENDER id, via GET /assets/render/{id} on the Serve API. This is the join between the two id spaces: a render request returns only a render id, while a render may create a video, a thumbnail and a poster image, each with its own asset id. Answers 404 `No assets found for Id` while the render is still in flight or if nothing was produced.

Get the status of an on-demand generation job created by `shotstack_post_generate`, via GET /generate/{id} on the Edit API. Answers 202 while the job is still processing and 200 once it has finished, done or failed. Jobs are owner-scoped: a job id belongs to the account and environment that created it.

List the generation models available to prompt-bearing image, video and audio assets, with what each one costs in credits, via GET /models on the Edit API. Use it to populate a model picker rather than hard-coding a list -- a newly launched model appears here with no change on your side -- and filter by each entry's asset `type` when a picker needs only one kind. Option schemas are omitted by default; pass `expand=options` to include them.

Get one generation model by its identifier, including the JSON Schema of the options it accepts and what it costs in credits, via GET /models/{id} on the Edit API. The identifier is the `model` value from `shotstack_get_models` (for example `nano-banana-2`), not a UUID. Answers 404 when no model has that identifier.

Inspect any media asset on the internet -- image, video or audio -- with a hosted FFprobe, via GET /probe/{url} on the Edit API. Returns width, height, duration, rotation, frame rate, codecs and the rest of the container's metadata as JSON. Pass `url` as an ordinary URL; Shotstack requires it percent-encoded into a single path segment and this integration does that encoding for you (measured 2026-09-19: an un-encoded URL answers 404 `The resource GET /edit/stage/probe/https://... does not exist`, the encoded form answers 200). The asset must be publicly reachable by Shotstack, not only by you.

Get the status, temporary asset URL and details of one render by id, via GET /render/{id} on the Edit API. The status walks `queued` -> `fetching` -> `rendering` -> `saving` -> `done`, or `failed` with an error. `data` returns the edit that produced it and `merged` returns that edit with its merge fields already substituted.

List the source files ingested against this account and environment, via GET /sources on the Ingest API. Returns a JSON:API document -- the files are under `data`, each with its status and its hosted URLs, and `meta.next` carries the cursor for the next page when there is one.

Get one ingested source file's details and status by its id, via GET /sources/{id} on the Ingest API. Source ids are alphanumeric in the UUID SHAPE but are not UUIDs (`zzz01m2w-h69ky-70mmg-k1kvf-2630rn`), so do not validate them as one.

List the templates stored against this account and environment, via GET /templates on the Edit API. Returns each template's id and name rather than its edit; fetch one with `shotstack_get_templates_by_id`. This is also the endpoint a pasted API key is checked against when a connection is made.

Retrieve one template, including its full edit, by template id, via GET /templates/{id} on the Edit API.

Transfer a file from any publicly reachable URL to one or more Serve API destinations, via POST /assets on the Serve API. `url`, `id` and `destinations` are all required; `id` is a client-chosen identifier for the asset and Shotstack does not require it to be unique.

Generate a single image, video or audio asset from a text prompt, without rendering a whole edit, via POST /generate on the Edit API. Submit one prompt-bearing asset. The answer is 200 with the finished asset when an identical request has been generated before (results are cached by prompt, model and options) and 202 with a job id otherwise -- poll `shotstack_get_generate_by_id` for that one. GENERATION IS BILLED IN CREDITS PER ASSET, on BOTH environments: Shotstack's own contract says so, and the per-model credit price is in `shotstack_get_models`. Identical repeat requests resolve from the cache at no charge.

Queue and render an edit as a video, image or audio file, via POST /render on the Edit API. Shotstack validates the edit, downloads and caches every asset it names, preprocesses video for compatibility, renders the timeline and stores the output. The response is the QUEUED render's id, not the finished file: poll `shotstack_get_render_by_id` (or supply `callback`) until the status is `done`, then fetch the hosted file with `shotstack_get_assets_render_by_id`. `timeline` and `output` are both required. On a `stage` connection the render is free and the output is watermarked; on a `v1` connection it spends the account's credits and may be billed.

Queue a source file to be fetched from a URL and stored by Shotstack, via POST /sources on the Ingest API. Sources can be video, image, audio or font files, and once ingested they can have new output renditions created from them. The URL must be publicly reachable by Shotstack or carry its own credentials. Answers 201 with the queued source, or 400 with a list of validation errors.

Save an edit as a re-usable template, via POST /templates on the Edit API. A template can be retrieved and modified before it is rendered, and merge fields let data be substituted into it and the result rendered in a single request with `shotstack_post_templates_render`. `name` is required; `template` is the edit itself and, if omitted, a blank template is saved.

Render an asset from a saved template id plus optional merge fields, via POST /templates/render on the Edit API. Merge fields replace the `{{PLACEHOLDER}}` variables inside the template's edit. Like `shotstack_post_render` this returns a QUEUED render id rather than a file, and costs what a render costs on the connection's environment.

Request a signed URL to upload a file directly to Shotstack, via POST /upload on the INGEST API -- not the Edit API, whatever its neighbours suggest (measured 2026-09-19: POST /edit/{env}/upload answers 404 `The resource POST /edit/stage/upload does not exist`, POST /ingest/{env}/upload answers 200). Takes no arguments. The response carries a source id and a short-lived pre-signed S3 URL; the file itself is then sent to THAT URL with a separate PUT request carrying the binary, which this integration does not make for you. Track the result with `shotstack_get_sources_by_id`.

Replace an existing template's name and edit by template id, via PUT /templates/{id} on the Edit API. This is a REPLACE, not a merge: Shotstack's own contract states that both the name and the template must be provided, and that omitting `template` saves a BLANK one. Read the template first with `shotstack_get_templates_by_id` and send it back changed, rather than sending only the field you meant to edit.