Skip to main content

Hello World (Curl)

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. Curl is included by default on most modern operating systems including Windows 10, Linux and OS X.

To check if Curl is installed on your operating system open your terminal on Linux/OS X or the Command Prompt in Windows then type:

curl --version

You should see an output like:

curl 7.64.0 (x86_64-pc-linux-gnu) libcurl/7.64.0 OpenSSL/1.1.1b zlib/1.2.11 libidn2/2.0.5 libpsl/0.20.2 (+libidn2/2.0.5) libssh/0.8.6/openssl/zlib nghttp2/1.36.0 librtmp/2.3
Release-Date: 2019-02-06
Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp
Features: AsynchDNS IDN IPv6 Largefile GSS-API Kerberos SPNEGO NTLM NTLM_WB SSL libz TLS-SRP HTTP2 UnixSockets HTTPS-proxy PSL

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":"title",
"text":"Hello World",
"style":"minimal"
},
"start":0,
"length":5,
"transition":{
"in":"fade",
"out":"fade"
}
}
]
}
]
},
"output":{"format":"mp4", "resolution":"sd"
}
}

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 (using the staging sandbox URL). 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/stage/render
info

Replace the x-api-key value with your own sandbox 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"
}
}
info

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/stage/render/d2b46ed6-998a-4d6b-9d91-b8cf0193a655
info

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":"hckwccw3q3",
"plan":"sandbox",
"status":"done",
"url":"https://s3-ap-southeast-2.amazonaws.com/shotstack-api-stage-output/hckwccw3q3/d2b46ed6-998a-4d6b-9d91-b8cf0193a655.mp4",
"data":{
"output":{
...
},
"timeline":{
...
}
},
"created":"2019-04-16T12:02:42.148Z",
"updated":"2019-04-16T12:02:51.867Z"
}
}
Warning

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:

StagingProduction
https://cdn.shotstack.io/au/stage/https://cdn.shotstack.io/au/v1/

The video created in this guide will be available at:

https://cdn.shotstack.io/au/stage/hwxmtow4o5/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:

StagingProduction
https://shotstack-api-stage-output.amazonaws.com/https://shotstack-api-v1-output.amazonaws.com/

Download or transfer the video using the URL returned in the get render status response:

curl -O https://shotstack-api-stage-output.amazonaws.com/hwxmtow4o5/d2b46ed6-998a-4d6b-9d91-b8cf0193a655.mp4
Danger

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:

  1. Prepare the edit data
  2. POST the edit data to the API
  3. Poll the API and wait for the render to complete
  4. Serve the video from the Shotstack CDN
  5. Download or transfer the video to your own storage