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

Argument	Required	Type	Details
`account`	No; body and guard rules apply	string	Named private Shotstack account; selects private credentials and stage/v1 environment.

get_template

shotstack-cli get-template

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.

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

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.
`confirm`	No; body and guard rules apply	boolean	Set true only when the user asked for exactly this action.

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

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.

list_models

shotstack-cli list-models

Argument	Required	Type	Details
`account`	No; body and guard rules apply	string	Named private Shotstack account; selects private credentials and stage/v1 environment.

get_model

shotstack-cli get-model

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.

get_asset

shotstack-cli get-asset

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.

delete_asset

shotstack-cli delete-asset

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.
`confirm`	No; body and guard rules apply	boolean	Set true only when the user asked for exactly this action.

get_asset_by_render_id

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

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.

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

Argument	Required	Type	Details
`account`	No; body and guard rules apply	string	Named private Shotstack account; selects private credentials and stage/v1 environment.

get_source

shotstack-cli get-source

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.

delete_source

shotstack-cli delete-source

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.
`confirm`	No; body and guard rules apply	boolean	Set true only when the user asked for exactly this action.

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 the active word.
`stroke`	No; body and guard rules apply	Union	Stroke properties for the active word. Set to "none" to explicitly remove the base stroke on the active word.
`shadow`	No; body and guard rules apply	Union	Shadow properties for the active word. Set to "none" to explicitly remove the base shadow on the active word.

RichCaptionAnimation

Word-level animation properties for caption effects.

Argument	Required	Type	Details
`style`	Yes	string	The animation style to apply to words: `karaoke` - Word-by-word color fill as spoken (shows all words, highlights active) `highlight` - Word changes to active color when spoken (shows all words) `pop` - Each word scales up when active `fade` - Gradual opacity transition per word `slide` - Words slide in from a direction `bounce` - Spring animation on word appearance `typewriter` - Words appear one by one and stay visible `none` - No animation, all words visible immediately Values: `karaoke`, `highlight`, `pop`, `fade`, `slide`, `bounce`, `typewriter`, `none`. default: `highlight`.
`direction`	No; body and guard rules apply	string	Direction for directional animations (slide). Only applicable when style is `slide`. Values: `left`, `right`, `up`, `down`. default: `up`.

TextToImageAsset

Notice: TextToImageAsset is deprecated. Use ImageAsset with prompt instead. This type continues to function and is internally rewritten to ImageAsset; no behaviour change for existing integrations. The TextToImageAsset lets you create a dynamic image from a text prompt.

Argument	Required	Type	Details
`type`	Yes	string	The type of asset to generate - set to `text-to-image` for text-to-image. Values: `text-to-image`. default: `text-to-image`.
`prompt`	Yes	string	The text prompt to generate an image from.
`width`	No; body and guard rules apply	integer	The width of the image in pixels.
`height`	No; body and guard rules apply	integer	The height of the image in pixels.
`crop`	No; body and guard rules apply	Crop	See the full input schema.

ImageToVideoAsset

Notice: ImageToVideoAsset is deprecated. Use VideoAsset with prompt, a model that accepts a starting image, and that image in options.startSrc — for example seedance-2.0-image-to-video. This type continues to function and is internally rewritten to VideoAsset; no behaviour change for existing integrations. The ImageToVideoAsset lets you create a video from an image and a text prompt.

