@thenavidm/shotstack-mcp-cli

v3.0.0

Published

10 days ago

Shotstack MCP and shared CLI with current Edit/Serve/Ingest schemas and confirmed account operations.

Shotstack MCP Server & CLI

Shotstack MCP server and CLI for Codex and AI agents. 23 tools for current rendering, templates, generation models, Serve and Ingest, with private accounts and explicit mutation approval. One shared implementation supplies both binaries and a desktop bundle.

Built and maintained by Navid Moazzez. Built on Slipway, which turns one definition of each tool into the MCP server and the CLI. The complete guide is on navid.me.

The terminal illustrates real command names and approval flow. It is not a recording of a paid provider render. Shotstack already has official CLI/local/hosted MCP products; their Studio and semantic validation are compared below.

Requires Node 22+ and eligible Shotstack API access for account operations. Validation: fixture tests, schema validation and protocol/artifact discovery are separate from provider-account rendering and desktop GUI outcomes, which are not claimed. Section 7 has the measured token costs.

Two ways to use it

Command line

npm install -g @thenavidm/shotstack-mcp-cli@latest
shotstack-cli
shotstack-cli list-models --agent
shotstack-cli schema render
shotstack-cli render --payload-file /absolute/private/approved-edit.json --account sandbox --confirm --agent

--confirm authorizes the specific requested operation. --agent and --yes do not supply consent or a provider credit cap.

MCP server, for your AI app

codex mcp add shotstack -- npx -y @thenavidm/shotstack-mcp-cli@latest

Configure private credentials/environment first. Ask: “Inspect this existing render and return its status; do not submit another render.” Client and OS details are in INSTALL.md.

Which one

| Where you work | Surface | | --- | --- | | Codex or an agent with shell access | Local MCP, shared CLI or both | | Desktop chat | Compatible local MCP or .mcpb | | Scripts/CI | CLI or an MCP client | | Remote-URL-only chat | Official provider-hosted MCP |

Features

| Capability | CLI command | MCP tool | | --- | --- | --- | | Render and status | render / get-render | render / get_render | | Templates | create-template / list-templates / render-template | create_template / list_templates / render_template | | Generation models and jobs | list-models / generate-asset / get-generated-asset | list_models / generate_asset / get_generated_asset | | Hosted assets | get-asset / transfer-asset | get_asset / transfer_asset | | Ingest sources | ingest-source / list-sources / get-source | ingest_source / list_sources / get_source | | Private upload credential | create-upload-url-file | create_upload_url_file | | Account/environment labels | list-accounts | list_accounts | | Configuration checks | doctor / login | CLI utilities |

| Number | Section | What it covers | | --- | --- | --- | | 1 | What you can ask it | Practical tasks | | 2 | Quick install | MCP/CLI/desktop | | 3 | Set up Shotstack access | Keys, environments, credits | | 4 | Connect your client | All client/OS routes | | 5 | Check it works | Doctor and first read | | 6 | Output, flags and exit codes | Flags and scripting | | 7 | MCP or CLI and token cost | Actual measurement method | | 8 | Every tool and argument | Every route/argument | | 9 | Render, template, generation and media workflows | Native workflow inputs | | 10 | Jobs, pagination and private files | Status and private credential files | | 11 | Several private accounts | Isolated named profiles | | 12 | Writing safely | Approval and direct-call policies | | 13 | How it works | Shared architecture and sync | | 14 | Your data | Credentials and provider processing | | 15 | Environment variables | Private settings and bounds | | 16 | Updates and removal | Upgrade/revoke/uninstall | | 17 | Troubleshooting | Errors and recovery | | 18 | API coverage and comparisons | Official and community tradeoffs | | 19 | Versions | Release history and migration | | 20 | FAQ | Accordion answers |

1. What you can ask it

Inspect my available generation models before choosing a supported asset.
Read this existing render's status; do not submit a duplicate.
Prepare a reviewed timeline and submit only the approved sandbox render.
Save this template, then render it with the merge values I selected.
Ingest this selected public source URL after confirmation.
Create an upload URL, keeping its temporary credential in my private file.
Inspect a hosted asset and confirm its exact ID before deletion.

Actual discovery supplies 23 tools: 12 reads and 11 confirmed account operations. The same handlers serve MCP and CLI. Read-only discovery and direct-call refusal agree. These checks do not establish successful provider rendering or GUI installation.

2. Quick install

npm install -g @thenavidm/shotstack-mcp-cli@latest
shotstack-cli --version
shotstack-cli login
shotstack-cli doctor
shotstack-cli tools

Node 22+ is required for manual installation. The shotstack-3.0.0.mcpb archive bundles production dependencies for a compatible desktop host. Complete setup is in INSTALL.md.

After configuring private local credentials:

codex mcp add shotstack -- npx -y @thenavidm/shotstack-mcp-cli@latest
codex mcp list

3. Set up Shotstack access

Private API keys and environments

Sign in to your intended account at app.shotstack.io, open the account menu and choose API Keys.
Select the sandbox or production key for the task. Set SHOTSTACK_ENV=stage or v1 to match. Production is the default; a sandbox key does not turn production URLs into sandbox URLs.
Save the key in an owner-only token file outside repositories. Set SHOTSTACK_TOKEN_FILE to its absolute path. SHOTSTACK_API_KEY in private local settings is the alternative.
Run shotstack-cli doctor, then doctor --network. The network check requests available generation models and does not print their content.
Read the selected schema, review the exact edit/account action and confirm only that operation. Do not submit a production render merely to test installation.

Requests use x-api-key on the fixed api.shotstack.io origin, with /edit, /serve or /ingest and the selected /stage or /v1 prefix. This package does not accept arbitrary API hosts, forward keys through redirects or perform OAuth. login prints setup instructions; it neither saves keys nor creates accounts.

