Asynchronous video rendering APIs allow developers to automate the creation of video content without manual editing. This article explains how to use the Shotstack API to programmatically generate a video, from defining the edit structure to retrieving the final hosted asset. We will cover the core concepts of the Edit JSON format, the asynchronous job lifecycle, and how to handle the two types of output URLs.
Context and practical value
The source material provides a comprehensive tutorial on using the Shotstack API to render videos. It explains the asynchronous workflow, details the structure of the Edit JSON object, and provides code examples in cURL, Node.js, and Python for submitting renders, polling status, and retrieving hosted assets.
This article synthesizes the tutorial into a structured guide that emphasizes the architectural implications of asynchronous video rendering. It specifically highlights the critical distinction between temporary and permanent output URLs and provides a clear, step-by-step approach to implementing automation in production environments.
Key takeaways
- Video rendering is asynchronous: the API queues a job and returns a render ID for tracking.
- An Edit JSON object describes the video's timeline, assets, and output settings.
- The temporary URL returned by the render status endpoint expires after 24 hours.
- Use the Serve API to retrieve a permanent, CDN-hosted copy of the rendered video.
- For production applications, use webhooks instead of polling to receive render completion notifications.
Understanding the Asynchronous Render Lifecycle
Unlike synchronous operations, video rendering takes time. The Shotstack API does not keep the initial request open until the MP4 is ready. Instead, it queues the job and immediately returns a unique render ID. You use this ID to poll the API for the job's status, which can move through states like queued, rendering, and done. This pattern is essential for building scalable applications that handle long-running background tasks.
Defining an Edit with JSON
The core of the Shotstack API is the Edit JSON object. This structure describes what the video should contain, how it should be laid out, and how it should be rendered. An Edit consists of two main parts: a timeline and an output configuration. The timeline defines the content and timing, using tracks and clips to layer assets. The output configuration specifies the final file format, resolution, and quality. For example, a simple edit might define a background color and a single clip displaying text.
Handling Output URLs: Temporary vs. Hosted
When a render is complete, the API returns a temporary URL. This URL is valid for 24 hours and is intended for immediate inspection or download. However, it is not suitable for serving to end-users. For a permanent copy, you must use the Serve API. This API queries Shotstack's CDN and returns a stable URL for the hosted asset. This distinction is critical for maintaining a reliable video delivery system.
Implementing Automation in Node.js and Python
While manual polling is useful for testing, production applications require automation. This involves writing scripts that submit the Edit JSON, store the render ID, and poll the status endpoint at regular intervals. The scripts should include error handling for failed renders and a timeout to prevent infinite loops. Both Node.js and Python examples are provided in the source material, demonstrating how to implement this logic using native fetch and the requests library, respectively.
Practical next steps
- Create a Shotstack account and generate a sandbox API key to test without consuming credits.
- Construct a minimal Edit JSON object that defines a timeline and output settings, then submit it to the render endpoint.
- Implement a polling loop in your application to check the status of the render job until it reaches the 'done' state.
- Retrieve the permanent CDN-hosted URL using the Serve API once the render is complete.
- Configure a webhook in your Edit JSON to receive notifications when a render finishes, replacing manual polling in production.
Limits and verification
- The source material does not provide specific metrics on render time or cost for different video resolutions.
- The tutorial focuses on a simple text-based edit; handling complex transitions, custom fonts, or external media assets requires additional configuration.
- The temporary URL expiration policy is a critical implementation detail that must be handled correctly to avoid broken links.
FAQ
What is the difference between the temporary URL and the hosted URL?
The temporary URL is returned immediately after a render completes and is valid for 24 hours. The hosted URL is retrieved via the Serve API and represents a permanent copy stored on Shotstack's CDN, which remains available until you delete it.
How do I handle the asynchronous nature of the rendering process?
You submit the Edit JSON to the render endpoint and receive a render ID. You then poll the render status endpoint using this ID until the status changes to 'done' or 'failed'. For production, it is recommended to use webhooks to receive notifications instead of polling.