Tasks and downloads
Understand waiting, resuming and expiring video links.
Create once, query repeatedly
Save the complete returned id and query GET /v1/videos/{id} with your API key.
| Status | Meaning | Action |
|---|---|---|
| queued | Waiting | Keep polling |
| in_progress | Processing or preparing the file | Keep polling |
| completed | Download ready | Save metadata.url immediately |
| failed | Failed | Inspect error.code, error.message and usage |
| expired | Cached file expired | Stop; check your local copy |
Unknown states are not success. Progress is not an ETA and may remain unchanged or decrease. Poll approximately every 15 seconds.
Download URL
Use completed.metadata.url verbatim, preserving expires and sig. Signed downloads do not need an additional API key.
The site caches the generated video. Retention is approximately 10 minutes from readiness, not from your first query. A signed URL lasts up to 5 minutes, bounded by the cached file's lifetime. expires_at describes the cached file expiry; the URL's expires parameter is the link expiry and may be earlier. Refreshing does not extend retention.
Expired links
If the file still exists, query the original task for a new signed URL. If status is expired or download returns 410, check your saved copy before deciding whether to pay for another generation.
Interrupted connections
Retry transient GET failures with backoff. Do not automatically retry a timed-out POST: the task may have been accepted. Keep its timestamp and request ID and check console records or contact support.
No idempotent creation or cancellation interface is promised to this client. Stopping local polling does not cancel or refund a task. Persist its ID and resume it after a local waiting limit.
The Python client supports resuming an existing task.