On macOS/Linux, use a private directory (0700) and regular token-only file (0600). Windows users must restrict the file's ACL to their user; POSIX mode checking does not establish Windows ACL protection. Token files cannot be symlinks or exceed 64 KB. They override environment keys and are cached until restart. GUI settings may differ from your shell environment.

Access, plans, credits and limits

The wrapper is free AGPL software. Shotstack access, rendering, generated assets, storage and serving follow the provider's account terms. No account role or OAuth scope bypass is supplied. Request API keys and check your dashboard's balance and current plan before approving charges.

The provider currently documents ten new-account credits valid for 30 days, with no credit card required. Sandbox renders are watermarked, limited to ten minutes and require at least one credit in the balance. AI generation in sandbox still consumes credits. Production rendering is billed by output duration; this wrapper is not a spending or money cap.

Rate limits use a fixed 60-second window per API key, across all plans. Current production/sandbox request limits are Edit 300/150, Serve 600/300 and Ingest 300/120. Wait for the window reset after 429; do not immediately repeat a render.

The local default 150 ms pacing is per account label/process, not a provider quota reservation. Shared keys in several processes still share quota. Mutations never retry automatically. GET 429 retries require an explicit Retry-After of at most ten seconds; missing/longer delays return exit 7. The default maximum is two retries and configurable upper bound five.

Current source limits are 5 GB per file and 10 GB combined source/output disk usage. Local request JSON has a separate 5 MiB cap and responses a 10 MiB cap. The wrapper does not upload local media bytes or automatically collect all pages. Check credit consumption for the selected current model and hosting charges.

Revoke and rotate

Rotate or revoke the intended key through your account's API Keys controls, update private client settings, and restart. Remove the client entry when disconnecting. npm removal does not revoke the provider key, undo renders, remove hosted assets or delete private output files. Keep account records and signed URLs out of GitHub issues and public logs.

4. Connect your client

INSTALL.md provides Codex-first configuration plus optional Claude Code, Claude Desktop archive/manual setup, Cursor, VS Code/Copilot, Windsurf, Zed, Gemini CLI, Cline and Docker. Use Node 22+ on macOS, Windows or Linux; GUI settings and remote development environments need their own accessible private credentials.

Manual MCP launches npx with arguments -y and @thenavidm/shotstack-mcp-cli@latest over stdio. This package has no public HTTP relay. Remote-only clients can use the official https://mcp.shotstack.io/ service with its supported OAuth/API-key setup.

npm installation ships SKILL.md but does not register an agent skill. Add the shipped file through the client's supported skill location. Client approvals and confirm=true are separate; the guard requires the exact requested mutation, not consent inferred from returned content.

5. Check it works

shotstack-cli --version
shotstack-cli doctor
shotstack-cli doctor --network
shotstack-cli list-accounts --agent
shotstack-cli list-models --agent

Help, schemas, discovery and account labels work without a provider key. Network doctor requests GET /edit/{environment}/models without returning its content. Success establishes that account request, not every rendering model or endpoint. Full discovery exposes 23 tools; read-only exposes 12.

For an existing selected render, use get-render --id REAL_RENDER_ID. A job status read should not create a new render. Missing credentials exits 10; invalid input and refused writes exit 2.

6. Output, flags and exit codes

Tool results go to stdout. Errors are JSON on stderr. Reads and generation return structured JSON, so --select can retain nested fields.

shotstack-cli render --help
shotstack-cli schema render
shotstack-cli get-render --id REAL_RENDER_ID --agent --select response.status,response.url

| Flag | What it does | | --- | --- | | --json | JSON output | | --compact | Single-line JSON | | --agent | Compact JSON and no prompts; never confirms a write | | --select a,b.c | Keep selected fields; dotted paths descend and arrays are traversed | | --confirm | Confirm the requested paid media operation | | --no-input, --no-color, --yes | Automation switches; none overrides the spending guard | | --wait=false | Return an accepted job instead of polling | | --download | Save completed media locally; requires waiting for completion |

Global output flags apply to tool commands. doctor has its own --network option and returns a JSON diagnostic.

| Exit code | Meaning | What a script should do | | --- | --- | --- | | 0 | Success | Read stdout | | 1 | Unexpected error | Report it with the command that caused it | | 2 | Usage, invalid input, a refused write, an unknown command or a hidden write | Fix the input or confirm only the requested action | | 3 | Job or local upload file not found | Check the ID/path | | 4 | Authentication or entitlement rejected | Check private credential settings and permissions | | 5 | API, network or polling failure | Inspect an accepted job before another paid submission | | 7 | Rate limited | Wait; do not loop over paid submissions | | 10 | Credentials not configured | Complete local setup |

The underscore spelling also works. generate_asset and generate-asset call the same tool. Nested objects use quoted JSON. Arrays of objects use repeated flags, one JSON object at a time.

7. MCP or CLI and token cost

MCP and CLI use the same input schemas, handlers and confirmation guard: Slipway builds the MCP server, over stdio or --http, and the CLI from each tool's one definition; there is no second API implementation. Choose shell calls for scripts and the local MCP for a stdio AI client.

