Hello World
This Hello World guide should provide you with a basic understanding of how quick and easy it is to create a simple video using styled text, a soundtrack and a simple fade transition.
Before you begin ensure you have registered and received your API keys.
Requirements
This tutorial uses Curl to create your first 'Hello World' video. Curl is a cross platform command line utility that can be used to POST data to an API.
Create the Hello World edit
We'll use a text file to define the JSON data so that it is easy to edit and format. Open your preferred text editor and copy and paste the following JSON, save the file as hello.json:
{
"timeline":{
"soundtrack":{
"src":"https://s3-ap-southeast-2.amazonaws.com/shotstack-assets/music/moment.mp3",
"effect":"fadeOut"
},
"background":"#000000",
"tracks":[
{
"clips":[
{
"asset": {
"type": "text",
"text": "HELLO WORLD",
"font": {
"size": 32,
"align": "center",
"font": "Montserrat ExtraBold",
"color": "#FFFFFF"
}
},
"start":0,
"length":5,
"transition":{
"in":"fade",
"out":"fade"
}
}
]
}
]
},
"output":{
"format":"mp4",
"size": {
"width": 1024,
"height": 576
}
}
}
POST the edit to the Shotstack API
You can now go ahead and POST the hello.json edit data to the API for rendering, to do this we'll use the render endpoint. From the same directory as the hello.json file, run the following Curl command:
curl -X POST \
-H "Content-Type: application/json" \
-H "x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf" \
-d @hello.json \
https://api.shotstack.io/edit/stage/render
Replace the x-api-key value with your own sandbox (stage) API key.
You should receive a 201 response code and payload similar to:
{
"success":true,
"message":"Created",
"response":{
"message":"Render Successfully Queued",
"id":"d2b46ed6-998a-4d6b-9d91-b8cf0193a655"
}
}
Take a note of the id, it will be different from the example above, you will need this in the next step. You should keep track of id in your own database as there is currently no way to retrieve a list of render id's.
Poll the API to check the render status
Your video is now either waiting in a queue to be rendered or is being processed. To check the status and know when rendering is complete and the video file is ready we need to poll the API.
Using the id noted in the previous step and your own key, call the staging API using the following command:
curl -X GET \
-H "Content-Type: application/json" \
-H "x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf" \
https://api.shotstack.io/edit/stage/render/d2b46ed6-998a-4d6b-9d91-b8cf0193a655
Replace the UUID at the end of the render URL with the id output in the previous step.
In less than one minute you should receive a 200 response code and payload similar to the output below. The status parameter tells you what stage the render is at, done means the video is ready for download. Other status are queued, fetching, rendering, saving and failed.
{
"success": true,
"message": "OK",
"response": {
"id": "d2b46ed6-998a-4d6b-9d91-b8cf0193a655",
"owner": "5ca6hu7s9k",
"plan": "free",
"status": "done",
"url": "https://shotstack-api-stage-output.s3-ap-southeast-2.amazonaws.com/5ca6hu7s9k/d2b46ed6-998a-4d6b-9d91-b8cf0193a655.mp4",
"data": {
"output": {
...
},
"timeline": {
...
}
},
"created": "2024-01-16T12:02:42.148Z",
"updated": "2024-01-16T12:02:51.867Z"
}
}
If the status is failed then there has been an error and the render will not continue. Attempt to resolve the issue based on the error message then try again. If the problem persists check the community forum or contact us for support.
Hosting and serving the rendered video
When the status returned from polling equals done, then the video is ready for hosting or downloading.
By default all videos are automatically sent to our video hosting and CDN service. After a few seconds the video should be available at the following locations:
| Staging | Production |
|---|---|
| https://cdn.shotstack.io/au/stage/ | https://cdn.shotstack.io/au/v1/ |
The video created in this guide would be available at:
https://cdn.shotstack.io/au/stage/5ca6hu7s9k/d2b46ed6-998a-4d6b-9d91-b8cf0193a655.mp4
The Serve API provides more information on the status and availability of hosted files.
Transferring the video to your own hosting service
If you use your own hosting solution, you can opt-out from the Shotstack hosting service and transfer the file to the location of your choice.
Videos are stored temporarily for a 24 hour period at the following locations:
| Staging | Production |
|---|---|
| https://shotstack-api-stage-output.s3-ap-southeast-2.amazonaws.com/ | https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/ |
Download or transfer the video using the URL returned in the get render status response:
curl -O https://shotstack-api-stage-output.s3-ap-southeast-2.amazonaws.com/5ca6hu7s9k/d2b46ed6-998a-4d6b-9d91-b8cf0193a655.mp4
Do not serve the temporary URLs from your application as the file will be deleted after 24 hours. Check the Hosting and Serving Assets guide for the correct way to serve assets generated by the video editing API.
Conclusion
You will now have a basic understanding of the key steps needed to create a simple edit:
- Prepare the edit data
- POST the edit data to the API
- Poll the API and wait for the render to complete
- Serve the video from the Shotstack CDN
- Download or transfer the video to your own storage