Argument	Required	Type	Details
`type`	Yes	string	The type of asset to generate - set to `image-to-video` for image-to-video. Values: `image-to-video`. default: `image-to-video`.
`src`	Yes	string	The image source URL. The URL must be publicly accessible or include credentials. minLength: `1`.
`prompt`	No; body and guard rules apply	string	The instructions for modifying the image into a video sequence.
`aspectRatio`	No; body and guard rules apply	string	The aspect ratio (shape) of the video output. Values: `1:1`, `4:3`, `16:9`, `9:16`, `3:4`, `21:9`, `9:21`.
`speed`	No; body and guard rules apply	number	Adjust the playback speed of the video 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 video (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 video (i.e. original length / 2). minimum: `0`. maximum: `10`. format: `float`.
`crop`	No; body and guard rules apply	Crop	See the full input schema.

TextToSpeechAsset

Notice: TextToSpeechAsset is deprecated. Use AudioAsset with prompt (the spoken text) and voice instead. This type continues to function and is internally rewritten to AudioAsset; no behaviour change for existing integrations. The TextToSpeechAsset lets you generate a voice over from text using a text-to-speech service. The generated audio can be trimmed, faded and have its volume and speed adjusted using the same properties available on the AudioAsset.

Argument	Required	Type	Details
`type`	Yes	string	The type of asset - set to `text-to-speech` for text-to-speech. Values: `text-to-speech`. default: `text-to-speech`.
`text`	Yes	string	The text to convert to speech.
`voice`	Yes	string	The voice to use for the text-to-speech conversion.
`language`	No; body and guard rules apply	string	The language code for the text-to-speech conversion.
`newscaster`	No; body and guard rules apply	boolean	Set the voice to newscaster mode. default: `False`.
`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 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. 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`.

HtmlAsset

Notice: The HtmlAsset is deprecated, use the RichTextAsset instead. The HtmlAsset clip type lets you create text based layout and formatting using HTML and CSS. You can also set the height and width of a bounding box for the HTML content to sit within. Text and elements will wrap within the bounding box.

Argument	Required	Type	Details
`type`	Yes	string	The type of asset - set to `html` for HTML. Values: `html`. default: `html`.
`html`	Yes	string	The HTML text string. See list of supported HTML tags.
`css`	No; body and guard rules apply	string	The CSS text string to apply styling to the HTML. See list of support CSS properties.
`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.
`background`	No; body and guard rules apply	string	Apply a background color behind the HTML bounding box using. Set the text color using hexadecimal color notation. Transparency is supported by setting the first two characters of the hex string (opposite to HTML), i.e. #80ffffff will be white with 50% transparency.
`position`	No; body and guard rules apply	string	Place the HTML in one of nine predefined positions within the HTML area. `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`.

Html5Asset

The Html5Asset renders full HTML5/CSS3/JS.

Argument	Required	Type	Details
`type`	Yes	string	The type of asset - set to `html5` for HTML5/CSS3/JS. Values: `html5`. default: `html5`.
`html`	Yes	string	The HTML markup for the asset. Max 1,000,000 characters. maxLength: `1000000`.
`css`	No; body and guard rules apply	string	The CSS string applied to the HTML. Max 500,000 characters. maxLength: `500000`.
`js`	No; body and guard rules apply	string	Optional JavaScript. Use for chart libraries, animations, or DOM manipulation. `gsap`, `d3`, `anime` and `lottie` are always available. CSS animations, transitions, and `Element.animate()` are also captured automatically. Max 500,000 characters. maxLength: `500000`.

TitleAsset

Notice: The TitleAsset is deprecated, use the RichTextAsset instead. The TitleAsset clip type lets you create video titles from a text string and apply styling and positioning.

Argument	Required	Type	Details
`type`	Yes	string	The type of asset - set to `title` for titles. Values: `title`. default: `title`.
`text`	Yes	string	The title text string - i.e. "My Title".
`style`	No; body and guard rules apply	string	Uses a preset to apply font properties and styling to the title. `minimal` `blockbuster` `vogue` `sketchy` `skinny` `chunk` `chunkLight` `marker` `future` `subtitle` Values: `minimal`, `blockbuster`, `vogue`, `sketchy`, `skinny`, `chunk`, `chunkLight`, `marker`, `future`, `subtitle`.
`color`	No; body and guard rules apply	string	Set the text color using hexadecimal color notation. Transparency is supported by setting the first two characters of the hex string (opposite to HTML), i.e. #80ffffff will be white with 50% transparency.
`size`	No; body and guard rules apply	string	Set the relative size of the text using predefined sizes from xx-small to xx-large. `xx-small` `x-small` `small` `medium` `large` `x-large` `xx-large` Values: `xx-small`, `x-small`, `small`, `medium`, `large`, `x-large`, `xx-large`.
`background`	No; body and guard rules apply	string	Apply a background color behind the text. Set the text color using hexadecimal color notation. Transparency is supported by setting the first two characters of the hex string (opposite to HTML), i.e. #80ffffff will be white with 50% transparency. Omit to use transparent background.
`position`	No; body and guard rules apply	string	Place the title in one of nine predefined positions of the viewport. `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 title relative to its position on the screen.

SvgAsset

The SvgAsset is used to add scalable vector graphics (SVG) to a video using raw SVG markup. Supported elements: , , , , , , `` Automatically extracted from SVG markup: - Path data (converted to a single combined path) - Fill color (from fill attribute or `style`) - Stroke color and width (from attributes or `style`) - Dimensions (from `width`/`height` or `viewBox`) - Opacity (from `opacity` attribute) See W3C SVG 2 Specification for path data syntax.

Argument	Required	Type	Details
`type`	Yes	string	The asset type - set to `svg` for SVG assets. Values: `svg`. default: `svg`.
`src`	Yes	string	Raw SVG markup string. The SVG must contain valid SVG elements. The shape, fill, stroke, dimensions and opacity are automatically extracted from the SVG content. minLength: `1`. maxLength: `500000`.

Transition

In and out transitions for a clip - i.e. fade in and fade out

Argument	Required	Type	Details
`in`	No; body and guard rules apply	string	The transition in. Available transitions are: `fade` - fade in `reveal` - reveal from left to right `wipeLeft` - fade across screen to the left `wipeRight` - fade across screen to the right `slideLeft` - move slightly left and fade in `slideRight` - move slightly right and fade in `slideUp` - move slightly up and fade in `slideDown` - move slightly down and fade in `carouselLeft` - slide in from right to left `carouselRight` - slide in from left to right `carouselUp` - slide in from bottom to top `carouselDown` - slide in from top to bottom `shuffleTopRight` - rotate in from top right `shuffleRightTop` - rotate in from right top `shuffleRightBottom` - rotate in from right bottom `shuffleBottomRight` - rotate in from bottom right `shuffleBottomLeft` - rotate in from bottom left `shuffleLeftBottom` - rotate in from left bottom `shuffleLeftTop` - rotate in from left top `shuffleTopLeft` - rotate in from top left `zoom` - fast zoom in The transition speed can also be controlled by appending `Fast` or `Slow` to the transition, e.g. `fadeFast` or `CarouselLeftSlow`. Values: `none`, `fade`, `fadeSlow`, `fadeFast`, `reveal`, `revealSlow`, `revealFast`, `wipeLeft`, `wipeLeftSlow`, `wipeLeftFast`, `wipeRight`, `wipeRightSlow`, `wipeRightFast`, `slideLeft`, `slideLeftSlow`, `slideLeftFast`, `slideRight`, `slideRightSlow`, `slideRightFast`, `slideUp`, `slideUpSlow`, `slideUpFast`, `slideDown`, `slideDownSlow`, `slideDownFast`, `carouselLeft`, `carouselLeftSlow`, `carouselLeftFast`, `carouselRight`, `carouselRightSlow`, `carouselRightFast`, `carouselUp`, `carouselUpSlow`, `carouselUpFast`, `carouselDown`, `carouselDownSlow`, `carouselDownFast`, `shuffleTopRight`, `shuffleTopRightSlow`, `shuffleTopRightFast`, `shuffleRightTop`, `shuffleRightTopSlow`, `shuffleRightTopFast`, `shuffleRightBottom`, `shuffleRightBottomSlow`, `shuffleRightBottomFast`, `shuffleBottomRight`, `shuffleBottomRightSlow`, `shuffleBottomRightFast`, `shuffleBottomLeft`, `shuffleBottomLeftSlow`, `shuffleBottomLeftFast`, `shuffleLeftBottom`, `shuffleLeftBottomSlow`, `shuffleLeftBottomFast`, `shuffleLeftTop`, `shuffleLeftTopSlow`, `shuffleLeftTopFast`, `shuffleTopLeft`, `shuffleTopLeftSlow`, `shuffleTopLeftFast`, `zoom`.
`out`	No; body and guard rules apply	string	The transition out. Available transitions are: `fade` - fade out `reveal` - reveal from right to left `wipeLeft` - fade across screen to the left `wipeRight` - fade across screen to the right `slideLeft` - move slightly left and fade out `slideRight` - move slightly right and fade out `slideUp` - move slightly up and fade out `slideDown` - move slightly down and fade out `carouselLeft` - slide out from right to left `carouselRight` - slide out from left to right `carouselUp` - slide out from bottom to top `carouselDown` - slide out from top to bottom `shuffleTopRight` - rotate out from top right `shuffleRightTop` - rotate out from right top `shuffleRightBottom` - rotate out from right bottom `shuffleBottomRight` - rotate out from bottom right `shuffleBottomLeft` - rotate out from bottom left `shuffleLeftBottom` - rotate out from left bottom `shuffleLeftTop` - rotate out from left top `shuffleTopLeft` - rotate out from top left `zoom` - fast zoom out The transition speed can also be controlled by appending `Fast` or `Slow` to the transition, e.g. `fadeFast` or `CarouselLeftSlow`. Values: `none`, `fade`, `fadeSlow`, `fadeFast`, `reveal`, `revealSlow`, `revealFast`, `wipeLeft`, `wipeLeftSlow`, `wipeLeftFast`, `wipeRight`, `wipeRightSlow`, `wipeRightFast`, `slideLeft`, `slideLeftSlow`, `slideLeftFast`, `slideRight`, `slideRightSlow`, `slideRightFast`, `slideUp`, `slideUpSlow`, `slideUpFast`, `slideDown`, `slideDownSlow`, `slideDownFast`, `carouselLeft`, `carouselLeftSlow`, `carouselLeftFast`, `carouselRight`, `carouselRightSlow`, `carouselRightFast`, `carouselUp`, `carouselUpSlow`, `carouselUpFast`, `carouselDown`, `carouselDownSlow`, `carouselDownFast`, `shuffleTopRight`, `shuffleTopRightSlow`, `shuffleTopRightFast`, `shuffleRightTop`, `shuffleRightTopSlow`, `shuffleRightTopFast`, `shuffleRightBottom`, `shuffleRightBottomSlow`, `shuffleRightBottomFast`, `shuffleBottomRight`, `shuffleBottomRightSlow`, `shuffleBottomRightFast`, `shuffleBottomLeft`, `shuffleBottomLeftSlow`, `shuffleBottomLeftFast`, `shuffleLeftBottom`, `shuffleLeftBottomSlow`, `shuffleLeftBottomFast`, `shuffleLeftTop`, `shuffleLeftTopSlow`, `shuffleLeftTopFast`, `shuffleTopLeft`, `shuffleTopLeftSlow`, `shuffleTopLeftFast`, `zoom`.

Offset

Offsets the position of an asset horizontally or vertically by a relative distance.

Argument	Required	Type	Details
`x`	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.
`y`	No; body and guard rules apply	Union	Offset an asset on the vertical axis (up or down). Use a number or an array of Tween objects to create a custom animation.

Crop

Crop the sides of an asset by a relative amount. The size of the crop is specified using a scale between 0 and 1, relative to the screen width - i.e a left crop of 0.5 will crop half of the asset from the left, a top crop of 0.25 will crop the top by quarter of the asset.

Argument	Required	Type	Details
`top`	No; body and guard rules apply	number	Crop from the top of the asset minimum: `0`. maximum: `1`. format: `float`.
`bottom`	No; body and guard rules apply	number	Crop from the bottom of the asset minimum: `0`. maximum: `1`. format: `float`.
`left`	No; body and guard rules apply	number	Crop from the left of the asset minimum: `0`. maximum: `1`. format: `float`.
`right`	No; body and guard rules apply	number	Crop from the left of the asset minimum: `0`. maximum: `1`. format: `float`.

Transformation

Apply one or more transformations to a clip. Transformations alter the visual properties of a clip and can be combined to create new shapes and effects.

Argument	Required	Type	Details
`rotate`	No; body and guard rules apply	RotateTransformation	See the full input schema.
`skew`	No; body and guard rules apply	SkewTransformation	See the full input schema.
`flip`	No; body and guard rules apply	FlipTransformation	See the full input schema.

RotateTransformation

Rotate a clip by the specified angle in degrees. Rotation origin is set based on the clips position.

Argument	Required	Type	Details
`angle`	No; body and guard rules apply	Union	Rotate a clip by the specified angle in degrees. Use a number or an array of Tween objects to create a custom animation.

SkewTransformation

Skew a clip so its edges are sheared at an angle. Use values between -100 and 100. Values over 3 or under -3 will skew the clip almost flat.

Argument	Required	Type	Details
`x`	No; body and guard rules apply	Union	Skew the clip along it's x axis.
`y`	No; body and guard rules apply	Union	Skew the clip along it's y axis.

FlipTransformation

Flip a clip vertically or horizontally. Acts as a mirror effect of the clip along the selected plane.

Argument	Required	Type	Details
`horizontal`	No; body and guard rules apply	boolean	Flip a clip horizontally.
`vertical`	No; body and guard rules apply	boolean	Flip a clip vertically.

TextFont

Font properties for text.

Argument	Required	Type	Details
`family`	No; body and guard rules apply	string	The font family name. This must be Family name embedded in the font, i.e. "Open Sans".
`color`	No; body and guard rules apply	string	The text color using hexadecimal color notation.
`opacity`	No; body and guard rules apply	number	The opacity of the text where 1 is opaque and 0 is transparent.
`size`	No; body and guard rules apply	integer	The size of the font in pixels (px).
`weight`	No; body and guard rules apply	integer	The weight of the font. 100 is lightest, 900 is heaviest (boldest).
`lineHeight`	No; body and guard rules apply	number	The line height of the font as a ratio of the font size.

TextBackground

Displays a background box behind the text.

Argument	Required	Type	Details
`color`	No; body and guard rules apply	string	The background color using hexadecimal color notation. pattern: `^#[A-Fa-f0-9]{6}$`.
`opacity`	No; body and guard rules apply	number	The opacity of the background where 1 is opaque and 0 is transparent. minimum: `0`. maximum: `1`.
`padding`	No; body and guard rules apply	number	Padding inside the background box in pixels. minimum: `0`. maximum: `100`.
`borderRadius`	No; body and guard rules apply	number	The border radius of the background box in pixels for rounded corners. minimum: `0`.
`wrap`	No; body and guard rules apply	boolean	Not supported on legacy `text` assets. Accepted here only so validators can emit a clear migration error pointing users to `rich-text` or `rich-caption`, which support background wrapping natively.

TextAlignment

Horizontal and vertical alignment properties for text.

Argument	Required	Type	Details
`horizontal`	No; body and guard rules apply	string	The horizontal alignment of the text. Value must be one of: `left` `center` `right` Values: `left`, `center`, `right`.
`vertical`	No; body and guard rules apply	string	The vertical alignment of the text. Value must be one of: `top` `center` `bottom` Values: `top`, `center`, `bottom`.

RichTextFont

Font properties for rich text.

Argument	Required	Type	Details
`family`	No; body and guard rules apply	string	The font family name. This must be the Family name embedded in the font, i.e. "Open Sans". default: `Open Sans`.
`size`	No; body and guard rules apply	integer	The size of the font in pixels (px). Must be between 1 and 500. minimum: `1`. maximum: `500`. default: `24`.
`weight`	No; body and guard rules apply	JSON	The weight of the font. Can be a number (100-900) or a string ('normal', 'bold', etc.). 100 is lightest, 900 is heaviest (boldest). default: `400`.
`style`	No; body and guard rules apply	string	The font style. Values: `normal`, `italic`. default: `normal`.
`color`	No; body and guard rules apply	string	The text color using hexadecimal color notation. pattern: `^#[A-Fa-f0-9]{6}$`. default: `#000000`.
`opacity`	No; body and guard rules apply	number	The opacity of the text where 1 is opaque and 0 is transparent. minimum: `0`. maximum: `1`. default: `1`.
`background`	No; body and guard rules apply	string	The background color behind the text using hexadecimal color notation. pattern: `^#[A-Fa-f0-9]{6}$`.
`stroke`	No; body and guard rules apply	RichTextStroke	Text stroke (outline) properties.

RichTextStyle

Text style properties including spacing, line height, and transformations.

Argument	Required	Type	Details
`letterSpacing`	No; body and guard rules apply	number	Additional spacing between letters in pixels. Can be negative for tighter spacing. default: `0`.
`wordSpacing`	No; body and guard rules apply	number	Additional spacing between words in pixels. A value of 0 uses the font's natural space width. minimum: `0`. default: `0`.
`lineHeight`	No; body and guard rules apply	number	The line height as a multiplier of the font size. Must be between 0 and 10. minimum: `0`. maximum: `10`. default: `1.2`.
`textTransform`	No; body and guard rules apply	string	Text transformation to apply. Values: `none`, `uppercase`, `lowercase`, `capitalize`. default: `none`.
`textDecoration`	No; body and guard rules apply	string	Text decoration to apply. Values: `none`, `underline`, `line-through`. default: `none`.
`gradient`	No; body and guard rules apply	RichTextGradient	Gradient fill for text instead of solid color.

RichTextGradient

Gradient properties for text fill.

Argument	Required	Type	Details
`type`	No; body and guard rules apply	string	The type of gradient. Values: `linear`, `radial`. default: `linear`.
`angle`	No; body and guard rules apply	number	The angle of the gradient in degrees (for linear gradients). Must be between 0 and 360. minimum: `0`. maximum: `360`. default: `0`.
`stops`	Yes	array	Gradient color stops. Must have at least 2 stops. minItems: `2`. Items: object.

RichTextStroke

Text stroke (outline) properties.

Argument	Required	Type	Details
`width`	No; body and guard rules apply	number	The width of the stroke in pixels. Must be 0 or greater. minimum: `0`. default: `0`.
`color`	No; body and guard rules apply	string	The stroke color using hexadecimal color notation. pattern: `^#[A-Fa-f0-9]{6}$`. default: `#000000`.
`opacity`	No; body and guard rules apply	number	The opacity of the stroke where 1 is opaque and 0 is transparent. minimum: `0`. maximum: `1`. default: `1`.

RichTextShadow

Text shadow properties.

Argument	Required	Type	Details
`offsetX`	No; body and guard rules apply	number	Horizontal offset of the shadow in pixels. Positive values move right, negative left. default: `0`.
`offsetY`	No; body and guard rules apply	number	Vertical offset of the shadow in pixels. Positive values move down, negative up. default: `0`.
`blur`	No; body and guard rules apply	number	The blur radius of the shadow in pixels. Must be 0 or greater. minimum: `0`. default: `0`.
`color`	No; body and guard rules apply	string	The shadow color using hexadecimal color notation. pattern: `^#[A-Fa-f0-9]{6}$`. default: `#000000`.
`opacity`	No; body and guard rules apply	number	The opacity of the shadow where 1 is opaque and 0 is transparent. minimum: `0`. maximum: `1`. default: `0.5`.

RichTextBackground

Background styling properties for the text bounding box.

Argument	Required	Type	Details
`color`	No; body and guard rules apply	string	The background color using hexadecimal color notation. pattern: `^#[A-Fa-f0-9]{6}$`.
`opacity`	No; body and guard rules apply	number	The opacity of the background where 1 is opaque and 0 is transparent. minimum: `0`. maximum: `1`. default: `1`.
`borderRadius`	No; body and guard rules apply	number	The border radius of the background box in pixels. Must be 0 or greater. minimum: `0`. default: `0`.
`wrap`	No; body and guard rules apply	boolean	When true, the background pill shrinks to fit the rendered text bounding box plus the asset's padding (and stroke width, if present), producing a pill or badge effect. When false (default), the background fills the full asset content area. Available on rich-text and rich-caption assets only; not supported on legacy `type: text`. default: `False`.
`padding`	No; body and guard rules apply	integer	Inner padding in pixels between the wrap pill edge and the rendered text. Only takes effect when `wrap: true`. When omitted, the renderer applies a sensible default proportional to the font size (approximately 12% of the active page font size on rich-caption assets). Set to 0 for a pill that hugs the text exactly. Available on rich-text and rich-caption assets only. minimum: `0`. maximum: `200`.

RichTextAlignment

Text alignment properties (horizontal and vertical).

Argument	Required	Type	Details
`horizontal`	No; body and guard rules apply	string	The horizontal alignment of the text. Values: `left`, `center`, `right`. default: `center`.
`vertical`	No; body and guard rules apply	string	The vertical alignment of the text within the bounding box. Values: `top`, `middle`, `bottom`. default: `middle`.

RichTextAnimation

Animation properties for text entrance effects.

Argument	Required	Type	Details
`preset`	Yes	string	The animation preset to apply. Available presets: `fadeIn` - fadeIn in animation `slideIn` - slide in from a direction `typewriter` - typewriter effect `ascend` - ascend from a direction `shift` - shift in from a direction `movingLetters` - letters move in from a direction Values: `fadeIn`, `slideIn`, `typewriter`, `ascend`, `shift`, `movingLetters`.
`duration`	No; body and guard rules apply	number	Override animation duration in seconds. Must be between 0.1 and 30 seconds. minimum: `0.1`. maximum: `30`.
`style`	No; body and guard rules apply	string	Animation style - animate by character or by word. Only applicable for typewriter and shift animations. Values: `character`, `word`.
`direction`	No; body and guard rules apply	string	Direction for directional animations. Required for slideIn, ascend, shift, and movingLetters presets. `ascend` - supports: up, down `shift` - supports: left, right, up, down `slideIn` - supports: left, right, up, down `movingLetters` - supports: left, right, up, down Values: `left`, `right`, `up`, `down`.

RichTextBorder

Border styling properties for the text bounding box.

Argument	Required	Type	Details
`width`	No; body and guard rules apply	number	The width of the border in pixels. Must be 0 or greater. minimum: `0`. default: `0`.
`color`	No; body and guard rules apply	string	The border color using hexadecimal color notation. pattern: `^#[A-Fa-f0-9]{6}$`. default: `#000000`.
`opacity`	No; body and guard rules apply	number	The opacity of the border where 1 is opaque and 0 is transparent. minimum: `0`. maximum: `1`. default: `1`.
`radius`	No; body and guard rules apply	number	The border radius in pixels for rounded corners. Must be 0 or greater. minimum: `0`. default: `0`.

RichTextPadding

Padding properties for individual sides of the text bounding box.

Argument	Required	Type	Details
`top`	No; body and guard rules apply	number	Top padding in pixels. minimum: `0`. default: `0`.
`right`	No; body and guard rules apply	number	Right padding in pixels. minimum: `0`. default: `0`.
`bottom`	No; body and guard rules apply	number	Bottom padding in pixels. minimum: `0`. default: `0`.
`left`	No; body and guard rules apply	number	Left padding in pixels. minimum: `0`. default: `0`.

CaptionFont

Font properties for captions text.

Argument	Required	Type	Details
`family`	No; body and guard rules apply	string	The font family name. This must be Family name embedded in the font, i.e. "Open Sans".
`color`	No; body and guard rules apply	string	The text color using hexadecimal color notation.
`opacity`	No; body and guard rules apply	number	The opacity of the text where 1 is opaque and 0 is transparent.
`size`	No; body and guard rules apply	integer	The size of the font in pixels (px).
`lineHeight`	No; body and guard rules apply	number	The line height of the font as a ratio of the font size.
`stroke`	No; body and guard rules apply	string	The stroke color of the font using hexadecimal color notation.
`strokeWidth`	No; body and guard rules apply	number	The width of the stroke in pixels.

CaptionBackground

Displays a background box behind the caption text.

Argument	Required	Type	Details
`color`	No; body and guard rules apply	string	The background color using hexadecimal color notation.
`opacity`	No; body and guard rules apply	number	The opacity of the background color.
`padding`	No; body and guard rules apply	integer	The padding inside the background box in pixels.
`borderRadius`	No; body and guard rules apply	integer	The border radius of the background box in pixels.

CaptionMargin

The margin properties for captions. Margins are used to position the caption text and background on the screen.

Argument	Required	Type	Details
`top`	No; body and guard rules apply	number	The margin above the text. Pushes captions down the screen.
`left`	No; body and guard rules apply	number	The margin to the left of the text. Pushes captions to the right.
`right`	No; body and guard rules apply	number	The margin to the right of the text. Pushes captions to the left.

ChromaKey

Chroma key is a technique that replaces a specific color in a video with a different background image or video, enabling seamless integration of diverse environments. Commonly used for green screen and blue screen effects.

Argument	Required	Type	Details
`color`	Yes	string	The chroma key color as a hex value. Use green (#00b140) for green screens or blue (#0000FF) for blue screens. Any valid hex color can be used as the key color. pattern: `^#[0-9a-fA-F]{6}$`.
`threshold`	No; body and guard rules apply	integer	Pixels within this distance from the key color are eliminated by setting their alpha values to zero. minimum: `0`. maximum: `250`.
`halo`	No; body and guard rules apply	integer	Pixels within the halo distance from the threshold boundary are given an increasing alpha value based on their distance from the threshold. minimum: `0`. maximum: `250`.

Tween

Use a Tween to animate properties over time. The following properties are currently supported and can be animated: Opacity - animate the transparency of a clip. Offset - animate the x and y position of a clip. Rotation - animate the rotation of a clip. Skew - animate the horizontal and vertical shearing effect. Volume - animate the audio volume of a clip.

Argument	Required	Type	Details
`from`	No; body and guard rules apply	JSON	The initial property value at the start of the animation.
`to`	No; body and guard rules apply	JSON	The final property value at the end of the animation.
`start`	No; body and guard rules apply	number	The time in seconds when the animation starts, relative to the clip, not the timeline.
`length`	No; body and guard rules apply	number	The duration of the animation in seconds.
`interpolation`	No; body and guard rules apply	string	The interpolation method to use for the animation. Available options are: `linear` - a linear interpolation between the start and end values. `bezier` - a bezier curve interpolation between the start and end values. `constant` - an interpolation where the property instantly jumps from the start to the end value, without any gradual transition. Values: `linear`, `bezier`, `constant`.
`easing`	No; body and guard rules apply	string	The easing function to use for the animation. Easing controls the rate of change of the animated value, allowing for more natural motion by speeding up or slowing down the animation at different points. Only applicable if interpolation is set to `bezier`. Values: `ease`, `easeIn`, `easeOut`, `easeInOut`, `easeInQuad`, `easeInCubic`, `easeInQuart`, `easeInQuint`, `easeInSine`, `easeInExpo`, `easeInCirc`, `easeInBack`, `easeOutQuad`, `easeOutCubic`, `easeOutQuart`, `easeOutQuint`, `easeOutSine`, `easeOutExpo`, `easeOutCirc`, `easeOutBack`, `easeInOutQuad`, `easeInOutCubic`, `easeInOutQuart`, `easeInOutQuint`, `easeInOutSine`, `easeInOutExpo`, `easeInOutCirc`, `easeInOutBack`.

MergeField

A merge field consists of a key; find, and a value; replace. Merge fields can be used to replace placeholders within the JSON edit to create re-usable templates. Placeholders should be a string with double brace delimiters, i.e. "{{NAME}}". A placeholder can be used for any value within the JSON edit.

Argument	Required	Type	Details
`find`	Yes	string	The string to find without delimiters.
`replace`	Yes	JSON	The replacement value. The replacement can be any valid JSON type - string, boolean, number, etc...

Output

The output format, render range and type of media to generate. For all formats except mp3, either resolution or size (with both width and height) must be specified.

Argument	Required	Type	Details
`format`	Yes	string	The output format and type of media file to generate. `mp4` - mp4 video file `gif` - animated gif `jpg` - jpg image file `png` - png image file `bmp` - bmp image file `mp3` - mp3 audio file (audio only) Values: `mp4`, `gif`, `mp3`, `jpg`, `png`, `bmp`.
`resolution`	No; body and guard rules apply	string	The preset output resolution of the video or image. For custom sizes use the `size` property. Either `resolution` or `size` (with both `width` and `height`) must be specified for all formats except `mp3`. `preview` - 512px x 288px @ 15fps `mobile` - 640px x 360px @ 25fps `sd` - 1024px x 576px @ 25fps `hd` - 1280px x 720px @ 25fps `1080` - 1920px x 1080px @ 25fps `4k` - 3840px x 2160px @ 25fps Values: `preview`, `mobile`, `sd`, `hd`, `1080`, `4k`.
`aspectRatio`	No; body and guard rules apply	string	The aspect ratio (shape) of the video or image. Useful for social media output formats. Options are: `16:9` (default) - regular landscape/horizontal aspect ratio `9:16` - vertical/portrait aspect ratio `1:1` - square aspect ratio `4:5` - short vertical/portrait aspect ratio `4:3` - legacy TV aspect ratio Values: `16:9`, `9:16`, `1:1`, `4:5`, `4:3`.
`size`	No; body and guard rules apply	Size	See the full input schema.
`fps`	No; body and guard rules apply	number	Override the default frames per second. Useful for when the source footage is recorded at 30fps, i.e. on mobile devices. Lower frame rates can be used to add cinematic quality (24fps) or to create smaller file size/faster render times or animated gifs (12 or 15fps). Default is 25fps. `12` - 12fps `15` - 15fps `24` - 24fps `23.976` - 23.976fps `25` (default) - 25fps `29.97` - 29.97fps `30` - 30fps `48` - 48fps `50` - 50fps `59.94` - 59.94fps `60` - 60fps Values: `12`, `15`, `23.976`, `24`, `25`, `29.97`, `30`, `48`, `50`, `59.94`, `60`.
`scaleTo`	No; body and guard rules apply	string	Override the resolution and scale the video or image to render at a different size. When using scaleTo the asset should be edited at the resolution dimensions, i.e. use font sizes that look best at HD, then use scaleTo to output the file at SD and the text will be scaled to the correct size. This is useful if you want to create multiple asset sizes. `preview` - 512px x 288px @ 15fps `mobile` - 640px x 360px @ 25fps `sd` - 1024px x 576px @25fps `hd` - 1280px x 720px @25fps `1080` - 1920px x 1080px @25fps Values: `preview`, `mobile`, `sd`, `hd`, `1080`, `4k`.
`quality`	No; body and guard rules apply	string	Adjust the output quality of the video, image or audio. Adjusting quality affects render speed, download speeds and storage requirements due to file size. The default `medium` provides the most optimized choice for all three factors. `verylow` - reduced quality, smallest file size `low` - slightly reduced quality, smaller file size `medium` (default) - optimized quality, render speeds and file size `high` - slightly increased quality, larger file size `veryhigh` - highest quality, largest file size Values: `verylow`, `low`, `medium`, `high`, `veryhigh`.
`repeat`	No; body and guard rules apply	boolean	Loop settings for gif files. Set to `true` to loop, `false` to play only once.
`mute`	No; body and guard rules apply	boolean	Mute the audio track of the output video. Set to `true` to mute, `false` to un-mute.
`range`	No; body and guard rules apply	Range	See the full input schema.
`poster`	No; body and guard rules apply	Poster	Generate a poster image from a specific point on the timeline.
`thumbnail`	No; body and guard rules apply	Thumbnail	Generate a thumbnail image from a specific point on the timeline.
`destinations`	No; body and guard rules apply	array	Specify the storage locations and hosting services to send rendered videos to. Items: Destinations.

Size

Set a custom size for a video or image in pixels. When using a custom size omit the resolution and aspectRatio. Custom sizes must be divisible by 2 based on the encoder specifications.

Argument	Required	Type	Details
`width`	No; body and guard rules apply	integer	Set a custom width for the video or image file in pixels. Value must be divisible by 2. Maximum video width is 1920px, maximum image width is 4096px. minimum: `1`. maximum: `4096`.
`height`	No; body and guard rules apply	integer	Set a custom height for the video or image file in pixels. Value must be divisible by 2. Maximum video height is 1920px, maximum image height is 4096px. minimum: `1`. maximum: `4096`.

Range

Specify a time range to render, i.e. to render only a portion of a video or audio file. Omit this setting to export the entire video. Range can also be used to render a frame at a specific time point - setting a range and output format as jpg will output a single frame image at the range start point.

Argument	Required	Type	Details
`start`	No; body and guard rules apply	number	The point on the timeline, in seconds, to start the render from - i.e. start at second 3. minimum: `0`. format: `float`.
`length`	No; body and guard rules apply	number	The length of the portion of the video or audio to render - i.e. render 6 seconds of the video. minimum: `0`. format: `float`.

Poster

Generate a poster image for the video at a specific point from the timeline. The poster image size will match the size of the output video.

Argument	Required	Type	Details
`capture`	Yes	number	The point on the timeline in seconds to capture a single frame to use as the poster image.

Thumbnail

Generate a thumbnail image for the video or image at a specific point from the timeline.

Argument	Required	Type	Details
`capture`	Yes	number	The point on the timeline in seconds to capture a single frame to use as the thumbnail image.
`scale`	Yes	number	Scale the thumbnail size to a fraction of the viewport size - i.e. setting the scale to 0.5 will scale the thumbnail to half the size of the viewport. minimum: `0`. maximum: `1`.

Destinations

A destination is a location where assets can be sent to for serving or hosting. Videos, images and audio files that are rendered by the Edit API and source and rendition files generated by the Ingest API can be sent to destinations. You can also fetch a file from any public URL and transfer it to a destination. A file can be sent to one or more destinations including 3rd party destinations. By default all ingested and generated assets are automatically sent to the Shotstack hosting destination. You can opt-out from by setting the Shotstack destination exclude property to true.

anyOf: ShotstackDestination, MuxDestination, S3Destination, GoogleCloudStorageDestination, GoogleDriveDestination, VimeoDestination, object, object, object.

Type: object.

ShotstackDestination

Send videos and assets to the Shotstack hosting and CDN service. This destination is enabled by default.

Argument	Required	Type	Details
`provider`	Yes	string	The destination to send assets to - set to `shotstack` for Shotstack hosting and CDN. default: `shotstack`.
`exclude`	No; body and guard rules apply	boolean	Set to `true` to opt-out from the Shotstack hosting and CDN service. All files must be downloaded within 24 hours of rendering.

MuxDestination

Notice: The Mux destination is deprecated. It continues to work, with no behaviour change for existing integrations. Send videos to the Mux video hosting and streaming service. Mux credentials are required and added via the dashboard, not in the request.

Argument	Required	Type	Details
`provider`	Yes	string	The destination to send video to - set to `mux` for Mux. default: `mux`.
`options`	No; body and guard rules apply	MuxDestinationOptions	Additional Mux configuration and features.

MuxDestinationOptions

Notice: MuxDestinationOptions, like the Mux destination, is deprecated. It continues to work, with no behaviour change for existing integrations. Pass additional options to control how Mux processes video. Currently supports playback_policy and passthrough options.

Argument	Required	Type	Details
`playbackPolicy`	No; body and guard rules apply	array	Sets the Mux `playback_policy` option. Value is an array of strings - use `public`, `signed`, or both. Items: string.
`passthrough`	No; body and guard rules apply	string	Sets the Mux `passthrough` option. Max 255 characters. maxLength: `255`.

S3Destination

Send videos and assets to an Amazon S3 bucket. Send files to any region with your own prefix and filename. AWS credentials are required and added via the dashboard, not in the request.

Argument	Required	Type	Details
`provider`	Yes	string	The destination to send assets to - set to `s3` for S3. default: `s3`.
`options`	No; body and guard rules apply	S3DestinationOptions	Additional S3 configuration options.

S3DestinationOptions

Pass additional options to control how files are stored in S3.

Argument	Required	Type	Details
`region`	Yes	string	Choose the region to send the file to. Must be a valid AWS region string like `us-east-1` or `ap-southeast-2`.
`bucket`	Yes	string	The bucket name to send files to. The bucket must exist in the AWS account before files can be sent.
`prefix`	No; body and guard rules apply	string	A prefix for the file being sent. This is typically a folder name, i.e. `videos` or `customerId/videos`.
`filename`	No; body and guard rules apply	string	Use your own filename instead of the default filenames generated by Shotstack. Note: omit the file extension as this will be appended depending on the output format. Also `-poster.jpg` and `-thumb.jpg` will be appended for poster and thumbnail images.
`acl`	No; body and guard rules apply	string	Sets the S3 Access Control List (acl) permissions. Default is `private`. Must use a valid S3 Canned ACL.

GoogleCloudStorageDestination

Send videos and assets to a Google Cloud Storage bucket. Send files with your own prefix and filename. Google Cloud credentials are required and added via the dashboard, not in the request.

Argument	Required	Type	Details
`provider`	Yes	string	The destination to send assets to - set to `google-cloud-storage` for Google Cloud Storage. default: `google-cloud-storage`.
`options`	No; body and guard rules apply	GoogleCloudStorageDestinationOptions	Additional Google Cloud Storage configuration options.

GoogleCloudStorageDestinationOptions

Pass additional options to control how files are stored in Google Cloud Storage.

Argument	Required	Type	Details
`bucket`	Yes	string	The bucket name to send files to. The bucket must exist in the Google Cloud Storage account before files can be sent.
`prefix`	No; body and guard rules apply	string	A prefix for the file being sent. This is typically a folder name, i.e. `videos` or `customerId/videos`.
`filename`	No; body and guard rules apply	string	Use your own filename instead of the default filenames generated by Shotstack. Note: omit the file extension as this will be appended depending on the output format. Also `-poster.jpg` and `-thumb.jpg` will be appended for poster and thumbnail images.

GoogleDriveDestination

Send rendered videos and assets to the Google Drive cloud storage service. Google Drive uses OAuth and you must authenticate and link your Google account via dashboard, not in the request.

Argument	Required	Type	Details
`provider`	Yes	string	The destination to send assets to - set to `google-drive` for Google Drive. default: `google-drive`.
`options`	No; body and guard rules apply	GoogleDriveDestinationOptions	Additional Google Drive configuration and features. If omitted, files are saved to the root of My Drive using the default Shotstack filename.

GoogleDriveDestinationOptions

Pass the folder ID and options to configure how assets are stored in Google Drive.

Argument	Required	Type	Details
`folderId`	No; body and guard rules apply	string	The Google Drive folder ID where the asset will be stored. If omitted, the asset is saved to the root of My Drive. The folder ID can be retrieved from the URL when logged in to Google Drive, e.g. https://drive.google.com/drive/u/0/folders/1r-eTY6OLO8tzQRKwMyq-fIrQ_7AJEI6A.
`filename`	No; body and guard rules apply	string	Use your own filename instead of the default filenames generated by Shotstack. Note: omit the file extension as this will be appended depending on the output format. Also `-poster.jpg` and `-thumb.jpg` will be appended for poster and thumbnail images.

VimeoDestination

Send videos to Vimeo video hosting and streaming service. Vimeo credentials are required and added via the dashboard, not in the request.

Argument	Required	Type	Details
`provider`	Yes	string	The destination to send video to - set to `vimeo` for Vimeo. default: `vimeo`.
`options`	No; body and guard rules apply	VimeoDestinationOptions	Additional Vimeo configuration and features.

VimeoDestinationOptions

Pass additional options to control how Vimeo publishes video, including name, description and privacy settings.

Argument	Required	Type	Details
`name`	No; body and guard rules apply	string	A name or title for the video that will be displayed on the Vimeo website.
`description`	No; body and guard rules apply	string	A description of the video that will be displayed on the Vimeo website.
`privacy`	No; body and guard rules apply	VimeoDestinationPrivacyOptions	Options to control the visibility of videos and privacy features.
`folderUri`	No; body and guard rules apply	string	The Vimeo folder URI to upload the video to. The folder must already exist in your Vimeo account.

VimeoDestinationPrivacyOptions

Options to control the visibility of videos and privacy features.

Argument	Required	Type	Details
`view`	No; body and guard rules apply	string	Set who can view the videos. Available options are: `anybody` - Anyone can view the video. `nobody` - Only the video owner can view the video. `contacts` - Only contacts can view the video. `password` - A password is required to view the video. `unlisted` - The video is not listed on Vimeo. Values: `anybody`, `nobody`, `contacts`, `password`, `unlisted`.
`embed`	No; body and guard rules apply	string	Set who can embed the video. Available options are: `public` - Anyone can embed the video. `private` - Only the video owner can embed the video. `whitelist` - Only whitelisted domains can embed the video. Values: `public`, `private`, `whitelist`.
`comments`	No; body and guard rules apply	string	Set who can comment on the video. Available options are: `anybody` - Anyone can comment on the video. `nobody` - Only the video owner can comment on the video. `contacts` - Only contacts can comment on the video. Values: `anybody`, `nobody`, `contacts`.
`download`	No; body and guard rules apply	boolean	Set whether the video can be downloaded.
`add`	No; body and guard rules apply	boolean	Set whether other users can add the video to their collections.

Edit

An edit defines the arrangement of a video on a timeline, an audio edit or an image design and the output format. Video assets are automatically preprocessed to fix common compatibility issues before rendering. You can control preprocessing behavior using the transcode flag on video assets.

Argument	Required	Type	Details
`timeline`	Yes	Timeline	See the full input schema.
`output`	Yes	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`.

GenerationAsset

An image, video or audio asset to generate from a text prompt.

Argument	Required	Type	Details
`type`	Yes	string	The kind of asset to generate. Values: `image`, `video`, `audio`.
`prompt`	Yes	string	A description of the asset to generate. For text-to-speech models it is the text spoken. minLength: `1`. maxLength: `4000`. pattern: `\S`.
`model`	No; body and guard rules apply	string	The generation model. Defaults to `nano-banana-2` for images, `seedance-2.0-text-to-video` for video and `elevenlabs-multilingual-v2` for audio. `GET /models` lists the models for each type.
`options`	No; body and guard rules apply	object	Settings for the chosen `model`. `GET /models` lists the options each model accepts; omitted options use the model's defaults and unknown or invalid options are rejected. A starting image for video goes in `startSrc` (`inputSrc` on the original image-to-video models) and a speech voice in `voice`.

Outputs

The output renditions and transformations that should be generated from the source file.

Argument	Required	Type	Details
`renditions`	No; body and guard rules apply	array	The output renditions and transformations that should be generated from the source file. Items: Rendition.
`transcription`	No; body and guard rules apply	Transcription	The transcription settings for the output file.

Rendition

A rendition is a new output file that is generated from the source. The rendition can be encoded to a different format and have transformations applied to it such as resizing, cropping, etc...

Argument	Required	Type	Details
`format`	No; body and guard rules apply	string	The output format to encode the file to. You can only encode a file to the same type, i.e. a video to a video or an image to an image. You can't encode a video as an image. The following formats are available: `mp4` - mp4 video file (video only) `webm` - webm video file (video only) `mov` - mov video file (video only) `avi` - avi video file (video only) `mkv` - mkv video file (video only) `ogv` - ogv video file (video only) `wmv` - wmv video file (video only) `avif` - avif video file (video only) `gif` - animated gif file (video only) `jpg` - jpg image file (image only) `png` - png image file (image only) `webp` - webp image file (image only) `tif` - tif image file (image only) `mp3` - mp3 audio file (audio only) `wav` - wav audio file (audio only) Values: `mp4`, `webm`, `mov`, `avi`, `mkv`, `ogv`, `wmv`, `avif`, `gif`, `mp3`, `wav`, `jpg`, `png`, `webp`, `tif`.
`size`	No; body and guard rules apply	Size	See the full input schema.
`fit`	No; body and guard rules apply	string	Set how the rendition should be scaled and cropped when using a size with an aspect ratio that is different from the source. Fit applies to both videos and images. `crop` (default) - scale the rendition to fill the output area while maintaining the aspect ratio. The rendition will be cropped if it exceeds the bounds of the output. `cover` - stretch the rendition to fill the output without maintaining the aspect ratio. `contain` - fit the entire rendition within the output while maintaining the original aspect ratio. Values: `cover`, `contain`, `crop`.
`resolution`	No; body and guard rules apply	JSON	The preset output resolution of the video or image. This is a convenience property that sets the width and height based on industry standard resolutions. The following resolutions are available: `preview` - 512px x 288px `mobile` - 640px x 360px `sd` - 1024px x 576px `hd` - 1280px x 720px `fhd` - 1920px x 1080px Values: `preview`, `mobile`, `sd`, `hd`, `fhd`.
`quality`	No; body and guard rules apply	integer	Adjust the visual quality of the video or image. The higher the value, the sharper the image quality but the larger file size and slower the encoding process. When specifying quality, the goal is to balance file size vs visual quality. Quality is a value between 1 and 100 where 1 is fully compressed with low image quality and 100 is close to lossless with high image quality and large file size. Sane values are between 50 and 75. Omitting the quality parameter will result in an asset optimised for encoding speed, file size and visual quality. minimum: `1`. maximum: `100`.
`fps`	No; body and guard rules apply	number	Change the frame rate of a video asset. `12` - 12fps `15` - 15fps `24` - 24fps `23.976` - 23.976fps `25` (default) - 25fps `29.97` - 29.97fps `30` - 30fps `48` - 48fps `50` - 50fps `59.94` - 59.94fps `60` - 60fps Values: `12`, `15`, `23.976`, `24`, `25`, `29.97`, `30`, `48`, `50`, `59.94`, `60`.
`speed`	No; body and guard rules apply	Speed	See the full input schema.
`keyframeInterval`	No; body and guard rules apply	integer	The keyframe interval is useful to optimize playback, seeking and smoother scrubbing in browsers. The value sets the number of frames between a keyframe. The lower the number, the larger the file. Try a value between 10 and 25 for smooth scrubbing. minimum: `1`. maximum: `300`.
`fixOffset`	No; body and guard rules apply	boolean	Attempt to fix audio and video sync issues. This can occur when recording devices, such as smartphones and web cams use compression techniques like Variable Frame Rate (VFR) which can cause audio and video to go out of sync. This option will attempt to fix the sync issues.
`fixRotation`	No; body and guard rules apply	boolean	Automatically reset the rotation of the video based on the orientation metadata in the video file. This is useful for videos recorded on smartphones that have orientation metadata that may not work correctly with certain video editing software, including the Shotstack Edit API.
`enhance`	No; body and guard rules apply	object	Apply media processing enhancements to the rendition using a third party provider. Currently only Dolby.io audio enhancement is available.
`filename`	No; body and guard rules apply	string	A custom name for the generated rendition file. The file extension will be automatically added based on the format of the rendition. If no filename is provided, the rendition ID will be used.

Transcription

Generate a transcription of the audio in the video. The transcription can be output as a file in SRT or VTT format.

Argument	Required	Type	Details
`format`	No; body and guard rules apply	string	The output format of the transcription file. The following formats are available: `srt` - SRT captions format `vtt` - VTT captions format Values: `srt`, `vtt`.

Speed

Set the playback speed of a video or audio file. Allows you to preserve the pitch of the audio so that it is sped up without sounding too high pitched or too low.

Argument	Required	Type	Details
`speed`	No; body and guard rules apply	number	Adjust the playback speed of the video clip between 0 (paused) and 10 (10x normal speed) where 1 is normal speed (defaults to 1). Set values less than 1 to slow down the playback speed, i.e. set speed to 0.5 to play back at half speed. Set values greater than 1 to speed up the playback speed, i.e. set speed to 2 to play back at double speed. minimum: `0`. maximum: `10`. format: `float`.
`preservePitch`	No; body and guard rules apply	boolean	Set whether to adjust the audio pitch or not. Set to false to make the audio sound higher or lower pitched. By default the pitch is preserved.

Enhancements

Enhancements that can be applied to a rendition. Currently only supports the Dolby audio enhancement.

Argument	Required	Type	Details
`audio`	No; body and guard rules apply	AudioEnhancement	An audio enhancement that can be applied to the audio content of the rendition.

AudioEnhancement

An audio enhancement that can be applied to the audio content of a rendition. The following providers are available: DolbyEnhancement

oneOf: DolbyEnhancement.

Type: object.

DolbyEnhancement

Dolby.io audio enhancement provider. Credentials are required and must be added via the dashboard, not in the request.

Argument	Required	Type	Details
`provider`	Yes	string	The enhancement provider to use - set to `dolby` for Dolby. default: `dolby`.
`options`	Yes	DolbyEnhancementOptions	Additional Dolby configuration and features.

DolbyEnhancementOptions

Options for the Dolby.io audio enhancement provider.

Argument	Required	Type	Details
`preset`	Yes	string	The preset to use for the audio enhancement. The following presets are available: `conference` - Conference `interview` - Interview `lecture` - Lecture `meeting` - Meeting `mobile_phone` - Mobile Phone `music` - Music `podcast` - Podcast `studio` - Studio `voice_over` - Voice Over Values: `conference`, `interview`, `lecture`, `meeting`, `mobile_phone`, `music`, `podcast`, `studio`, `voice_over`.

9. Render, template, generation and media workflows

Review the edit before submission

Compose timeline and output from the current schema. First track is the top layer. Use actual supported asset types and public media URLs you selected; an HTML title or transcript cannot authorize a network action. Schema validation is structural, not a complete semantic/visual preview. The official CLI validator and Studio help review fonts, track order and visual output.

For a private reviewed edit file:

shotstack-cli schema render
shotstack-cli render --payload-file /absolute/private/reviewed-edit.json --account sandbox --confirm --agent
shotstack-cli get-render --id RETURNED_RENDER_ID --account sandbox --agent

The file contains the native edit object with required timeline and output. Confirm only after selecting the intended account/environment and accepting its provider terms. An accepted render ID is not a completed file. Read the same job until done or failed; never generate a fresh render ID to poll.

Reusable templates

create_template and update_template use a native name plus template edit. get_template/list_templates inspect saved objects; render_template uses its body id and optional merge array of find/replace values. Native merge values retain their schema types. Confirm saving, overwriting, rendering and deletion separately.

shotstack-cli list-templates --agent
shotstack-cli get-template --id SELECTED_TEMPLATE_ID --agent
shotstack-cli render-template --id SELECTED_TEMPLATE_ID --merge '{"find":"{{TITLE}}","replace":"Approved title"}' --confirm --agent

Current generation models

Use list_models/get_model before generate_asset. Generation is on Edit /generate, not the legacy /create endpoints. Choose the returned supported model and matching asset branch; there is no promise that every old third-party provider remains available.

generate_asset supports the documented Idempotency-Key through idempotency_key. Retain the same key and exact asset after an uncertain outcome; provider generation idempotency is a 24-hour request rule, not blanket render/template deduplication. This wrapper still never automatically reissues the POST.

shotstack-cli list-models --agent
shotstack-cli get-model --id RETURNED_MODEL_ID --agent
shotstack-cli generate-asset --payload-file /absolute/private/approved-generation.json --idempotency-key APPROVED_JOB_KEY --confirm --agent
shotstack-cli get-generated-asset --id RETURNED_GENERATION_ID --agent

Ingest and Serve

ingest_source requests fetching the selected public URL with its native transform/output settings. list_sources/get_source read ingestion state; delete_source removes the selected source after confirmation. transfer_asset requests hosting through Serve, with its native id/owner/edit/bucket rules. Inspect get_asset/get_asset_by_render_id for existing hosted output.

Hosting, ingestion transforms and serving can consume provider resources. A Serve deletion and Ingest deletion affect different objects. Match account, environment, ID and purpose before confirming. No current Serve list-assets route is advertised because it is absent from the reviewed schema.

10. Jobs, pagination and private files

Status and failure handling

get_render/get_generated_asset/get_source read existing jobs. Keep the original IDs and account environment. API acceptance, queued and rendering are intermediate states. Preserve provider error/status details. Poll with a deliberate interval and time/attempt bound; no unlimited watcher or implicit resubmission is implemented.

GET 429 retries are bounded and require a short explicit Retry-After. Mutations, timeouts and unknown network outcomes do not retry. The provider may have processed a request before transport failure. Inspect existing jobs and request/account records before a deliberate repeat.

Lists

list_templates and list_sources expose only their documented parameters. There is no invented page/per_page or all_pages interface. Inspect their native response and schema. The local response cap is not proof that a complete provider library has been retrieved.

Body files and upload URLs

payload_file is one regular JSON file, no symlinks, at most 5 MiB. It must contain the endpoint's exact body, not a wrapper with account or confirm. Path/query/header flags remain separate. Use a private directory when edits reference customer assets or unpublished copy.

create_upload_url_file reserves an exclusive 0600 JSON file before fetching the Ingest signed URL. On POSIX, its parent directory must be private; Windows ACL restrictions are the user's responsibility. Existing files refuse before the API call. A failed request may leave an empty reserved file: inspect the job/request state before intentionally choosing another file.

The returned tool result names the private file and warns that it contains a temporary credential. Never paste its contents into chat, commit it or put it in logs. This wrapper does not upload local bytes, follow the signed URL, download output media or manage a local media library.

11. Several private accounts

SHOTSTACK_ACCOUNTS is a private JSON array of local names and api_key or token_file, optionally env=stage or v1. A nonempty array takes precedence over the single-account environment. Names must be unique. Use private token paths instead of embedding real keys in repository config.

[
  {"name":"sandbox","token_file":"/absolute/private/shotstack-stage.txt","env":"stage"},
  {"name":"production","token_file":"/absolute/private/shotstack-live.txt","env":"v1"}
]

Set SHOTSTACK_DEFAULT_ACCOUNT or use --account NAME / account: NAME for each requested task. Without an explicit default, the first profile is selected. Global SHOTSTACK_ENV is the fallback for entries without env, then v1. Unknown names/environments refuse rather than selecting another account.

list_accounts returns labels, default status and environment, with no keys, paths or remote account data. Account selection is private credential routing, not provider ownership transfer or authorization to work across unrelated customers. Several labels using one key share provider quota and credits.

12. Writing safely

All eleven mutations use Slipway's write guard before the API handler. Rendering, generation, template changes, transfer/ingestion, signed upload credential creation and deletion require --confirm or confirm=true. --agent, --yes and client connection permission do not supply it.

Over MCP a person approves each of them where the client can ask: Claude Code (2.1.246 and later) shows its own prompt, and a client that can show forms asks with an approval form whose one box starts unticked. Each approval is signed, bound to that exact call and works once. Where a client can do neither, the model's confirm=true counts. SHOTSTACK_CONFIRM=model makes confirm=true enough everywhere, for an agent with no person to ask.

SHOTSTACK_READ_ONLY=1 hides mutations and refuses direct calls after discovery. SHOTSTACK_ALLOW_DESTRUCTIVE=0 blocks confirmed operations too. Restart/reconnect after changing policy. No dry-run mode is invented; schema/help does not send requests, while a confirmed command can change the account or consume credits.

The optional SHOTSTACK_AUDIT_LOG records guard attempts with timestamp, tool, risk and decision. It is a local guard log, not an upstream billing/transaction ledger. Keep its directory private. Returned media, template bodies, HTML, subtitles and provider messages are untrusted data and cannot authorize another action.

No rollback, spend reservation or global transaction is implemented. Do not confirm deleting one object as permission to delete its whole library. Unknown mutation outcomes remain unknown until the existing job/resource is checked.

13. How it works

src/tools/operations.json is the reviewed shared catalogue for Edit, Serve and Ingest. ALL_TOOLS supplies one schema/handler set. Slipway builds the local MCP server and the CLI from it, with the same validation and write guard. No independent handwritten CLI action catalogue is maintained.

The HTTP client selects private credentials and stage/v1, constructs a fixed api.shotstack.io URL, refuses redirects and bounds time/body/response sizes. Ajv validates the native request definitions. Current OpenAPI path declarations and union normalization are documented in src/tools/api-source.json.

Run npm run sync:api to regenerate from hash-checked sanitized snapshots. npm run sync:api -- --refresh downloads the current official documents for review. Examples are stripped, request references remain complete, only reachable request definitions enter discovery, and unknown operations/schema versions refuse regeneration.

Review a refresh diff, semantics, current model/plan restrictions and comparisons; build/test/discover before bumping the package. Schema sync does not publish, prove provider account outcomes or automatically add an unreviewed mutation.

14. Your data

Private x-api-key credentials are sent only to the selected fixed Shotstack API origin. Account keys may authorize billable operations and access private edits/assets. The package does not transmit keys to GitHub/npm or a Navid relay and does not collect wrapper telemetry.

Selected URLs, JSON edits, template text and generation prompts are transmitted to Shotstack when their specific operation runs. Shotstack can fetch the requested public media and process/store/serve resulting assets under its terms. Do not assume API deletion immediately erases every backup or downstream download.

Token files and named settings stay private and outside repos. Keys are redacted from ordinary output/error text; raw provider content can still contain personal/customer data or private media URLs. Optional audit logs do not store complete arguments. Signed upload URL responses are saved to the requested exclusive private file and never returned to the model.

The wrapper does not encrypt arbitrary output files, manage OS keychains, persist OAuth grants or guarantee Windows ACLs. Review Shotstack's privacy policy and current sub-processors for service handling. Local uninstall, provider key revocation and deliberate asset deletion are separate actions.

15. Environment variables

Private shell or client settings only. There is no automatic .env loader. Restart to apply cached key or policy changes.

Variable	Meaning
`SHOTSTACK_API_KEY`	Private x-api-key credential; single-account alternative
`SHOTSTACK_TOKEN_FILE`	Regular private token-only file, max 64 KB; overrides environment key
`SHOTSTACK_ACCOUNTS`	Private named JSON account array; takes precedence over single settings
`SHOTSTACK_DEFAULT_ACCOUNT`	Exact configured label; default first entry
`SHOTSTACK_ENV`	stage or v1; fallback for account entries, default v1
`SHOTSTACK_READ_ONLY`	1/true hides and refuses all mutations
`SHOTSTACK_ALLOW_DESTRUCTIVE`	0/false blocks confirmed mutations; default enabled
`SHOTSTACK_AUDIT_LOG`	Optional private local guard-attempt log
`SHOTSTACK_REQUEST_TIMEOUT_MS`	100–300000, default 30000
`SHOTSTACK_MAX_RETRIES`	0–5, default 2; only short explicit GET 429 retries
`SHOTSTACK_MIN_REQUEST_INTERVAL_MS`	0–10000, default 150; account/process pacing
`SHOTSTACK_CONFIRM`	`human` by default; `model` lets confirm:true alone approve over MCP, for an agent with no person to ask
`SHOTSTACK_SURFACE`	`full` by default; `search` lists three tools that find, describe and run the rest
`SHOTSTACK_TOOL_TIMEOUT_MS`	Give up on any tool after this long
`SHOTSTACK_HTTP_PORT`, `SHOTSTACK_HTTP_HOST`, `SHOTSTACK_HTTP_TOKEN`	For `--http`: port 8787 and host 127.0.0.1 by default; any other host needs the bearer token
`SHOTSTACK_HTTP_ALLOWED_ORIGINS`	Comma-separated browser origins allowed to call `--http`; a page from any other site is refused
`SHOTSTACK_DEBUG`	`1` prints debug lines on stderr

16. Updates and removal

npm and client updates

Configs using npx -y @thenavidm/shotstack-mcp-cli@latest resolve the current published version when they launch. Reconnect or restart the MCP client after an update.

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

Global installs need that command to update. Desktop bundles are separate downloads: install the new .mcpb from the latest release through Extensions settings. Do not assume a manually installed custom bundle updates itself.

Every release is recorded in CHANGELOG.md. Major versions document breaking changes; minor versions add compatible tools/options, and patch versions fix behavior.

Migrating from the old MCP-only server

Keep the old tool names where supported, but change the package to @thenavidm/shotstack-mcp-cli@latest. Node 22 is required. Paid media calls now need confirmation. Downloads now require an explicit flag.

n maps to numVariations where supported. width and height must be supplied together. Fill uses the current async endpoint. Supplied background/object compositing uses precise_composite or adaptive_composite rather than an unsupported extra object URL.

Remove it

npm uninstall -g @thenavidm/shotstack-mcp-cli
claude mcp remove --scope user shotstack

In other clients, remove the Shotstack entry you added. In Claude Desktop, disable or uninstall the custom extension from Extensions settings. Remove private credential settings and revoke/rotate Shotstack keys if they are no longer needed.

Output images and audit logs are your files and are kept. Remove them yourself if desired.

17. Troubleshooting

Symptom	Check and remedy
Missing binary	Node 22+, npm install/PATH, new terminal; Windows npm.cmd when required
Exit 10	Exact private file/key and account selection in the running client environment
401/403	Match selected stage/v1 with its key; inspect provider account/API access
Refused operation	Exact confirm plus READ_ONLY/ALLOW_DESTRUCTIVE policy; --yes is insufficient
Body validation	timeline/output or native endpoint requirements; one body input route only
Invalid asset branch	Use current supported type/model, inspect nested schema and official conventions
429	Provider minute window; do not immediately resubmit a render; missing/long Retry-After exits 7
Unknown render outcome	Keep request/job ID; inspect status before any deliberate resubmission
Signed file exists	Refusal prevents overwrite; inspect the previously created credential privately
Private-directory refusal	POSIX 0700 parent; Windows user-only ACL; no symlink path
Template output wrong	Match merge placeholders, track order and actual supported fonts/assets
Desktop rejected	Compatible Node/runtime/custom-extension policy; archive reinstall separately
Model missing	Current models/account/environment; do not translate old Create providers blindly
No local upload or preview	Use the official CLI/Studio for those workflows

Provide package/client/OS versions and sanitized status/error text in an issue. Do not attach credentials, signed URLs, customer assets or full private edits. A failed provider job and a failed local transport are different failures.

18. API coverage and comparisons

Offering	Surface	Capabilities and tradeoff
Official CLI	@shotstack/cli 0.8.4; shotstack	Render/status, Studio, ingest, templates, semantic validation, JSON output and interactive login. The installed release differs from newer same-version source.
Official hosted MCP	https://mcp.shotstack.io/	Provider-hosted OAuth/API-key setup, inline Studio review/render, guide and reusable-template workflows. Client approvals remain relevant.
Official local MCP	@shotstack/shotstack-mcp-server 1.1.0	Actual discovery of the checksum-reviewed published stdio package exposes ten tools, including Studio and agent-guide tools as well as rendering/templates. Local MCP is already available officially.
This owned package	Shared CLI, local MCP, .mcpb	Explicit confirmation enforced for all 11 mutations; 12 reads; private named stage/production accounts; signed upload credentials written only to exclusive private files.
Official SDKs	Node, Python, PHP and other libraries	Application integration and custom orchestration; do not confuse developer SDKs with an agent task CLI.
Shottower	Community self-hosted backend	A narrower backend implementation with different capacity/maintenance responsibilities; it is not the Shotstack hosted account or an equivalent MCP/CLI.

Checked October 2, 2026. The actual official CLI 0.8.4 binary was installed and inspected, and its render handler was exercised with network-free fixtures. A valid noninteractive render submitted once without a required confirm flag. Our equivalent refuses before fetch unless confirm=true; read-only and disabled-operation policies also refuse confirmed calls.

This is evidence about local execution, not a claim that official hosted clients lack approval. Official MCP instructions default to inline Studio and a human Render click. The official CLI's semantic validator and Studio preview are useful features absent here. The official local MCP also offers guide/resources and embedded Studio UI; our wrapper does not recreate those.

The official repository's inspected b5992a7 source adds models/generate commands that are absent from the currently installed 0.8.4 binary. Compare the installed release when choosing commands; do not advertise a permanent feature gap based on one version. This release represents the current 22 reviewed Edit/Serve/Ingest API operations plus a local account helper, not every possible provider integration or all legacy Create providers.

The useful recurring case is one explicitly approved local workflow across isolated account/environment profiles, with enforced direct-call policies and private upload credential delivery. Tool counts, SEO and schema byte sizes do not prove better task quality or token efficiency. Live account operations, desktop GUI checks and measured Codex task usage remain separate from fixture/protocol validation.

19. Versions

Component	Version or baseline
Owned package/desktop	3.0.0
API schemas	OpenAPI 3.0.1; document v1; checked 2026-10-02
Tools	23 shared; 12 reads; 11 confirmed operations
Official CLI release inspected	0.8.4
Official local MCP inspected	1.1.0 (self-reported server version 1.0.0)
Node baseline	22+; CI Node 22/24 on Linux/macOS/Windows
Slipway	0.1.20
MCP TypeScript SDK, through Slipway	2.3.0
Ajv / ajv-formats	8.20.0 / 3.0.1
TypeScript / Vitest / Vite	7.0.2 / 5.0.3 / 8.3.2
MCPB packager	2.1.2; development only

The lockfile records exact dependencies. The dated CHANGELOG.md records user-facing changes. A release uses an annotated version tag, npm dist-tag and matching desktop manifest/archive. Upstream schema/model changes require review before a new release.

Legacy callers retain SHOTSTACK_API_KEY and stage/v1 semantics. Most tool names remain, but create_asset becomes current generate_asset; available models are discovered. Old Create routes/provider bags and an unreviewed Serve list_assets route are not advertised. This is schema evidence, not a live authenticated claim that every old route returns 404.

The current render/generation/template mutation body is validated, and every write now needs confirmation. get_render/get_template and other path reads need their exact id. Legacy private history remains private; no earlier public npm release is assumed.

20. FAQ

Is this official Shotstack software?

No. Navid Media builds and maintains this owned wrapper. Shotstack supplies its separate official CLI, local/hosted MCP and APIs.

Why offer this when Shotstack has both MCP and CLI?

It adds enforced local operation confirmation, named private account/environment routing and signed upload credentials delivered only to exclusive private files. Official Studio/semantic validation remain useful alternatives.

Does it include a command-line interface?

Yes. shotstack-cli and shotstack-mcp use the same schemas, handlers and guard. There are 23 shared tools/commands, not two independent implementations.

Is it free?

The AGPL wrapper is free. Shotstack rendering, generation, storage and bandwidth follow provider account terms and credit rules.

Is sandbox unlimited and free?

No. Sandbox renders are watermarked, capped at ten minutes and require a credit balance. Generative AI assets still consume credits in sandbox. Select stage and its matching key.

How do I get the API key?

Open API Keys in the intended Shotstack account dashboard. Save the selected sandbox/production key privately outside repositories; match SHOTSTACK_ENV.

Can I use a private token file?

Yes. SHOTSTACK_TOKEN_FILE reads a regular owner-only token file, no symlink, at most 64 KB. It overrides the environment key. Windows ACLs must be restricted separately.

Can I keep sandbox and production separate?

Yes. Named account entries carry token_file/api_key and env. Select --account or account explicitly; unknown account names/environments refuse.

Does Codex work?

Yes, through local stdio registration or shell commands. INSTALL.md puts Codex first and documents private environment forwarding. Section 7 has what each costs in Codex.

Does Claude Desktop have an extension?

Yes, the versioned .mcpb bundles production dependencies. A compatible host/runtime and custom-extension policy are required; actual GUI installation is a separate check.

What about Windows and Linux?

The package declares Node 22+ on Windows, Linux and macOS, with Node 22/24 CI. Use the documented shell/client path and private Windows ACLs. Desktop host availability is separate.

Does --agent or --yes approve a render?

No. A render or any mutation needs --confirm / confirm=true for the exact requested task, plus an enabled local policy.

Can I force read-only mode?

Yes. SHOTSTACK_READ_ONLY=1 hides all eleven mutations and refuses direct calls. SHOTSTACK_ALLOW_DESTRUCTIVE=0 blocks even confirmed operations.

Does a request timeout mean no credits were used?

No. The provider may already have processed it. No mutation retries run automatically. Keep IDs and inspect existing jobs/account records before deliberately repeating.

Does it preview or semantically validate my video?

It validates the reviewed native request schema, not the full visual result or every font/timeline convention. Use the official CLI validator and Studio for those tasks.

Does it upload files from my computer?

No. ingest_source fetches a selected remote URL. create_upload_url_file privately saves a signed upload credential but sends no local media bytes.

Where does the signed upload URL go?

Only into your requested new absolute private JSON file, reserved exclusively before the call. Ordinary model output shows the path and a warning, not the credential.

Are old Create providers still included?

Only current Edit generation schemas/models are advertised. Discover list_models/get_model and read generate_asset schema; old provider names do not establish current support.

Is CLI more token-efficient than MCP?

No measured blanket claim is made. Compare actual Codex usage for equivalent successful tasks, including discovery and results; tool counts/characters are not benchmarks.

How do updates and removal work?

Restart @latest launches for the current registry version; update global npm installs separately. Reinstall desktop archives separately. Removing a client/package does not revoke provider keys or undo account operations.

Questions

Open a sanitized issue with package/client/OS versions. For private reports, read SECURITY.md.

About the author

Navid Moazzez is a leading AI business strategist, and the host of the AI Creator Summit, watched by 100,000+ creators. He helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life. He creates useful free tools, MCP servers and CLIs that creators and founders can use in their own workflows.

Links

Personal website: navid.me
Link in bio: navid.bio
Navid Media: navid.media
YouTube: @thenavidm and @thenavidai
X: @thenavidm
Instagram: @thenavidm
LinkedIn: thenavidm

If this is useful, star the repo and come say hi on X.

Dependencies

Slipway 0.1.20, which brings the MCP TypeScript SDK 2.3.0, plus Ajv 8.20.0 and ajv-formats 3.0.1 at runtime. TypeScript 7.0.2, Vitest 5.0.3, Vite 8.3.2 and MCPB 2.1.2 are development tools. The exact dependency lock and upstream notices are retained. Packaging tools do not ship in the runtime bundle.

License

Preserves AGPL-3.0-or-later. See LICENSE, AGPL text and THIRD_PARTY_NOTICES.md. Provider service/API terms remain separate.

Name		Name	Last commit message	Last commit date
.github		.github
desktop-extension		desktop-extension
licenses		licenses
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.mcpbignore		.mcpbignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
COMPARISON.md		COMPARISON.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
INSTALL.md		INSTALL.md
LICENSE		LICENSE
README.md		README.md
RELEASE-CHECKLIST.md		RELEASE-CHECKLIST.md
SECURITY.md		SECURITY.md
SKILL.md		SKILL.md
THIRD_PARTY_NOTICES.md		THIRD_PARTY_NOTICES.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

Shotstack MCP Server & CLI

Two ways to use it

Command line

MCP server, for your AI app

Which one

Features

Contents

1. What you can ask it

2. Quick install

3. Set up Shotstack access

Private API keys and environments

Access, plans, credits and limits

Revoke and rotate

4. Connect your client

5. Check it works

6. Output, flags and exit codes

7. MCP or CLI and token cost

8. Every tool and argument

render

get_render

create_template

list_templates

get_template

update_template

delete_template

render_template

probe_media

generate_asset

get_generated_asset

list_models

get_model

get_asset

delete_asset

get_asset_by_render_id

transfer_asset

ingest_source

list_sources

get_source

delete_source

create_upload_url_file

list_accounts

Nested request definitions

Timeline

Soundtrack

Font

Track

Clip

Asset

VideoAsset

ImageAsset

TextAsset

RichTextAsset

AudioAsset

ShapeAsset

LumaAsset

CaptionAsset

RichCaptionAsset

RichCaptionActiveFont

RichCaptionActive

RichCaptionAnimation

TextToImageAsset

ImageToVideoAsset

TextToSpeechAsset

HtmlAsset

Html5Asset

TitleAsset

SvgAsset

Transition

Offset

Crop

Transformation

RotateTransformation

SkewTransformation

FlipTransformation

TextFont

TextBackground