Measured on 2026-10-05 against 2.0.2, with Claude Code 2.1.286 on Claude Opus 5.5 (one short prompt with and without the server connected, the difference read from the API's own usage figures) and Codex 0.159.3 on gpt-6.1-sol:

| Cost | 2.0.2 | 3.0.0 | | --- | --- | --- | | Claude Code, every tool loaded, every message | 287,446 | 154,114 | | Claude Code's default, tool search, every message | 482 | 480 | | SKILL.md, read once | 1,207 | 1,266 | | Codex over the CLI, one task, median of five | 105,563 | 83,947 | | Codex over MCP, the same task, median of five | 46,793 | 47,033 |

The task was "find the command that renders a template, and the flags it requires". Every tool loaded costs about half as much because Shotstack's edit schema spelled out its clip, track and asset types everywhere they appear, and each is now written once. Over the CLI, four 3.0.0 runs asked which render template, whose answer carries the command's help, where every 2.0.2 run read the command list and then the help: one request fewer. Over MCP, Codex now prints each destination transfer_asset can send a file to, where it printed 2.0.2's as Array<unknown>, 2,039 characters more, while seven other tools print shorter. SKILL.md costs 59 more because it says how approval works over MCP and what exit codes 1 and 2 cover.

Tool-list bytes or characters divided by four are not API usage, and no other offering was measured.

Local --select trims output after receipt; it does not change provider response size or quota. Provider credits remain separate from model tokens.

8. Every tool and argument

Every route and argument below comes from actual stdio discovery and reviewed current upstream schemas. Read exact nested definitions with shotstack-cli schema COMMAND before constructing a body. Native body names, arrays, unions and enums remain exact.

| Tool | Route | Mode | | --- | --- | --- | | render | POST /edit/{environment}/render | Confirm requested operation | | get_render | GET /edit/{environment}/render/{id} | Read | | create_template | POST /edit/{environment}/templates | Confirm requested operation | | list_templates | GET /edit/{environment}/templates | Read | | get_template | GET /edit/{environment}/templates/{id} | Read | | update_template | PUT /edit/{environment}/templates/{id} | Confirm requested operation | | delete_template | DELETE /edit/{environment}/templates/{id} | Confirm requested operation | | render_template | POST /edit/{environment}/templates/render | Confirm requested operation | | probe_media | GET /edit/{environment}/probe/{url} | Read | | generate_asset | POST /edit/{environment}/generate | Confirm requested operation | | get_generated_asset | GET /edit/{environment}/generate/{id} | Read | | list_models | GET /edit/{environment}/models | Read | | get_model | GET /edit/{environment}/models/{id} | Read | | get_asset | GET /serve/{environment}/assets/{id} | Read | | delete_asset | DELETE /serve/{environment}/assets/{id} | Confirm requested operation | | get_asset_by_render_id | GET /serve/{environment}/assets/render/{id} | Read | | transfer_asset | POST /serve/{environment}/assets | Confirm requested operation | | ingest_source | POST /ingest/{environment}/sources | Confirm requested operation | | list_sources | GET /ingest/{environment}/sources | Read | | get_source | GET /ingest/{environment}/sources/{id} | Read | | delete_source | DELETE /ingest/{environment}/sources/{id} | Confirm requested operation | | create_upload_url_file | POST /ingest/{environment}/upload | Confirm requested operation | | list_accounts | Local, no network | Read |

render

shotstack-cli render

| Argument | Required | Type | Details | | --- | --- | --- | --- | | timeline | No; body and guard rules apply | Timeline | See the full input schema. | | output | No; body and guard rules apply | Output | See the full input schema. | | merge | No; body and guard rules apply | array | An array of key/value pairs that provides an easy way to create templates with placeholders. The placeholders can be used to find and replace keys with values. For example you can search for the placeholder {{NAME}} and replace it with the value Jane. Items: MergeField. | | callback | No; body and guard rules apply | string | An optional webhook callback URL used to receive status notifications when a render completes or fails. Notifications are also sent when a rendered video is sent to an output destination. See webhooks for more details. | | disk | No; body and guard rules apply | string | Notice: This option is now deprecated and will be removed. Disk types are handled automatically. Setting a disk type has no effect. The disk type to use for storing footage and assets for each render. local - optimized for high speed rendering with up to 512MB storage mount - optimized for larger file sizes and longer videos with 5GB for source footage and 512MB for output render Values: local, mount. | | instance | No; body and guard rules apply | string | The render instance type to use for processing the edit. s1 - standard instance (default) s2 - standard instance with more resources a1 - accelerated instance for faster rendering Values: s1, s2, a1. default: s1. | | account | No; body and guard rules apply | string | Named private Shotstack account; selects private credentials and stage/v1 environment. | | confirm | No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. | | payload_file | No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: 1. |

A body is required. Use native body flags or one complete payload/payload_file; these cannot be mixed. Required body fields: timeline, output.

get_render

shotstack-cli get-render

| Argument | Required | Type | Details | | --- | --- | --- | --- | | id | Yes | string | Exact resource ID from the selected account. minLength: 1. | | account | No; body and guard rules apply | string | Named private Shotstack account; selects private credentials and stage/v1 environment. |

create_template

shotstack-cli create-template

| Argument | Required | Type | Details | | --- | --- | --- | --- | | name | No; body and guard rules apply | string | The template name | | template | No; body and guard rules apply | Edit | See the full input schema. | | account | No; body and guard rules apply | string | Named private Shotstack account; selects private credentials and stage/v1 environment. | | confirm | No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. | | payload_file | No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: 1. |

A body is required. Use native body flags or one complete payload/payload_file; these cannot be mixed. Required body fields: name.

list_templates

shotstack-cli list-templates

get_template

shotstack-cli get-template

update_template

shotstack-cli update-template

| Argument | Required | Type | Details | | --- | --- | --- | --- | | id | Yes | string | Exact resource ID from the selected account. minLength: 1. | | name | No; body and guard rules apply | string | The template name | | template | No; body and guard rules apply | Edit | See the full input schema. | | account | No; body and guard rules apply | string | Named private Shotstack account; selects private credentials and stage/v1 environment. | | confirm | No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. | | payload_file | No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: 1. |

A body is required. Use native body flags or one complete payload/payload_file; these cannot be mixed. Required body fields: name.

delete_template

shotstack-cli delete-template

render_template

shotstack-cli render-template

| Argument | Required | Type | Details | | --- | --- | --- | --- | | id | No; body and guard rules apply | string | The id of the template to render in UUID format. | | merge | No; body and guard rules apply | array | An array of key/value pairs that provides an easy way to create templates with placeholders. The placeholders can be used to find and replace keys with values. For example you can search for the placeholder {{NAME}} and replace it with the value Jane. Items: MergeField. | | account | No; body and guard rules apply | string | Named private Shotstack account; selects private credentials and stage/v1 environment. | | confirm | No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. | | payload_file | No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: 1. |

A body is required. Use native body flags or one complete payload/payload_file; these cannot be mixed. Required body fields: id.

probe_media

shotstack-cli probe-media

| Argument | Required | Type | Details | | --- | --- | --- | --- | | url | Yes | string | Public HTTPS URL of the selected media file. minLength: 1. format: uri. pattern: ^https://. | | account | No; body and guard rules apply | string | Named private Shotstack account; selects private credentials and stage/v1 environment. |

generate_asset

shotstack-cli generate-asset

| Argument | Required | Type | Details | | --- | --- | --- | --- | | idempotency_key | No; body and guard rules apply | string | A key that makes this request its own generation. Retrying with the same key returns the job it first created instead of generating and billing again, and a new key generates afresh even when the asset matches an earlier one. Without a key, identical assets share one cached result. For 24 hours a key reused for a different asset is rejected; after that it returns its first result. | | asset | No; body and guard rules apply | GenerationAsset | See the full input schema. | | length | No; body and guard rules apply | number | The length, in seconds, of the clip the asset fills. A model that generates to a duration takes it from this value in place of its own duration option. Other models ignore it. | | account | No; body and guard rules apply | string | Named private Shotstack account; selects private credentials and stage/v1 environment. | | confirm | No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. | | payload_file | No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: 1. |

A body is required. Use native body flags or one complete payload/payload_file; these cannot be mixed. Required body fields: asset.

get_generated_asset

shotstack-cli get-generated-asset

list_models

shotstack-cli list-models

get_model

shotstack-cli get-model

get_asset

shotstack-cli get-asset

delete_asset

shotstack-cli delete-asset

get_asset_by_render_id

shotstack-cli get-asset-by-render-id

transfer_asset

shotstack-cli transfer-asset

| Argument | Required | Type | Details | | --- | --- | --- | --- | | url | No; body and guard rules apply | string | The file URL to fetch and transfer. | | id | No; body and guard rules apply | string | An identifier for the asset which must be provided by the client. The identifier does not need to be unique. | | destinations | No; body and guard rules apply | array | Specify the storage locations and hosting services to send the file to. Items: Destinations. | | account | No; body and guard rules apply | string | Named private Shotstack account; selects private credentials and stage/v1 environment. | | confirm | No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. | | payload_file | No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: 1. |

A body is required. Use native body flags or one complete payload/payload_file; these cannot be mixed. Required body fields: url, id, destinations.

ingest_source

shotstack-cli ingest-source

| Argument | Required | Type | Details | | --- | --- | --- | --- | | url | No; body and guard rules apply | string | The URL of the file to be ingested. The URL must be publicly accessible or include credentials. | | outputs | No; body and guard rules apply | Outputs | See the full input schema. | | destinations | No; body and guard rules apply | Destinations | See the full input schema. | | callback | No; body and guard rules apply | string | An optional webhook callback URL used to receive status notifications when sources are uploaded and renditions processed. | | account | No; body and guard rules apply | string | Named private Shotstack account; selects private credentials and stage/v1 environment. | | confirm | No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body and guard rules apply | object | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. | | payload_file | No; body and guard rules apply | string | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. minLength: 1. |

A body is required. Use native body flags or one complete payload/payload_file; these cannot be mixed. Required body fields: .

list_sources

shotstack-cli list-sources

get_source

shotstack-cli get-source

delete_source

shotstack-cli delete-source

create_upload_url_file

shotstack-cli create-upload-url-file

| Argument | Required | Type | Details | | --- | --- | --- | --- | | account | No; body and guard rules apply | string | Named private Shotstack account; selects private credentials and stage/v1 environment. | | confirm | No; body and guard rules apply | boolean | Set true only when the user asked for exactly this action. | | secret_result_file | Yes | string | New absolute JSON file in a private owner-only directory. Signed upload URL stays out of model output; no overwrite. minLength: 1. |

The output file must be new and absolute, in a private directory. It is reserved exclusively before the API call; the signed URL is never returned in model output. This command creates a temporary upload credential; it does not upload file bytes.

list_accounts

shotstack-cli list-accounts

| Argument | Required | Type | Details | | --- | --- | --- | --- | | None | No | None | No arguments |

Nested request definitions

The following definitions are shared by the request schemas. oneOf selects one validated asset branch; $ref names point to the definition heading here. Required fields are specific to the selected branch. Any deeper inline shape remains available through schema COMMAND.

Timeline

A timeline represents the contents of a video edit over time, an audio edit over time, in seconds, or an image layout. A timeline consists of layers called tracks. Tracks are composed of titles, images, audio, html or video segments referred to as clips which are placed along the track at specific starting point and lasting for a specific amount of time.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | soundtrack | No; body and guard rules apply | Soundtrack | A music or audio soundtrack file in mp3 format. Deprecated - use an AudioAsset clip on its own track instead. | | background | No; body and guard rules apply | string | A hexadecimal value for the timeline background colour. Defaults to #000000 (black). | | fonts | No; body and guard rules apply | array | An array of custom fonts to be downloaded for use by the HTML assets. Items: Font. | | tracks | Yes | array | A timeline consists of an array of tracks, each track containing clips. Tracks are layered on top of each other in the same order they are added to the array with the top most track layered over the top of those below it. Ensure that a track containing titles is the top most track so that it is displayed above videos and images. minItems: 1. Items: Track. | | cache | No; body and guard rules apply | boolean | Disable the caching of ingested source footage and assets. See caching for more details. |

Soundtrack

Notice: The Soundtrack is deprecated, use an AudioAsset clip on its own track instead. This type continues to function; no behaviour change for existing integrations. A music or audio file in mp3 format that plays for the duration of the rendered video or the length of the audio file, which ever is shortest.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | src | Yes | string | The URL of the mp3 audio file. The URL must be publicly accessible or include credentials. minLength: 1. pattern: \S. | | effect | No; body and guard rules apply | string | The effect to apply to the audio file fadeIn - fade volume in only fadeOut - fade volume out only fadeInFadeOut - fade volume in and out Values: fadeIn, fadeOut, fadeInFadeOut. | | volume | No; body and guard rules apply | number | Set the volume for the soundtrack between 0 and 1 where 0 is muted and 1 is full volume (defaults to 1). |

Font

Download a custom font to use with the HTML asset type, using the font name in the CSS or font tag. See our custom fonts getting started guide for more details.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | src | Yes | string | The URL of the font file. The URL must be publicly accessible or include credentials. |

Track

A track contains an array of clips. Tracks are layered on top of each other in the order in the array. The top most track will render on top of those below it.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | clips | Yes | array | An array of Clips comprising of TitleClip, ImageClip or VideoClip. minItems: 1. Items: Clip. |

Clip

A clip is a container for a specific type of asset, i.e. a title, image, video, audio or html. You use a Clip to define when an asset will display on the timeline, how long it will play for and transitions, filters and effects to apply to it.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | id | No; body and guard rules apply | string | Optional client-generated identifier. Used by client SDKs (e.g. the Shotstack Studio SDK) to reference a clip across edits without relying on its position in the timeline. The render API does not use this field and it does not appear in render output. | | asset | Yes | Asset | See the full input schema. | | start | Yes | Union | The start position of the Clip on the timeline. | | length | Yes | Union | The duration the Clip should play for. | | fit | No; body and guard rules apply | string | Set how the asset should be scaled to fit the viewport using one of the following options: crop (default) - scale the asset to fill the viewport while maintaining the aspect ratio. The asset will be cropped if it exceeds the bounds of the viewport. cover - stretch the asset to fill the viewport without maintaining the aspect ratio. contain - fit the entire asset within the viewport while maintaining the original aspect ratio. none - preserves the original asset dimensions and does not apply any scaling. Values: cover, contain, crop, none. | | scale | No; body and guard rules apply | Union | Scale the asset to a fraction of the viewport size - i.e. setting the scale to 0.5 will scale asset to half the size of the viewport. This is useful for picture-in-picture video and scaling images such as logos and watermarks. Use a number or an array of Tween objects to create a custom animation. | | width | No; body and guard rules apply | number | Set the width of the clip bounding box in pixels. This constrains the width of the clip, overriding the default behavior where clips fill the viewport width. minimum: 1. maximum: 3840. format: float. | | height | No; body and guard rules apply | number | Set the height of the clip bounding box in pixels. This constrains the height of the clip, overriding the default behavior where clips fill the viewport height. minimum: 1. maximum: 2160. format: float. | | position | No; body and guard rules apply | string | Place the asset in one of nine predefined positions of the viewport. This is most effective for when the asset is scaled and you want to position the element to a specific position. top - top (center) topRight - top right right - right (center) bottomRight - bottom right bottom - bottom (center) bottomLeft - bottom left left - left (center) topLeft - top left center - center Values: top, topRight, right, bottomRight, bottom, bottomLeft, left, topLeft, center. | | offset | No; body and guard rules apply | Offset | Offset the location of the asset relative to its position on the viewport. The offset distance is relative to the width of the viewport - for example an x offset of 0.5 will move the asset half the viewport width to the right. | | transition | No; body and guard rules apply | Transition | See the full input schema. | | effect | No; body and guard rules apply | string | A motion effect to apply to the Clip. zoomIn - slow zoom in zoomOut - slow zoom out slideLeft - slow slide (pan) left slideRight - slow slide (pan) right slideUp - slow slide (pan) up slideDown - slow slide (pan) down The motion effect speed can also be controlled by appending Fast or Slow to the effect, e.g. zoomInFast or slideRightSlow. Values: zoomIn, zoomInSlow, zoomInFast, zoomOut, zoomOutSlow, zoomOutFast, slideLeft, slideLeftSlow, slideLeftFast, slideRight, slideRightSlow, slideRightFast, slideUp, slideUpSlow, slideUpFast, slideDown, slideDownSlow, slideDownFast. | | filter | No; body and guard rules apply | string | A filter effect to apply to the Clip. none - no filter applied blur - blur the scene boost - boost contrast and saturation contrast - increase contrast darken - darken the scene greyscale - remove colour lighten - lighten the scene muted - reduce saturation and contrast negative - negative colors Values: none, blur, boost, contrast, darken, greyscale, lighten, muted, negative. | | opacity | No; body and guard rules apply | Union | Offset an asset on the horizontal axis (left or right). Use a number or an array of Tween objects to create a custom animation. | | transform | No; body and guard rules apply | Transformation | A transformation lets you modify the visual properties of a clip. Available transformations are rotate, skew and flip. Transformations can be combined to create interesting new shapes and effects. | | alias | No; body and guard rules apply | string | A unique identifier for this clip that can be used to reference it from other clips using the alias:// protocol in asset sources. This is useful for features like auto-captioning where a caption asset needs to reference the audio from another clip. pattern: ^[A-Za-z0-9_-]+$. |

Asset

The type of asset to display for the duration of the Clip, i.e. a video clip or an image. Choose from one of the available asset types below.

oneOf: VideoAsset, ImageAsset, TextAsset, RichTextAsset, AudioAsset, LumaAsset, CaptionAsset, RichCaptionAsset, HtmlAsset, Html5Asset, TitleAsset, ShapeAsset, SvgAsset, TextToImageAsset, ImageToVideoAsset, TextToSpeechAsset.

Type: object.

VideoAsset

The VideoAsset adds a video to a Clip. The video can be sourced from a URL (src), generated from a text prompt (prompt), or both. At least one of src or prompt must be provided. - Source URL: set src to the URL of an mp4 (or compatible) video file. - Generated: set prompt to describe the motion. Choose a generator with model and configure it with model-specific options. Models that animate an image take it as options.startSrc (the original image-to-video models use options.inputSrc); the default model generates from the prompt alone. The generated src is filled in automatically. - Both: src acts as a preview placeholder while prompt drives generation — the video is regenerated from the prompt at render time. Unchanged prompts and options resolve from the generation cache.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | type | Yes | string | The type of asset - set to video for videos. Values: video. default: video. | | src | No; body and guard rules apply | string | The video source URL. The URL must be publicly accessible or include credentials. When prompt is also set, src serves as a preview placeholder and the video is regenerated from the prompt at render time. minLength: 1. pattern: \S. | | prompt | No; body and guard rules apply | string | A text prompt to generate the video from. The engine generates a video at render time and fills src automatically; an existing src is treated as a preview placeholder and replaced. Use model to choose the generator and options to configure it. A starting image goes in options.startSrc — or options.inputSrc on the original image-to-video models — on the models that accept one. maxLength: 4000. | | model | No; body and guard rules apply | string | The generation model to use when prompt is set (e.g. seedance-2.0-text-to-video). Defaults to seedance-2.0-text-to-video if omitted. GET /models lists what is available and the options each accepts. | | options | No; body and guard rules apply | object | Model-specific generation settings. Valid keys and values depend on the chosen model and are defined by the model registry. Omitted options use the model's defaults. Unknown or invalid options are rejected. | | transcode | No; body and guard rules apply | boolean | Set to true to force re-encoding of the video during preprocessing. This can help resolve compatibility issues, fix rotation problems, synchronize audio, or convert formats. The video will be processed to ensure optimal compatibility with the rendering engine. | | trim | No; body and guard rules apply | number | The start trim point of the video clip, in seconds (defaults to 0). Videos will start from the in trim point. The video will play until the file ends or the Clip length is reached. | | volume | No; body and guard rules apply | Union | Set the volume of the video clip. Use a number or an array of Tween objects to create custom volume transitions. | | volumeEffect | No; body and guard rules apply | string | Preset volume effects to apply to the video asset fadeIn - fade volume in only fadeOut - fade volume out only fadeInFadeOut - fade volume in and out Values: none, fadeIn, fadeOut, fadeInFadeOut. | | speed | No; body and guard rules apply | Union | Adjust the playback speed of the video clip. Use a number for a constant speed or an array of Tween objects to change speed over time, for example easing from normal speed up to 3x. | | crop | No; body and guard rules apply | Crop | See the full input schema. | | chromaKey | No; body and guard rules apply | ChromaKey | See the full input schema. |

ImageAsset

The ImageAsset adds an image to a Clip. The image can be sourced from a URL (src), generated from a text prompt (prompt), or both. At least one of src or prompt must be provided. - Source URL: set src to the publicly accessible URL of a jpg or png file. - Generated: set prompt to describe the image. Choose a generator with model and configure it with model-specific options; the engine fills src in automatically. - Both: src acts as a preview placeholder while prompt drives generation — the image is regenerated from the prompt at render time. Unchanged prompts and options resolve from the generation cache.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | type | Yes | string | The type of asset - set to image for images. Values: image. default: image. | | src | No; body and guard rules apply | string | The image source URL. The URL must be publicly accessible or include credentials. When prompt is also set, src serves as a preview placeholder and the image is regenerated from the prompt at render time. minLength: 1. pattern: \S. | | prompt | No; body and guard rules apply | string | A text prompt to generate the image from. The engine generates an image at render time and fills src automatically; an existing src is treated as a preview placeholder and replaced. Use model to choose the generator and options to configure it. maxLength: 4000. | | model | No; body and guard rules apply | string | The generation model to use when prompt is set (e.g. flux-schnell, nano-banana-2). Defaults to nano-banana-2 if omitted. Each model's available options are defined by the model registry. | | options | No; body and guard rules apply | object | Model-specific generation settings. Valid keys and values depend on the chosen model and are defined by the model registry. Omitted options use the model's defaults. Unknown or invalid options are rejected. | | crop | No; body and guard rules apply | Crop | See the full input schema. |

TextAsset

Notice: The TextAsset is deprecated, use the RichTextAsset instead. This type continues to function; no behaviour change for existing integrations. The TextAsset is used to add text and titles to a video. The text can be styled with built in and custom Fonts. You can also add a background bounding box used to control wrapping and overflow. Emoticons are also supported.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | type | Yes | string | The type of asset - set to text for text. Values: text. default: text. | | text | Yes | string | The text string to display. | | width | No; body and guard rules apply | integer | Set the width of the HTML asset bounding box in pixels. Text will wrap to fill the bounding box. | | height | No; body and guard rules apply | integer | Set the width of the HTML asset bounding box in pixels. Text and elements will be masked if they exceed the height of the bounding box. | | font | No; body and guard rules apply | TextFont | Font styling properties. | | background | No; body and guard rules apply | TextBackground | Background styling properties. | | alignment | No; body and guard rules apply | TextAlignment | Alignment properties. | | stroke | No; body and guard rules apply | object | Text stroke (outline) properties. | | animation | No; body and guard rules apply | object | Animation properties for text entrance effects. | | ellipsis | No; body and guard rules apply | string | The string to display when text overflows its bounding box. Set to an ellipsis character or custom string to indicate truncated text. |

RichTextAsset

The RichTextAsset provides advanced text rendering with support for custom fonts, gradients, shadows, strokes, animations, and styling options. It offers more flexibility and visual effects than the basic TextAsset.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | type | Yes | string | The type of asset - set to rich-text for rich text. Values: rich-text. default: rich-text. | | text | Yes | string | The text string to display. Maximum 5000 characters. maxLength: 5000. | | font | No; body and guard rules apply | RichTextFont | Font styling properties. | | style | No; body and guard rules apply | RichTextStyle | Text style properties including spacing, line height, and transformations. | | stroke | No; body and guard rules apply | RichTextStroke | Text stroke (outline) properties. | | shadow | No; body and guard rules apply | RichTextShadow | Text shadow properties. | | background | No; body and guard rules apply | RichTextBackground | Background styling properties for the text bounding box. | | border | No; body and guard rules apply | RichTextBorder | Border styling properties for the text bounding box. | | padding | No; body and guard rules apply | Union | Padding inside the text bounding box. Can be a single number (applied to all sides) or an object with individual sides. | | align | No; body and guard rules apply | RichTextAlignment | Text alignment properties (horizontal and vertical). | | animation | No; body and guard rules apply | RichTextAnimation | Animation properties for text entrance effects. |

AudioAsset

The AudioAsset adds audio to a Clip. The audio can be sourced from a URL (src), generated from a text prompt (prompt), or both. At least one of src or prompt must be provided. - Source URL: set src to a publicly accessible audio URL (e.g. mp3). - Generated speech: set prompt to the spoken text and choose a text-to-speech model; set the voice via options. - Generated music or SFX: set prompt describing the sound and choose a music generation model. - Both: src acts as a preview placeholder while prompt drives generation — the audio is regenerated from the prompt at render time. Unchanged prompts and options resolve from the generation cache. - Use model to choose the generator and options to configure it. The generated src is filled in automatically.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | type | Yes | string | The type of asset - set to audio for audio assets. Values: audio. default: audio. | | src | No; body and guard rules apply | string | The audio source URL. The URL must be publicly accessible or include credentials. When prompt is also set, src serves as a preview placeholder and the audio is regenerated from the prompt at render time. minLength: 1. pattern: \S. | | prompt | No; body and guard rules apply | string | A text prompt. For text-to-speech models the prompt is the spoken text; for music models it describes the sound to generate. The generated src is filled in automatically; an existing src is treated as a preview placeholder and replaced. maxLength: 4000. | | model | No; body and guard rules apply | string | The generation model to use when prompt is set (e.g. polly-neural, elevenlabs-tts, elevenlabs-music). Defaults to elevenlabs-tts (with a default voice) if omitted. Each model's available options are defined by the model registry. | | options | No; body and guard rules apply | object | Model-specific generation settings. Valid keys and values depend on the chosen model and are defined by the model registry. Omitted options use the model's defaults. Unknown or invalid options are rejected. | | trim | No; body and guard rules apply | number | The start trim point of the audio clip, in seconds (defaults to 0). Audio will start from the in trim point. The audio will play until the file ends or the Clip length is reached. | | volume | No; body and guard rules apply | Union | Set the volume of the audio clip. Use a number or an array of Tween objects to create custom volume transitions. | | speed | No; body and guard rules apply | number | Adjust the playback speed of the audio clip between 0 (paused) and 10 (10x normal speed), where 1 is normal speed (defaults to 1). Adjusting the speed will also adjust the duration of the clip and may require you to adjust the Clip length. For example, if you set speed to 0.5, the clip will need to be 2x as long to play the entire audio (i.e. original length / 0.5). If you set speed to 2, the clip will need to be half as long to play the entire audio (i.e. original length / 2). minimum: 0. maximum: 10. format: float. | | effect | No; body and guard rules apply | string | The effect to apply to the audio asset fadeIn - fade volume in only fadeOut - fade volume out only fadeInFadeOut - fade volume in and out Values: none, fadeIn, fadeOut, fadeInFadeOut. |

ShapeAsset

The ShapeAsset is used to add shapes to a video. The shape can be styled with a fill and a stroke. You can manipulate properties such as rotation to create dynamic effects like a diamond shape or stripes.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | type | Yes | string | The type of asset - set to shape for shape. Values: shape. default: shape. | | shape | Yes | string | The shape to display. Values: rectangle, circle, line. | | width | No; body and guard rules apply | integer | Sets the width of the bounding box in pixels. This value should be larger than the shape's width. If omitted, the entire viewport width and height will be used. | | height | No; body and guard rules apply | integer | Sets the height of the bounding box in pixels. This value should be larger than the shape's height. If omitted, the entire viewport width and height will be used. | | fill | No; body and guard rules apply | object | Specifies the fill style of the shape. | | stroke | No; body and guard rules apply | object | Specifies the stroke style of the shape. | | rectangle | No; body and guard rules apply | object | Configuration settings for the rectangle shape. Required when shape is set to rectangle. | | circle | No; body and guard rules apply | object | Configuration settings for the circle shape. Required when shape is set to circle. | | line | No; body and guard rules apply | object | Configuration settings for the line shape. Required when shape is set to line. |

LumaAsset

The LumaAsset is used to create luma matte masks, transitions and effects between other assets. A luma matte is a grey scale image or animated video where the black areas are transparent and the white areas solid. The luma matte animation should be provided as an mp4 video file. The src must be a publicly accessible URL to the file.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | type | Yes | string | The type of asset - set to luma for luma mattes. Values: luma. default: luma. | | src | Yes | string | The luma matte source URL. The URL must be publicly accessible or include credentials. minLength: 1. pattern: \S. | | trim | No; body and guard rules apply | number | The start trim point of the luma matte clip, in seconds (defaults to 0). Videos will start from the in trim point. A luma matte video will play until the file ends or the Clip length is reached. |

CaptionAsset

Notice: The CaptionAsset is deprecated, use the RichCaptionAsset instead. The CaptionAsset is used to add captions (subtitles) to a video. It uses a supplied SRT or VTT file which will be read and burnt to the video. Captions can be applied independently from a video or audio file for greater flexibility with styling and layout. For example you can scale, position or crop a video without modifying the captions. To sync captions with a video or audio file use a Video or Audio with matching start and end time.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | type | Yes | string | The type of asset - set to caption for captions. Values: caption. default: caption. | | src | Yes | string | The URL to an SRT or VTT subtitles file, or an alias reference to auto-generate captions from an audio or video clip. For file URLs, the URL must be publicly accessible or include credentials. For auto-captioning, use the format alias://clip-name where clip-name is the alias of an audio, video, or text-to-speech clip. The system will automatically transcribe the audio and detect the language. minLength: 1. pattern: \S. | | font | No; body and guard rules apply | CaptionFont | Font styling properties. | | background | No; body and guard rules apply | CaptionBackground | Background styling properties. | | margin | No; body and guard rules apply | CaptionMargin | Margin properties. | | trim | No; body and guard rules apply | number | The start trim point of the captions, in seconds (defaults to 0). Remove the trim length from the start of the captions and allow it to be synced with video or audio. The captions will play until the file ends or the Clip length is reached. | | speed | No; body and guard rules apply | number | Adjust the playback speed of the captions between 0 (paused) and 10 (10x normal speed) where 1 is normal speed (defaults to 1). Adjusting the speed will also adjust the duration of the clip and may require you to adjust the Clip length. For example, if you set speed to 0.5, the clip will need to be 2x as long to play the entire captions (i.e. original length / 0.5). If you set speed to 2, the clip will need to be half as long to play the entire captions (i.e. original length / 2). minimum: 0. maximum: 10. format: float. |

RichCaptionAsset

The RichCaptionAsset provides word-level caption animations with rich-text styling. It supports karaoke-style highlighting, word-by-word animations, and advanced typography. Captions can be sourced from SRT/VTT/TTML subtitle files, from audio/video media URLs (auto-transcribed), or from alias references to other clips in the same timeline.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | type | Yes | string | The type of asset - set to rich-caption for rich captions. Values: rich-caption. default: rich-caption. | | src | Yes | string | Source for the caption words. Accepts three formats: (1) the URL to a subtitle file (.srt, .vtt, .ttml, or .dfxp) which is parsed directly; (2) the URL to an audio or video media file (.mp4, .mov, .webm, .mp3, .wav, .m4a, .flac, .aac, .ogg, and related formats) which is auto-transcribed; (3) an alias reference in the form alias://clip-name where clip-name is the alias of another audio, video, or text-to-speech clip in the same timeline — the referenced clip's source is auto-transcribed. For file URLs, the URL must be publicly accessible or include credentials. Content is classified at runtime and unsupported content types (HTML, PDF, images, archives) are rejected with a structured error. minLength: 1. | | font | No; body and guard rules apply | object | Font styling properties for inactive words. | | style | No; body and guard rules apply | object | Text style properties including spacing, line height, and transformations. | | stroke | No; body and guard rules apply | RichTextStroke | Text stroke (outline) properties for inactive words. | | shadow | No; body and guard rules apply | RichTextShadow | Text shadow properties. | | background | No; body and guard rules apply | RichTextBackground | Background styling properties for the caption bounding box. | | border | No; body and guard rules apply | RichTextBorder | Border styling properties for the caption bounding box. | | padding | No; body and guard rules apply | Union | Padding inside the caption bounding box. Can be a single number (applied to all sides) or an object with individual sides. | | align | No; body and guard rules apply | RichTextAlignment | Text alignment properties (horizontal and vertical). | | active | No; body and guard rules apply | RichCaptionActive | Styling properties for the active/highlighted word. These override the base styling when a word is being spoken. | | animation | No; body and guard rules apply | RichCaptionAnimation | Word-level animation properties controlling how words are highlighted or revealed. |

RichCaptionActiveFont

Font properties for the active/highlighted word.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | family | No; body and guard rules apply | string | The font family for the active word. Inherits from the base font.family when not set. | | weight | No; body and guard rules apply | JSON | The weight of the font for the active word. Can be a number (100-900) or a string. Inherits from the base font.weight when not set. default: 400. | | color | No; body and guard rules apply | string | The active word color using hexadecimal color notation. pattern: ^#[A-Fa-f0-9]{6}$. | | background | No; body and guard rules apply | string | The background color behind the active word using hexadecimal color notation. pattern: ^#[A-Fa-f0-9]{6}$. | | opacity | No; body and guard rules apply | number | The opacity of the active word where 1 is opaque and 0 is transparent. minimum: 0. maximum: 1. default: 1. | | size | No; body and guard rules apply | number | The font size of the active word in pixels. minimum: 1. maximum: 500. | | textDecoration | No; body and guard rules apply | string | Text decoration to apply to the active word. Values: none, underline, line-through. default: none. |

RichCaptionActive

Styling properties for the active/highlighted word.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | font | No; body and guard rules apply | RichCaptionActiveFont | Font properties for th