Tools Reference
| Tool | Purpose |
|---|---|
render_video | Create a video from a JSON specification |
get_render_status | Check render progress and get output URL |
create_template | Save a reusable video template |
list_templates | List all saved templates |
get_template | Retrieve a template's structure |
render_template | Render a video from a template |
delete_template | Remove a template |
render_video
Create a video, image, or audio file from a JSON specification.
| Parameter | Type | Required | Description |
|---|---|---|---|
timeline | Timeline | Yes | Timeline with tracks and clips |
output | Output | Yes | Format and resolution settings |
merge | MergeField[] | No | Merge field replacements |
callback | string | No | Webhook URL for completion |
Prompt: "Create a 10-second video with 'Hello World' centered on screen"
Response: { "id": "d2b46ed6-...", "message": "Render Successfully Queued" }
get_render_status
Check render progress and get the output URL when complete.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Render ID from render_video or render_template |
includeData | boolean | No | Include original edit data in response (useful for debugging) |
Prompt: "Check the status of render d2b46ed6-..."
Response: { "id": "...", "status": "done", "url": "https://cdn.shotstack.io/.../video.mp4" }
Status values: queued → fetching → rendering → saving → done (or failed)
create_template
Save a reusable video template with merge field placeholders.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Template name |
template | Edit | Yes | Edit specification with {{PLACEHOLDER}} syntax |
Prompt: "Create a template called 'greeting' with a NAME placeholder"
Response: { "id": "ca84c7c5-...", "message": "Template Successfully Created" }
list_templates
Retrieve all saved templates.
Prompt: "List all my templates"
Response: { "templates": [{ "id": "...", "name": "greeting", "created": "..." }] }
get_template
Retrieve a template's full structure.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Template ID |
Prompt: "Show me the greeting template"
render_template
Render a video from a saved template with merge field replacements.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Template ID |
merge | MergeField[] | No | [{ "find": "NAME", "replace": "Alice" }] |
Prompt: "Render the greeting template with NAME set to 'Alice'"
delete_template
Permanently delete a template.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Template ID |
Prompt: "Delete the greeting template"
Quick Reference
Track layering: Track 0 = top layer (foreground). Last track = bottom layer (background).
Asset types: video, image, audio, rich-text, svg, rich-caption, text-to-speech, text-to-image, image-to-video
Output formats: mp4, gif, mp3, jpg, png
Resolutions: preview, mobile, sd, hd, 1080, 4k
Aspect ratios: 16:9, 9:16, 1:1, 4:5, 4:3
Common Errors
| Error | Solution |
|---|---|
| Font not found | Don't specify font.family, or use Shotstack CDN fonts |
| Invalid URL | Ensure URL is public HTTPS |
| Render failed | Simplify the request and retry |
| Template not found | Use list_templates to get valid IDs |