Colour tags, outlines from clicks, and matching a keyframe: an object takes the colour it has in another keyframe of the clip.
Match Colour
Gives an object the colour it has in another keyframe of the same clip, while the job waits for your review of the keyframes: outline the object in the keyframe where its colour is right and save it as a colour tag, outline the same object in other keyframes as the tag's targets, then match each of those keyframes - a new try of it. You click, we outline: no model is needed on your side. Free on every plan, Trial included, and never one of the Modify tries.
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope jobs:read
Lists the clip's colour tags for Match Colour. A tag is an object outlined in one keyframe whose colour is right (its reference); its targets are the same object outlined in other keyframes of the clip, which a match gives the tag's colour. Free on every plan. As the website does it: save an object as a tag, then give its colour to an object of any keyframe (its own keyframe too) by setting it as a target there and matching that keyframe at once - one object onto one target, a new try.
Parameters
Name
Where
Type
Required
What it is
job_id
path
string
yes
The job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
What you get back: 200 OK with tags, oldest first, and max_tags (the most a clip can have). Per tag: reference - the keyframe whose colour it gives (frame), the version it was outlined on (version) and the version in use now (current_version; stale true when they differ), its clicks, its outline (stateready, working while it is being made or failed; area_px, score from 0 to 1, outline_url), warnings with warning_texts and cutout_url, a small picture of the object cut out of the keyframe; targets by keyframe - their objects (the same fields) and applied (the try that last gave them the tag's colour, and the reference version it used). A target whose reference has changed since keeps its colour until you match its keyframe again.
Good to know: The tags belong to this clip (its job) only and go with it. Warnings never stop anything; they name what can make a result less good, each with its sentence to show in warning_texts: little_colour (the reference has hardly any colour), fragmented_outline (a pattern outlined in pieces), coloured_light (strongly coloured light in the keyframe), may_include_person (a part you clicked away is still inside), low_score and empty_outline.
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope keyframes:write
Makes a colour tag: name it and click its object in the keyframe whose colour is right. We outline the object from your clicks and cut out its picture.
Parameters
Name
Where
Type
Required
What it is
job_id
path
string
yes
The job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
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.
name
body (JSON)
string
no
The tag's name, 1 to 40 characters, different from the clip's other tags. Example: Mia's dress. Left out, the tag is named after what the object is, numbered within the clip (Dress 1, Car 2), or Object 1 when we cannot tell; rename it at any time.
found
body (JSON)
string
no
Instead of reference (19 Nov 2026): the id of a garment we found in a keyframe (GET .../found-objects, e.g. f443-v2-0) - its keyframe and clicks are the reference, and without a name the tag is named from what it is at once (Dress 1). NotFound when the keyframe shows another picture now.
outline_id
body (JSON)
string
no
With reference (19 Nov 2026): the outline_id of POST .../outline made for exactly these clicks on this keyframe - a ready one is taken over, so the object is not outlined a second time; any other is ignored (outlined anew).
reference
body (JSON)
object
no
Needed without found. {"frame": 443, "clicks": [...]}: the keyframe whose colour is right, and the object's clicks there (as objects of POST .../outline).
What you get back: 201 Created with the tag as GET /jobs/{job_id}/colour-tags shows it, and its address in Location. The outline comes within about a second; when it takes longer, reference.state is working with Retry-After: 1 - get the tag again (GET .../colour-tags/{tag_id}).
Good to know: A clip has at most 12 tags (ValidationFailed, 422, details.fieldtags). Clicks that cannot be used answer ValidationFailed with status 422 and the field in details.field. When Match Colour is not running at the moment the request answers FeatureUnavailable (details.reasonno_worker, Retry-After: 60).
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope keyframes:write
Renames a colour tag, or gives it another reference object (other clicks, or another keyframe).
Parameters
Name
Where
Type
Required
What it is
job_id
path
string
yes
The job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
tag_id
path
string
yes
The colour tag's id, as POST /jobs/{job_id}/colour-tags or GET /jobs/{job_id}/colour-tags gave it. Example: t1.
name
body (JSON)
string
no
The new name.
reference
body (JSON)
object
no
A new reference object, {"frame": 443, "clicks": [...]} (without frame: the same keyframe). Not a keyframe that is one of the tag's targets.
What you get back: 200 OK with the tag. A new reference is outlined again (reference.state); the keyframes it was applied to keep their colour until you match them again.
Good to know: Send at least one of name and reference.
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope jobs:read
Downloads a colour tag's picture: its reference object cut out of the keyframe, at most 256 pixels on its long side, transparent around the object - to show the tag.
Parameters
Name
Where
Type
Required
What it is
job_id
path
string
yes
The job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
tag_id
path
string
yes
The colour tag's id, as POST /jobs/{job_id}/colour-tags or GET /jobs/{job_id}/colour-tags gave it. Example: t1.
What you get back: 200 OK with a PNG with transparency. Use the address of reference.cutout_url: it changes when the picture does.
Good to know:NotFound while the tag has no picture yet (its outline is still being made).
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope keyframes:write
Adds the tag's object in a keyframe of the clip (a target): click it there, or send the clicks of an object we found there (GET .../found-objects). The objects replace the tag's objects in that keyframe.
Parameters
Name
Where
Type
Required
What it is
job_id
path
string
yes
The job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
tag_id
path
string
yes
The colour tag's id, as POST /jobs/{job_id}/colour-tags or GET /jobs/{job_id}/colour-tags gave it. Example: t1.
frame
path
integer
yes
The keyframe's frame number (counted from 0), as frame in GET /jobs/{job_id}/keyframes. Example: 12.
objects
body (JSON)
array
yes
The objects on this keyframe, at most 16: each {"clicks": [...]}. clicks are 1 to 32 points on the object in the order they were made, each {"x": 0.51, "y": 0.72, "mode": "add"} - x and y from 0 to 1 from the picture's left and top edge, modeadd (a part of the object) or remove (not this part); at least one add.
outline_id
body (JSON)
string
no
(19 Nov 2026) The outline_id of POST .../outline made for exactly these objects on this keyframe: a ready one is taken over - no second outline, the target is ready at once. Any other is ignored (outlined anew).
What you get back: 200 OK with the target: its objects outlined by us (stateworking with Retry-After: 1 when that takes longer - get the tag again) and applied.
Good to know: Any keyframe of the clip, the tag's own reference keyframe too, and at most 16 tagged objects in one keyframe (ValidationFailed, 422). Only the objects you set change colour. Then match the keyframe (POST .../match-colour).
{ "frame": 511, "applied": null,
"objects": [ { "id": "t1-511-1", "state": "ready", "clicks": [ "..." ], "area_px": 120176, "score": 0.947,
"warnings": [ "may_include_person" ], "warning_texts": [ "The outline still covers a part you removed. It may include the person wearing it." ],
"outline_url": "https://www.recuromedia.com/api/2.0/jobs/job_3152/keyframes/511/objects/t1-511-1.png?v=1763457180" } ] }
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope keyframes:write
Outlines objects in a keyframe from clicks - our outline of each, the same one a match uses. Nothing is saved: use it to show a person what their clicks select.
Parameters
Name
Where
Type
Required
What it is
job_id
path
string
yes
The job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
frame
path
integer
yes
The keyframe's frame number (counted from 0), as frame in GET /jobs/{job_id}/keyframes. Example: 12.
objects
body (JSON)
array
yes
The objects on this keyframe, at most 16: each {"clicks": [...]}. clicks are 1 to 32 points on the object in the order they were made, each {"x": 0.51, "y": 0.72, "mode": "add"} - x and y from 0 to 1 from the picture's left and top edge, modeadd (a part of the object) or remove (not this part); at least one add.
replaces
body (JSON)
string
no
(19 Nov 2026) The outline_id of an earlier outline of this keyframe you no longer want (the person clicked again): it is cancelled while it still waits for us, so it never holds up this one. An unknown or finished one is simply nothing to cancel.
What you get back: 200 OK within about a second, with each object's outline on the keyframe's version in use (version): outline as run lengths - size [height, width], and counts: the lengths of the runs of pixels row by row from the top left, the first run outside the object (0 when the first pixel is inside), then inside, outside and so on - and as a picture (outline_url, 255 inside, 0 outside), area_px, score and warnings. When it takes longer: 202 Accepted with stateworking, Location and Retry-After: 1 - get GET .../outline/{outline_id} every second.
Good to know: You need nothing else to outline objects: no model of your own. An outline is kept for an hour. Keep its outline_id: saving the same clicks as a tag (POST .../colour-tags) or a target (PUT .../targets/{frame}) with it takes this outline over instead of making another.
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope keyframes:write
Matches a keyframe: every tagged object in it takes the colour of its tag's reference object, in one new try of the keyframe. Free on every plan - also Trial - and never one of the Modify tries.
Parameters
Name
Where
Type
Required
What it is
job_id
path
string
yes
The job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
frame
path
integer
yes
The keyframe's frame number (counted from 0), as frame in GET /jobs/{job_id}/keyframes. Example: 12.
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.
(the body)
body (JSON)
object
no
Empty ({}): all of the keyframe's tagged objects are matched.
What you get back: 202 Accepted with the match as GET .../match-colour shows it, Location (that address) and Retry-After: 1. It takes about a second.
Good to know: The colour is copied by brightness: the keyframe keeps its own light, grain and folds; near-whites stay white; nothing outside the objects changes. Where two objects overlap the smaller one wins. The result is a new version of the keyframe and the one in use (sourcematch_colour in versions); choose another version as always (PUT /jobs/{job_id}/keyframes) or delete the try (DELETE .../versions/{version}). A keyframe without tagged objects answers ValidationFailed (422); while the keyframe is being changed - a Modify or another match - ModifyInProgress with Retry-After: 1. Approving the keyframes waits for every match.
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope jobs:read
Shows a keyframe's last match - poll it every second while it is queued or working.
Parameters
Name
Where
Type
Required
What it is
job_id
path
string
yes
The job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
frame
path
integer
yes
The keyframe's frame number (counted from 0), as frame in GET /jobs/{job_id}/keyframes. Example: 12.
If-None-Match
header
string
no
The last ETag (a free 304 when nothing has changed).
What you get back: 200 OK with state: idle (no match yet), queued, working, done (version: the new try, in use now) or failed (error says why), warnings with warning_texts, and a Retry-After header (1 while it runs, 60 otherwise).
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope jobs:read
Gets a keyframe ready for outlining in your own program: the keyframe's embedding for the outline decoder, made once per version of the keyframe. Only for a client that runs the decoder itself - POST .../outline needs none of this.
Parameters
Name
Where
Type
Required
What it is
job_id
path
string
yes
The job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
frame
path
integer
yes
The keyframe's frame number (counted from 0), as frame in GET /jobs/{job_id}/keyframes. Example: 12.
What you get back: 200 OK when it is made (url: the file), 202 Accepted with stateworking and Retry-After: 1 while it is being made - ask again every second. size is the keyframe's [width, height]; layout.tensors are the file's parts in order.
Good to know: The file is for the outline decoder named in layout.decoder.
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope jobs:read
Lists the garments we found in a keyframe that no colour tag covers yet, best first - each one a colour tag can be made of with {"found": "<id>"} (POST .../colour-tags). Free on every plan.
Parameters
Name
Where
Type
Required
What it is
job_id
path
string
yes
The job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
frame
path
integer
yes
The keyframe's frame number (counted from 0), as frame in GET /jobs/{job_id}/keyframes. Example: 12.
What you get back: 200 OK. stateready: the garments as found; working (with Retry-After: 1): the keyframe is being listed - ask again after a second, each request moves the lists on, this keyframe first; waiting: Match Colour is not running at the moment; failed: tried again later; off: switched off on this site. progress: the clip's keyframes listed so far. Each object's outline comes in the answer as run lengths, as POST .../outline gives them: one request a keyframe, no picture to download for each object.
Good to know: We list every keyframe's garments in the background once the job waits for its keyframes - a few seconds for a clip; a job made before this gets its lists when they are first asked for. A keyframe whose version in use changes is listed again, and an id is only for the picture the keyframe shows now. The lists are kept in the job's folder and deleted with the job, with faces and hands cut out. To give a found object a tag's colours, send its clicks as the target (PUT .../targets/{frame}).