Requests, results and retries
Requests run in the background. Follow one until it finishes, then download what it made.
Every processing endpoint starts a request that runs in the background. The response is the request itself, with status queued.
Statuses
| Status | Meaning |
|---|---|
queued |
Accepted, waiting for a worker. |
processing |
Running. Video requests report progress (0–100). |
succeeded |
Finished. result holds the data and the files. |
failed |
Finished without a result. error says why. Not charged. |
aborted |
Stopped with POST /v1/requests/{id}/abort. Not charged. |
Poll GET /v1/requests/{id} every few seconds (images take about a second; videos take longer), or pass webhook_url to be told (see Webhooks).
Results
result.files[].url is a download link that works until the file is deleted, 7 days after the request finishes (url_expires_at, the same moment as result.deleted_at). Anyone with the link can download the file, so share it only where the file may go. Opening it redirects to the file itself. result.data describes the output: dimensions and format for images, duration and codec for videos, pages and size for PDFs.
Read endpoints (images/read, videos/read, documents/read) return result.data only.
Sources
source must be a public http or https URL on the default port. The API refuses private, loopback and cloud-metadata addresses, follows at most 3 redirects, and only processes these formats:
- Images: JPEG, PNG, GIF, WebP, TIFF, BMP, HEIC, AVIF
- Videos: MP4, MOV, WebM, MKV, AVI, FLV, MPEG, MPEG-TS
- Documents: PDF
Idempotency
Send an Idempotency-Key header (any unique string up to 255 characters) to make a retry safe. The same key with the same body returns the first request (200, header Idempotent-Replayed: true) instead of starting and charging a second one. The same key with a different body is a 409.
Your own references
customer (up to 64 characters) and metadata (up to 20 keys of text) are stored on the request, returned with it and sent in its webhooks. Use them to tie requests to your own users and orders; GET /v1/usage?group_by=customer totals them.