Objects
The JSON objects the endpoints answer with, field by field. Fields marked "only when ..." are missing from the JSON otherwise. We add fields over time: ignore fields you do not know.
The Upload object
An upload: POST /uploads, GET /uploads/{upload_id}.
| Field | Type | What it is |
|---|---|---|
id | string | The upload's id: upl_ and 24 characters. |
status | string | open (takes chunks) or completed (the file is a media). |
file_name | string | The file's name as stored (shortened when it was longer than 200 characters). |
size | integer | The file's size in bytes. |
chunk_size | integer | The size of every chunk except the last, in bytes. |
chunk_count | integer | How many chunks the file has: chunk numbers run from 0 to chunk_count - 1. |
max_parallel | integer | How many chunks of this upload can be on their way at the same time (4). |
chunk_url_template | string | The address of a chunk: replace {index} with the chunk number. |
direct_chunk_url_template | string | Only for API keys: the same on the server that holds the upload (see Cloud servers). |
received_count | integer | How many different chunks have arrived. |
received_bytes | integer | How many bytes of the file have arrived. |
missing | array of integers | The chunk numbers still missing - at most the first 1,000. Empty: every chunk is there. |
purpose | string | job or preview. |
media_id | string or null | The media made from it, once completed; null before. |
expires_at | string (time) | When an open upload is removed if no further chunk arrives (7 days after the last chunk; each chunk moves it on). A completed upload is kept 1 day after its completion, whatever this says. |
The Media object
A media: GET /media/{media_id}, GET /media, the completion of an upload, an import.
| Field | Type | What it is |
|---|---|---|
id | string | The media's id, for example med_4821. |
name | string | Its name: the file's name, with a number added when you have a media of that name already (A001_C003 (2).mov). |
status | string | queued (waiting for the analysis or still downloading), analyzing, ready (a job or preview can use it) or failed. |
stage | string or null | While queued or analysing: downloading (an import), information, transcoding or analyzing; null otherwise. |
percent | number | Progress of the stage, 0 to 100; 100 when ready. |
eta_seconds | integer or null | Estimated seconds left of the stage (transcoding, analyzing); null while unknown and in the other stages. |
size | integer | The file's size in bytes. |
purpose | string | job or preview. |
duration_seconds | number | Only when ready: the length in seconds. |
frames | integer | Only when ready: the number of frames (0 for a sound-only file). |
frame_rate | object or null | Only when ready: frames per second as num/den (25/1 = 25 fps, 24000/1001 = 23.976 fps); null for a sound-only file. |
width, height | integer | Only when ready: the frame size we work with, in pixels (0 for a sound-only file). |
source_geometry | object or null | Only when ready: the uploaded file's own width, height, pixel aspect sar (for example "1:1") and field_order (progressive, tff top field first, bff bottom field first). What match source gives back. |
pixel_aspect | string | Only when ready: the shape of a pixel, "1:1" for square pixels. |
field_order | string | Only when ready: progressive, tff, bff or mixed (interlaced video has fields). |
pulldown | boolean | Only when ready: true when 3:2 pulldown was removed at the analysis (29.97 fps became 23.976 fps). |
crop | object or null | Only when ready: the black borders found - left, top, right, bottom in pixels - the picture inside them (inner_width, inner_height) and its shape (ratio, for example "1.33:1"). null for a sound-only file. |
color | string or null | Only when ready: bw (black-and-white), color or mixed (both kinds of scenes); null for a sound-only file. |
audio | object or null | Only when ready: channels, sample_rate (Hz) and silent (true: the sound is silence); null without sound. |
timecode | string or null | Only when ready: the file's start timecode, for example 01:00:10:00; null without. |
scene_count | integer | Only when ready: how many scenes were found (scenes). |
warnings | array of strings | Only when ready: interlaced, pulldown_removed, letterboxed (black borders found), portrait, variable_frame_rate, low_resolution, low_bitrate. Empty: nothing to note. |
source | object or null | What you sent as source with the upload, unchanged. |
jobs, previews | array of strings | Only for a single media (not in lists): the ids of its jobs and previews. |
created_at | string (time) or null | When the media was made. |
error | object or null | Only when failed: {"code": "MediaFailed", "message": "..."}; {"code": "ChecksumMismatch", "message": "..."} when the file is not the one whose sha256 you gave at POST /uploads; or {"code": "PictureTooLarge", "message": "...", "details": {"width", "height", "max_long_side", "max_short_side"}} when the picture is larger than we take (its file is deleted); null otherwise. |
The Preview object
A preview: POST /media/{media_id}/previews, GET /previews/{preview_id}.
| Field | Type | What it is |
|---|---|---|
id | string | The preview's id, for example prv_3171. |
media_id | string | The media it shows. |
status | string | queued, rendering (being made), ready or failed. |
kind | string | image (the website also makes video previews; the API reads them but does not make them). |
frame | integer | The frame shown, from 0. |
progress | object or null | While rendering: percent (0 to 100) and eta_seconds (seconds left, or null); null otherwise. |
before_url, after_url | string or null | When ready: the addresses of the two images (with your credentials); null before. |
width, height | integer or null | When ready: the images' size in pixels. |
charged | boolean | Always false: previews are free. |
previews_left_today | object | How many free previews your company has left in the current 24 hours: restoration and colorization (each null on the Free plan: no daily count). |
expires_at | string (time) or null | When it is deleted: 6 hours after it was finished. |
error | object or null | When failed: {"code": "PreviewFailed", "message": "..."}. |
The Quote object
A quote: POST /quotes.
| Field | Type | What it is |
|---|---|---|
price | Money | What the job costs, in your company's currency. |
charge | object | What the start would take, and from where: amount and currency (from a prepaid balance always in EUR), from - balance (prepaid), quota (the seconds of a Trial; then also seconds), invoice or none (the Free plan: nothing is charged, every price is 0). |
tier | string | sd, hd, 2k or 4k (a 4K result) (Billing). |
price_class | string | restoration or colorization (the same prices unless your company has its own price list). |
duration_seconds | number | The seconds priced. |
covers | boolean | true: the job would start now. false: it would be refused - see refusal. |
refusal | object or null | When covers is false: the code, detail and details (an object, or null) the start would answer, for example BalanceInsufficient or OptionConflict (details.field says which setting). |
watermark | boolean | true on the Trial: the result would carry a watermark. |
estimate | boolean | true for a planned file (its frame size and length are yours, not measured). |
exchange | object or null | When your prices are in another currency than euros: the rate and date of the exchange to the euro balance; null otherwise. |
settings | object | The settings priced: preset_id, filters, output_format, output_scaling. |
media_id | string | Only with media_id: the media priced. |
The Job object
A job: POST /jobs, GET /jobs/{job_id}, GET /jobs, cancel, approve, webhooks.
| Field | Type | What it is |
|---|---|---|
id | string | The job's id, for example job_3150. |
media_id | string | The media it processes. |
status | string | queued, running, needs_action, completed, failed or cancelled (Jobs). |
stage | string or null | While running or needs_action: what it does now (the list); null otherwise. |
needs_action | string or null | keyframes while it waits for your review; null otherwise. |
progress | object | percent (the whole job, 0 to 100), stage_percent (the current stage, 0 to 100, or null), eta_seconds (estimated seconds left, or null while unknown). |
queue | object | position (how many tasks are ahead of it; 0 when it is not waiting) and message (for example Queued: 2 tasks ahead, or null). |
settings | object | preset_id (the preset you named, or null) and filters (the filter keys it runs). |
output | object | The output options (geometry, frame_rate, audio, timecode, reel_name) with format and scaling. |
price | Money | The job's price. |
billing | object | state: reserved (taken at the start), settled (delivered), refunded (given back) or none (nothing taken, for example on invoice); charged: what was taken - a Money object, {"seconds": 12} on the Trial, or null. |
watermark | boolean | true: the result carries the Trial's watermark. |
keyframes | string | review or auto. |
created_at, started_at, finished_at | string (time) or null | When it was made, when work began, when it ended (null until then). |
result | object or null | Only when completed: url (the download address; null when the file is gone), file_name, size (bytes), sha256 (the file's SHA-256, for jobs started through the API; null for a workspace job), content_type and expires_at (when the file is deleted, 60 days after the job finished). |
error | object or null | Only when failed: {"code": "JobFailed", "message": "..."}. |
reference, client_data | string, object or null | What you sent with POST /jobs, unchanged. |
The Keyframes object
The keyframes of a job: GET /jobs/{job_id}/keyframes, PUT.
| Field | Type | What it is |
|---|---|---|
saturation | integer | The colour strength of the whole job in percent (50 to 200; 100 = as colorized). |
scenes | array | One entry per scene: scene (its number, from 0), first_frame and last_frame, coverage (percent of the scene's frames the keyframes cover and the number of uncovered_frames, or null) keyframes (a list of Keyframe objects) and modify (the scene's keyframe changes: limit, used, remaining; null limits on the Free plan). |
The Keyframe object
One keyframe: an entry of the keyframes list, and GET/POST .../keyframes/{frame}/modify.
| Field | Type | What it is |
|---|---|---|
frame | integer | Its frame number (from 0). |
image_url | string | Its thumbnail (JPEG, 480 pixels wide). Once it has more than one version the address ends in ?v= and the active version, so that no cache shows an old version. |
full_url | string | The same at full size (PNG). |
original_url | string | The same frame before colorization (JPEG). |
saturation | integer | Its colour strength in percent (its own, or the job's). |
excluded | boolean | true: left out. |
shown | boolean | true for the three keyframes per scene the website's dialog shows. Every keyframe that is not left out is used. |
active_version | integer | The version that is shown, approved and carried to the frames (1 = the colorization). |
attention | string or null | rejected: the version in use is a picture our check rejected (you can keep it - it is your choice); no_picture: the keyframe has no picture at all (the frame before colorization); null otherwise. Show these keyframes marked. |
needs_choice | boolean | true while the keyframe is used and has no picture: choose another version, change it or leave it out - approving answers KeyframeNeedsChoice until then. false when none of that is possible (the scene then keeps the frame before colorization). |
versions | array | Every colour version, oldest first: version, text (the sentence that made it; null for version 1), created (time), image_url, full_url, rejected (true for a picture our check rejected - in the colorization's tries or a change's; show it marked, it can still be chosen for free and never counts as a change), reason (why it was rejected, a sentence for the person; null otherwise), picture (false for the version of a keyframe without a picture) and deletable (true for a Modify try - a change's picture, also one our check rejected: DELETE deletes it) and charge (a Modify try on the Prepaid plan: {"state": ...} - pending until it is settled, charged once it was taken from the balance (a small charge - the order history of the website lists it), none when it was not charged; null when nothing is charged: the colorization's versions, the Free and Invoice plans). A keyframe whose every try was rejected has only rejected versions - the best one active. |
original_version | integer | The keyframe's Original: its own colorization (for a keyframe whose colorization was all rejected, the best of those tries). It becomes the one in use when the one in use is deleted. |
modify | object | Its last change: available (whether changes are offered - the same on every keyframe; false while changes are switched off or not set up on this site - then the change answers FeatureUnavailable with details.reason not_enabled or not_configured - and on a plan without Modify, the Trial plan: included false, the change answers ModifyNotIncluded; show your change button disabled; versions and saturation work either way), included (whether the plan has Modify), charged (whether each try is a small charge from the balance - the Prepaid plan), charge_currency (EUR, or null), state (idle, running, done or failed), per (always keyframe), limit (the tries this keyframe can keep at a time - Free, Prepaid and Invoice 5 tries per keyframe at a time, Trial none (Modify is not included)), used (the tries it keeps now: every picture a change gave it, also one our check rejected - a deleted one no more), remaining (its room for more tries), scene (the scene's own count: scene, per, limit, used - its keyframes' tries added up - and remaining - their room added up), phase (while running: queued, working or retrying - the image service is asked again; otherwise null), frames (the keyframes its last change went to), last_text (as written), sent_text (as the check passed it on), text_max (the longest text, 300), warning (the check's note on the last change - the colour asked for is much darker or lighter than the thing in the film, so it comes out lighter or darker; a sentence to show, the change was made all the same; otherwise null), version (when done: the version it made), error_code (when failed: refused - the image service declined the change under its content rules, describe it differently -, failed - try again - or rejected - our check rejected every picture of the change: they are in versions, marked, and each is a try), error (a sentence for the person), started and finished (times), kept (the Modify tries the keyframe keeps now - its versions with deletable true) and kept_max (the most it keeps at a time - the same as limit: then a change answers KeyframeTriesFull until one is deleted). |
The Me object
Your account: GET /me.
| Field | Type | What it is |
|---|---|---|
user | object | id, first_name, last_name, email, two_factor (true: two-factor authentication on), api_enabled. |
company | object | id, name, account_type (client, partner or owner). |
plan | object | code (free, trial, prepaid or invoice), name (to show), watermark (true on the Trial), billing (how jobs are paid: balance, quota, invoice or none). |
balance | Money or null | The prepaid balance in EUR; null on plans without one. |
quota | object or null | The seconds left of a Trial: restoration_seconds, colorization_seconds, shared (true: one pool for both); null otherwise. |
limits | object | trial_max_seconds (on the Trial the longest media per kind, {"restoration": 300, "colorization": 60}; null otherwise), max_upload_bytes, max_open_uploads, chunk_size (min, max, default in bytes), disk_used_percent (your storage, 0 to 100), previews_left_today, active_previews_max, picture (the largest picture you can upload, max_long_side and max_short_side; null on the Free plan: no limit). |
prices | object | currency, discount_percent (your company's), per_minute (per class restoration/colorization and tier sd/hd/2k/4k - 4k is a job that delivers 4K - as strings with the discount applied), minimum (null: none) and rule (the pricing rule in a sentence). |
capabilities | object | What this site can run now (true or false): colorize, reconstruct, interpolate, audio, match_source, keyframes_auto, ranges (false: parts of a media are not supported), previews, webhooks (true for API keys). |
defaults | object | What our apps use: handles_seconds (seconds added before and after a cut part), output_format, keyframes. |
links | object | Website pages for what the API does not do: workspace, top_up, account, connected_apps, order_history, support (the Contact Us part of the About Us page), terms, privacy, upgrade (where a Trial or Free account changes its plan) and pricing (the workspace, where a signed-in account sees its own prices). |
account | object | What an app's Account tab offers (see Website pages from an app): billing (prepaid, invoice, trial or free), can_top_up (true on Prepaid), can_upgrade (true on the Trial), billing_note (a short text to show instead, such as Invoiced monthly; null when none), web_links (true: this sign-in can open the pages signed in with POST /auth/web-links - app sign-ins only), web_pages (the pages it opens) and pages (each page's own address: opened without a link, the person signs in first). |
auth | object | How this request is signed in: kind (api_key, api_token - a token made from a key - or app_login), client_id, login_id, scopes, access_expires_at (when the token expires; null for a key) and device_name (an app sign-in's device name as Connected Apps shows it; null otherwise). |
The Catalogue object
What a job can be made of: GET /catalogue.
| Field | Type | What it is |
|---|---|---|
filters | array | Every filter: key (for settings.filters), group, label, stage (restoration, colorize, reconstruct, interpolate or audio), kind (video or audio), changes_timing (true: it changes the frame rate), conflicts_with (only for those: ["frame_rate:source"]), price_class, allowed (always true), description and example_url (an example video, for most filters). See Filters. |
exclusive_groups | array of arrays | Filters of which you can choose at most one (the three dust and scratches levels). |
output_formats | array | key (for settings.output_format), label, container (mov, mxf or mp4) and edit_friendly (true: made for editing; MP4 is for viewing). |
output_scalings | array | key (source, 1080, 2160) and label. |
output_options | object | The allowed values of output.geometry, output.frame_rate and output.audio. |
limits | object | picture: the largest picture we take (max_long_side, max_short_side), as in GET /health. |
pricing | object | Our list prices: tiers and output_4k_eur_per_min, as in GET /health (your own prices: prices of GET /me). |
presets | array | Every preset you can use: id, name, owner (global: ours; user: saved by you in the workspace), filters, output_format, output_scaling, colorize (true: it colorizes), allowed (always true). |
The Tokens object
Tokens: the sign-in endpoints and POST /auth/token.
| Field | Type | What it is |
|---|---|---|
token_type | string | Always Bearer. |
access_token | string | The access token: rma_ and 43 characters. Send it as Authorization: Bearer .... |
expires_in | integer | Seconds until it expires (3600). |
refresh_token | string | Only for app sign-ins: the refresh token, rmr_ and 43 characters. Store it safely; it works 90 days. |
refresh_expires_in | integer | Only with a refresh token: seconds until it expires (7776000 = 90 days). |
scope | string | The scopes, separated by spaces. |
login_id | string | The sign-in's id (al_...), as Connected Apps lists it. |
user, company | object | Only for app sign-ins: id and names, to show "Signed in as ...". |
status | string | Only for app sign-ins: signed_in. |
A Money object is {"amount": "12.40", "currency": "EUR"} (Times, money and ids).
