Merge fields are dynamic placeholders (e.g., {{ name }}) that allow you to turn a single design into a high-volume automation tool.
By defining these variables in the Studio Editor, you can programmatically swap text, images, and video properties for every video you render.
Step 1: Define Your Merge Fields
Defining variables in the v2 Studio Editor allows you to preview how dynamic data will look on your canvas before you send it to the API:
Click the Merge Fields icon (the
{ }symbol) at the bottom of the right-hand properties panel.Click the (+) button to create a new variable.
Enter a Variable Name (e.g.,
NAME) and click OK.Set a Default Value (e.g.,
Janice). This value is used in the editor preview so you can design your layout accurately.
Step 2: Apply Merge Fields to Text
Once your fields are defined, you can link them to your text assets:
Select a Text asset on the canvas.
In the Edit Text properties box, wrap your variable name in double curly brackets:
{{ NAME }}.The canvas will immediately update to show your Default Value, confirming the link is successful.
Step 3: Enabling Dynamic Sources for Media
Merge fields can also be used to dynamically replace images or video URLs. To enable this:
Select a media asset (Image or Video) in your project.
Open the more options menu (three dots) in the top toolbar.
Toggle on Dynamic Source.
This prepares the asset to have its source URL swapped via the API.
Step 4: Rendering at Scale via API
To generate videos in bulk, you use your Studio project as a Template.
When you send a render request to the Shotstack API, you include the Template ID and a merge array containing the specific merge field data for that video.
Example API Request:
Bash
curl -X POST \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '
{
"id": "ca84c7c5-5fe4-66d3-839e-ee0f1d4c2641",
"merge": [
{
"find": "name",
"replace": "Alex"
},
{
"find": "URL",
"replace": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/footage/city-timelapse.mp4"
},
{
"find": "DURATION",
"replace": 10
}
]
}'
By using this API-driven approach, you can connect your Shotstack templates to a database, CRM, or a simple script to automate the production of hundreds of personalized videos at once.