The Life of an API Render
From request to download: statuses, progress, download links, how long videos are kept, and reproducing a video with its seed.
From request to MP4
- 1You send a create-video request. We check it, charge the credits, and answer straight away with the video id, status "queued", the seed and your remaining balance.
- 2The video waits its turn in the queue.
- 3Our cloud renderer picks it up. The status becomes "rendering" and progress climbs from 0 to 1.
- 4When the file is ready the status becomes "done" and a download link appears. If it fails, the status becomes "failed" with an error message and the credits return to your balance.
- 5You find out by checking the video (every 10 to 15 seconds is plenty) or, better, by receiving a webhook.
Statuses
The API and the Recent API Renders table on /developer use slightly different words for the same states.
| API status | Shown on /developer | What it means |
|---|---|---|
| queued | Queued | Accepted and paid for, waiting for a renderer. Can still be cancelled. |
| rendering | Rendering (with a percentage) | Being rendered or uploaded. Cannot be cancelled. |
| done | Done | Finished. A download link is available. |
| failed | Failed | Did not finish. Hover the badge on /developer to see the reason. Credits are back in your balance. |
Download links and how long videos are kept
A download link is a direct MP4 link that works for 15 minutes. It is short-lived on purpose, so a leaked link stops working quickly. If yours has expired, check the video again for a fresh one, or use the video's download address from the API reference, which always sends you to a fresh link.
Finished videos are kept for 7 days, then deleted. Download and store anything you want to keep. The Download button on /developer uses the same links and refreshes them while the page is open.
Reproducing a video with its seed
Every response includes a seed. Send that seed back with the same settings to get the same video again. You can also choose your own seed (1 to 64 letters, numbers, dashes or underscores) so you know it in advance.
Tip
- Render a few short, cheap clips, keep the seed of the one you like, then render the full-length version with that seed.
Matching videos to your own records
Add a metadata object to a request, for example your order number or user id. It comes back every time you read that video and in every webhook about it. Up to 20 keys; values can be text (up to 500 characters), numbers or true/false.
Listing your videos
Listing videos returns the ones made with the key you call it with, newest first, 20 at a time (you can ask for up to 100). When the answer says has_more, send back its next_starting_after value as starting_after to get the next page. You can also list only videos in one state (queued, rendering, done or failed) or made in a time range.
Tip
- Walking the pages this way never skips or repeats a video, even when several were created in the same second.
Troubleshooting
| What you see | What to do |
|---|---|
| Status stays "queued" for a long time | The queue is busy. Keep waiting; if it is still queued after several minutes, contact support with the video id. |
| Status is "failed" | Read the error. Your credits are already back. Try again; if the same settings fail repeatedly, contact support with the video id. |
| Download link returns an error | The link is older than 15 minutes. Check the video again for a new link. |
| not_found for a video you made | It may be older than 7 days and deleted, or it was made with a different account. |
| not_ready when downloading | The video is not done yet. Check its status first. |
More from BallEngine
Guides, plans and answers for making your videos.