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](./request-api-keys.md). ### 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**: ```json { "timeline": { "soundtrack": { "src": "https://s3-ap-southeast-2.amazonaws.com/shotstack-assets/music/moment.mp3", "effect": "fadeOut" }, "tracks": [ { "clips": [ { "asset": { "type": "text", "text": "HELLO WORLD", "font": { "family": "Montserrat ExtraBold", "color": "#ffffff", "size": 32 }, "alignment": { "horizontal": "left" } }, "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: ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf" \ -d @hello.json \ https://api.shotstack.io/edit/stage/render ``` :::info Replace the **x-api-key** value with your own sandbox (stage) API key. ::: You should receive a 201 response code and payload similar to: ```json { "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: ```bash 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 ``` :::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. ```json { "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" } } ``` :::caution 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 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](/docs/guide/serving-assets/hosting) or downloading. By default all videos are automatically sent to our [video hosting and CDN service](/docs/guide/serving-assets/hosting). 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](/docs/guide/serving-assets/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](/docs/guide/serving-assets/self-host) 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: ```bash curl -O https://shotstack-api-stage-output.s3-ap-southeast-2.amazonaws.com/5ca6hu7s9k/d2b46ed6-998a-4d6b-9d91-b8cf0193a655.mp4 ``` :::warning 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](/docs/guide/serving-assets/hosting) 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