Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope media:write
Opens an upload: you tell us the file's name and size, and we tell you how to cut it into chunks and where to send them. Nothing is sent yet. This is step 2 of the workflow.
Parameters
Name
Where
Type
Required
What it is
Idempotency-Key
header
string
no (recommended)
Your own value of 1 to 64 printable characters: a new random one (a UUID) for every new request, and the same one when you send that request again after a lost response. The shell examples keep it in a variable that a second run of the same block does not change (see Idempotency keys). Example: 9b2f0c7e-3d4a-4f61-8a5e-2c1b7d9e0f43.
file_name
body (JSON)
string
yes
The file's name with its extension: .mov, .mp4, .mxf, .mkv, .mpg, .mpeg, .wav or .mp3 (upper or lower case). Up to 1000 characters are accepted; a name longer than 200 characters is shortened (its start and its extension are kept). Example: A001_C003.mov.
size
body (JSON)
integer
yes
The file's size in bytes: 1 to 53,687,091,200 (50 GiB). Example: 35181362.
chunk_size
body (JSON)
integer
no
The size of every chunk except the last, in bytes: 4,194,304 (4 MiB) to 33,554,432 (32 MiB). Default: 8,388,608 (8 MiB).
sha256
body (JSON)
string
no (recommended)
The whole file's SHA-256 as 64 lower-case hexadecimal characters - in the example replace YOUR_FILE_SHA256 with your file's: sha256sum A001_C003.mov (Linux, Git Bash), shasum -a 256 A001_C003.mov (macOS) or (Get-FileHash A001_C003.mov).Hash.ToLower() (PowerShell). We check it after the completion; a file that does not match ends as a failed media with error.codeChecksumMismatch. Leave it out rather than send another file's. Example: a93dcb26...f44f.
purpose
body (JSON)
string
no
job or preview (a short part uploaded only for a preview; deleted 24 hours after the upload was completed unless a job uses it). Default: job.
source
body (JSON)
object
no
Anything you want to keep with the media - for example the clip name, reel name and timecode of your edit - up to 4 KB as JSON. It comes back as source of the media; we do not read it. Example: {"clip_name": "A001_C003"}.
ingest.keep_frame_rate
body (JSON)
boolean
no
true keeps 29.97 fps material with 3:2 pulldown at 29.97 fps (see Uploads and media). Default: false.
picture
body (JSON)
object
no (recommended)
The file's frame size, {"width": 1920, "height": 1080} (whole pixels; 0 and 0 for sound only). A picture larger than limits.picture of GET /health (2048 × 1556, either way round) answers PictureTooLarge at once - before you send anything.
notify_url
body (JSON)
string
no
A public https address of yours (up to 2000 characters) that gets a webhook when the media is analysed. API keys only.
What you get back: 201 Created with an Upload object and a Location header (the upload's address). Keep its id, chunk_size and chunk_count.
Good to know: At most 10 uploads can be open at the same time per user (TooManyUploads). An open upload is kept for 7 days after its last chunk arrived.
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope media:write
Sends one chunk of the file. Chunk 0 is the first chunk_size bytes of the file, chunk 1 the next chunk_size bytes, and so on; the last chunk is the rest. Send them in any order, up to max_parallel at the same time.
Parameters
Name
Where
Type
Required
What it is
upload_id
path
string
yes
The upload's id, as POST /uploads gave it: upl_ and 24 characters. Example: upl_5f0c2a9e41b7d3c8e6a1f094.
index
path
integer
yes
The chunk's number, from 0 to chunk_count - 1.
Content-Type
header
string
yes
application/octet-stream.
Repr-Digest
header
string
no (recommended)
The chunk's SHA-256 in base64 between colons: sha-256=:<base64>: (RFC 9530). A chunk damaged on the way is then refused (ChunkDigestMismatch) and you send it again.
(the body)
body (bytes)
bytes
yes
The chunk's bytes exactly: chunk_size bytes, or for the last chunk size - index × chunk_size bytes. Not base64, not JSON.
What you get back: 200 OK with index (the chunk you sent) and received_count (how many different chunks have arrived so far).
Good to know: Sending a chunk again is harmless: it is written again. A completed upload takes no more chunks (UploadNotOpen). Chunks have no per-minute limit; at most 4 chunks of one upload, 16 of one credential and 32 of one user can be on their way at the same time (TooManyParallelChunks, Retry-After: 1).
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope media:read
Shows an upload and which chunks are still missing. Use it to resume an upload that was interrupted: send the chunks in missing, then complete.
Parameters
Name
Where
Type
Required
What it is
upload_id
path
string
yes
The upload's id, as POST /uploads gave it: upl_ and 24 characters. Example: upl_5f0c2a9e41b7d3c8e6a1f094.
If-None-Match
header
string
no
The last ETag (a 304 when nothing has changed).
What you get back: 200 OK with an Upload object and an ETag header. missing lists at most the first 1,000 missing chunks: when you have sent those, ask again.
Good to know: An upload changes only when its chunks arrive, so it answers no Retry-After: ask when you need its missing list, at most once a second. A completed upload is kept 1 day after its completion (with its media_id); after that this answers NotFound - find the media with GET /media. Its expires_at counts only while it is open.
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope media:write
Tells us that every chunk has arrived. The file becomes a media and its analysis starts. Then wait for the media to be ready (GET /media/{media_id}).
Parameters
Name
Where
Type
Required
What it is
upload_id
path
string
yes
The upload's id, as POST /uploads gave it: upl_ and 24 characters. Example: upl_5f0c2a9e41b7d3c8e6a1f094.
What you get back: 202 Accepted with status (completed), upload_id, media_id (keep it: it is the id of your media from now on) and media (a Media object), and a Location header with the media's address. Completing again gives the same media - nothing is made twice. The example is an upload opened with a sha256: its media starts analyzing, stageinformation (the SHA-256 is checked first); without sha256 it starts queued, stagenull.
Good to know: The body is empty (--data '' sends an empty POST). Missing chunks answer UploadIncomplete with details.missing (at most the first 1,000): send those and complete again. When you already have a media with the same name, the new one is named with a number, for example A001_C003 (2).mov. We read the file's frame size before it becomes a media: a picture larger than limits.picture answers PictureTooLarge, and the upload and its file are deleted (nothing is charged).
Credential: API key and secret (HTTP Basic) or an access token made from them - not an app sign-in · scope media:write
Makes a media from a file that is on the internet already (your own storage, Dropbox, Google Drive) instead of uploading it from your computer. We download it ourselves. API keys only - apps upload.
Parameters
Name
Where
Type
Required
What it is
Idempotency-Key
header
string
no (recommended)
Your own value of 1 to 64 printable characters: a new random one (a UUID) for every new request, and the same one when you send that request again after a lost response. The shell examples keep it in a variable that a second run of the same block does not change (see Idempotency keys). Example: 9b2f0c7e-3d4a-4f61-8a5e-2c1b7d9e0f43.
url
body (JSON)
string
yes
A public https:// address of the file, up to 4000 characters. Private and local addresses (for example 192.168.x.x or localhost) are refused, also when a redirect leads there; at most 5 redirects are followed.
file_name
body (JSON)
string
no
The media's name, with one of the extensions of POST /uploads. Default: the name the address's server gives (its Content-Disposition header), else the last part of the address.
username
body (JSON)
string
no
A user name for the address (HTTP authentication of your storage). It is sent only to the host you named.
password
body (JSON)
string
no
The password that goes with username.
picture
body (JSON)
object
no
The file's frame size, as for POST /uploads: a picture over limits.picture answers PictureTooLarge and nothing is downloaded. Without it, the analysis checks the size: the media ends failed with error.codePictureTooLarge.
notify_url
body (JSON)
string
no
A public https address of yours for a webhook when the media is analysed.
What you get back: 202 Accepted with a Media object (statusqueued, stagedownloading, percent of the download) and a Location header. When the download has finished, the media is analysed like an upload: poll GET /media/{media_id} until ready.
Good to know: An app sign-in gets InsufficientScope with details.credentialapi_key.
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope media:read
Lists your media, newest first, a page at a time. Use it to find a media again (for example after your program restarted).
Parameters
Name
Where
Type
Required
What it is
status
query
string
no
Only media in this state: queued, analyzing, ready, failed or all. Default: all.
purpose
query
string
no
job, preview or all. Default: job (preview uploads are left out).
limit
query
integer
no
How many entries one page holds: 1 to 200. Default: 50.
cursor
query
string
no
The next_cursor of the page before, exactly as it came. Leave it out for the first page. See Lists and pages.
What you get back: 200 OK with data (a list of Media objects - without jobs and previews; ask a single media for those) and next_cursor (a string to get the next page, or null on the last page).
Good to know: One request looks at most at 500 media. With a status or purpose filter a page can therefore hold fewer than limit entries - even none - and still have a next_cursor: follow next_cursor until it is null.
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope media:read
Shows one media: how far its analysis is, and - once it is ready - what the analysis found: length, frame rate, frame size, borders, black-and-white or colour, sound, timecode, scenes and warnings. Poll it after complete until status is ready or failed.
Parameters
Name
Where
Type
Required
What it is
media_id
path
string
yes
The media's id, as POST /uploads/{upload_id}/complete or GET /media gave it. Example: med_4821.
If-None-Match
header
string
no
The last ETag (a 304 when nothing has changed).
What you get back: 200 OK with a Media object, an ETag and a Retry-After header: 1 while the media is queued or analyzing (poll again after 1 second), 60 otherwise.
Good to know: A media whose analysis failed is still a 200: status is failed and error says why. Delete it and upload the file again.
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope media:read
Lists the scenes the analysis found (a scene is a stretch of film between two cuts), with their first and last frame, start time, whether they are black-and-white or colour, and a sharpness score.
Parameters
Name
Where
Type
Required
What it is
media_id
path
string
yes
The media's id, as POST /uploads/{upload_id}/complete or GET /media gave it. Example: med_4821.
What you get back: 200 OK with data, one entry per scene: index (from 0), first_frame and last_frame (frame numbers from 0; the last frame belongs to the scene), start_seconds (seconds from the start), color (bw or color) and quality (the scene's sharpness score, 0 to 1; higher is sharper).
Good to know: A sound-only media has no scenes (data is empty).
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope media:read
Gives you a still image (JPEG) of the media at a point in time - for a list or a preview picture in your own program.
Parameters
Name
Where
Type
Required
What it is
media_id
path
string
yes
The media's id, as POST /uploads/{upload_id}/complete or GET /media gave it. Example: med_4821.
at_seconds
query
number
no
Where, in seconds from the start: a number from 0, for example 1.5. A time after the end is taken as 0.2 seconds before the end; a negative time or text answers ValidationFailed. Default: the middle of the media.
width
query
integer
no
The image's width in pixels: 64 to 960 (an odd number is made one smaller). The height follows the picture's shape. Default: 480.
What you get back: 200 OK with the JPEG image (image/jpeg), cached by your client for up to 300 seconds.
Good to know: A sound-only media has no picture: NotFound.
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope media:write
Deletes a media together with its previews and jobs, as the workspace does. Running jobs are stopped, and what they were charged without delivering a result is given back.
Parameters
Name
Where
Type
Required
What it is
media_id
path
string
yes
The media's id, as POST /uploads/{upload_id}/complete or GET /media gave it. Example: med_4821.
What you get back: 204 No Content: deleted; no body. This cannot be undone: download the results you want to keep first.
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope previews:write
Makes a free before/after image of one frame of the media with the settings you are considering - so you can see the effect before you pay for a job. A preview is never charged.
Parameters
Name
Where
Type
Required
What it is
media_id
path
string
yes
The media's id, as POST /uploads/{upload_id}/complete or GET /media gave it. Example: med_4821.
Idempotency-Key
header
string
no (recommended)
Your own value of 1 to 64 printable characters: a new random one (a UUID) for every new request, and the same one when you send that request again after a lost response. The shell examples keep it in a variable that a second run of the same block does not change (see Idempotency keys). Example: 9b2f0c7e-3d4a-4f61-8a5e-2c1b7d9e0f43.
settings
body (JSON)
object
yes
What the job does: either preset_id or filters (not both), optionally output_format and output_scaling.
settings.preset_id
body (JSON)
string
one of the two
A preset of GET /catalogue (presets[].id): its filters, output format and output scaling. Example: pre_90. A preset's upload server (a website setting) is never used by an API job: the result stays here for you to download.
settings.filters
body (JSON)
array of strings
one of the two
Filter keys of GET /catalogue (filters[].key; the full list is in Filters). At most one of light_dust_and_scratches, medium_dust_and_scratches and heavy_dust_and_scratches. An empty list [] runs no filter: the job only re-encodes the media into the output format (and scales it, with output_scaling), at the full price of its tier. Example: ["noise", "medium_dust_and_scratches"].
settings.output_format
body (JSON)
string
no
The result's file type: mov_prores_422_hq, mov_prores_4444, mxf_dnxhr_hqx, mxf_dnxhr_444, mp4_h264 or mp4_hevc. Default: the preset's format, or mov_prores_422_hq with filters.
settings.output_scaling
body (JSON)
string
no
The result's height: source (the same as the media), 1080 (HD) or 2160 (4K). Default: the preset's scaling, or source with filters. A larger output can raise the price (see Billing).
at_frame
body (JSON)
integer
no
The frame to show, from 0 to the media's frames - 1.
at_seconds
body (JSON)
number
no
Or the time to show, in seconds from 0 to the media's duration_seconds. Use one of the two. Default (neither): the middle of the media.
kind
body (JSON)
string
no
Only image. Default: image.
What you get back: 202 Accepted with a Preview object (statusqueued) and a Location header. Poll GET /previews/{preview_id} until ready; in our tests a preview took 3 to 30 seconds.
Good to know: Limits: 20 restoration and 5 colorization previews per company in 24 hours (PreviewLimitReached), 2 being made at the same time per user (PreviewsBusy). Every plan has colorization previews; the Free plan has no daily count (previews_left_todaynull). A still image cannot show motion or sound: image stabilization, content stabilization, natural speed, high frame rate and the sound filters are left out of a preview.
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope media:read
Downloads one of the two images of a ready preview: before.jpg (the frame as it is now, cropped and scaled as the result will be) or after.jpg (the same frame with the settings).
Parameters
Name
Where
Type
Required
What it is
preview_id
path
string
yes
The preview's id, as POST /media/{media_id}/previews gave it. Example: prv_3171.
which
path
string
yes
before or after.
What you get back: 200 OK with the JPEG image, cached by your client for up to 600 seconds. Before the preview is ready: PreviewNotReady (Retry-After: 5).
Error codes it can answer (each links to what it means and what to do): NotFound. Any endpoint can also answer RateLimited and InternalError.
Login to your Account
Signing you in...
Sign in as ?
You opened a sign-in link from your e-mail. Signing in here signs you in on this device (this browser). If you asked for the link in another window, you can type its code there instead.
