Reference: Match Colour

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.

GET /jobs/{job_id}/colour-tags #

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
NameWhereTypeRequiredWhat it is
job_idpathstringyesThe 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 (state ready, 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.

Request
curl -sS -u "$AUTH" "$API/jobs/job_3152/colour-tags"
Response: 200 OK
{ "tags": [ { "id": "t1", "name": "Mia's dress", "created": "2026-11-18T09:12:00Z",
              "reference": { "frame": 443, "version": 2, "current_version": 2, "stale": false, "object": "t1-r", "state": "ready",
                             "clicks": [ { "x": 0.5405, "y": 0.7407, "mode": "add" } ], "area_px": 98351, "score": 0.857,
                             "warnings": [], "warning_texts": [], "outline_url": "https://www.recuromedia.com/api/2.0/jobs/job_3152/keyframes/443/objects/t1-r.png?v=1763457120",
                             "cutout_url": "https://www.recuromedia.com/api/2.0/jobs/job_3152/colour-tags/t1/cutout.png?v=1763457120", "...": "..." },
              "targets": { "511": { "frame": 511, "objects": [ { "id": "t1-511-1", "state": "ready", "area_px": 120176, "...": "..." } ],
                                    "applied": { "version": 5, "reference_version": 2 } } } } ],
  "max_tags": 12 }

Error codes it can answer (each links to what it means and what to do): NotFound, JobNotAwaitingKeyframes, MatchColourOff. Any endpoint can also answer RateLimited and InternalError.

POST /jobs/{job_id}/colour-tags #

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
NameWhereTypeRequiredWhat it is
job_idpathstringyesThe job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
Idempotency-Keyheaderstringno (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.
namebody (JSON)stringnoThe 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.
foundbody (JSON)stringnoInstead 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_idbody (JSON)stringnoWith 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).
referencebody (JSON)objectnoNeeded 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.field tags). 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.reason no_worker, Retry-After: 60).

Request
curl -sS -u "$AUTH" -X POST "$API/jobs/job_3152/colour-tags" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "Mia'"'"'s dress", "reference": {"frame": 443, "clicks": [{"x": 0.5405, "y": 0.7407, "mode": "add"}]}}'
Response: 201 Created
{ "id": "t1", "name": "Mia's dress", "created": "2026-11-18T09:12:00Z",
  "reference": { "frame": 443, "version": 2, "state": "ready", "area_px": 98351, "score": 0.857, "warnings": [], "...": "..." },
  "targets": {} }

Error codes it can answer (each links to what it means and what to do): ValidationFailed, NotFound, JobNotAwaitingKeyframes, MatchColourOff, FeatureUnavailable, IdempotencyKeyReused. Any endpoint can also answer RateLimited and InternalError.

GET /jobs/{job_id}/colour-tags/{tag_id} #

Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope jobs:read

Shows one colour tag - poll it every second while its outline is working.

Parameters
NameWhereTypeRequiredWhat it is
job_idpathstringyesThe job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
tag_idpathstringyesThe 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 the tag as GET /jobs/{job_id}/colour-tags shows it; Retry-After: 1 while its reference outline is being made.

Request
curl -sS -u "$AUTH" "$API/jobs/job_3152/colour-tags/t1"
Response: 200 OK
{ "id": "t1", "name": "Mia's dress", "reference": { "frame": 443, "state": "ready", "...": "..." }, "targets": { "...": "..." } }

Error codes it can answer (each links to what it means and what to do): NotFound, JobNotAwaitingKeyframes, ColourTagNotFound, MatchColourOff. Any endpoint can also answer RateLimited and InternalError.

PATCH /jobs/{job_id}/colour-tags/{tag_id} #

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
NameWhereTypeRequiredWhat it is
job_idpathstringyesThe job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
tag_idpathstringyesThe colour tag's id, as POST /jobs/{job_id}/colour-tags or GET /jobs/{job_id}/colour-tags gave it. Example: t1.
namebody (JSON)stringnoThe new name.
referencebody (JSON)objectnoA 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.

Request
curl -sS -u "$AUTH" -X PATCH "$API/jobs/job_3152/colour-tags/t1" -H "Content-Type: application/json" \
  -d '{"name": "Green dress"}'
Response: 200 OK
{ "id": "t1", "name": "Green dress", "reference": { "...": "..." }, "targets": { "...": "..." } }

Error codes it can answer (each links to what it means and what to do): ValidationFailed, NotFound, JobNotAwaitingKeyframes, ColourTagNotFound, MatchColourOff, FeatureUnavailable. Any endpoint can also answer RateLimited and InternalError.

DELETE /jobs/{job_id}/colour-tags/{tag_id} #

Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope keyframes:write

Deletes a colour tag with its outlines. The tries it made stay - delete them as any try (DELETE .../versions/{version}).

Parameters
NameWhereTypeRequiredWhat it is
job_idpathstringyesThe job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
tag_idpathstringyesThe 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: 204 No Content.

Request
curl -sS -u "$AUTH" -X DELETE "$API/jobs/job_3152/colour-tags/t1"
Response: 204 No Content
HTTP/2 204

Error codes it can answer (each links to what it means and what to do): NotFound, JobNotAwaitingKeyframes, ColourTagNotFound, MatchColourOff. Any endpoint can also answer RateLimited and InternalError.

GET /jobs/{job_id}/colour-tags/{tag_id}/cutout.png #

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
NameWhereTypeRequiredWhat it is
job_idpathstringyesThe job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
tag_idpathstringyesThe 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).

Request
curl -sS --fail -u "$AUTH" -o tag-t1.png "$API/jobs/job_3152/colour-tags/t1/cutout.png" || rm -f tag-t1.png
Response: 200 OK
HTTP/2 200
content-type: image/png

Error codes it can answer (each links to what it means and what to do): NotFound, JobNotAwaitingKeyframes, ColourTagNotFound, MatchColourOff. Any endpoint can also answer RateLimited and InternalError.

PUT /jobs/{job_id}/colour-tags/{tag_id}/targets/{frame} #

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
NameWhereTypeRequiredWhat it is
job_idpathstringyesThe job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
tag_idpathstringyesThe colour tag's id, as POST /jobs/{job_id}/colour-tags or GET /jobs/{job_id}/colour-tags gave it. Example: t1.
framepathintegeryesThe keyframe's frame number (counted from 0), as frame in GET /jobs/{job_id}/keyframes. Example: 12.
objectsbody (JSON)arrayyesThe 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, mode add (a part of the object) or remove (not this part); at least one add.
outline_idbody (JSON)stringno(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 (state working 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).

Request
curl -sS -u "$AUTH" -X PUT "$API/jobs/job_3152/colour-tags/t1/targets/511" -H "Content-Type: application/json" \
  -d '{"objects": [{"clicks": [{"x": 0.5135, "y": 0.7222, "mode": "add"}, {"x": 0.5405, "y": 0.4352, "mode": "remove"}]}]}'
Response: 200 OK
{ "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" } ] }

Error codes it can answer (each links to what it means and what to do): ValidationFailed, NotFound, JobNotAwaitingKeyframes, ColourTagNotFound, MatchColourOff, FeatureUnavailable. Any endpoint can also answer RateLimited and InternalError.

DELETE /jobs/{job_id}/colour-tags/{tag_id}/targets/{frame} #

Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope keyframes:write

Takes the tag's objects out of one keyframe. The tries made stay.

Parameters
NameWhereTypeRequiredWhat it is
job_idpathstringyesThe job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
tag_idpathstringyesThe colour tag's id, as POST /jobs/{job_id}/colour-tags or GET /jobs/{job_id}/colour-tags gave it. Example: t1.
framepathintegeryesThe keyframe's frame number (counted from 0), as frame in GET /jobs/{job_id}/keyframes. Example: 12.

What you get back: 204 No Content; NotFound when the tag has no objects in that keyframe.

Request
curl -sS -u "$AUTH" -X DELETE "$API/jobs/job_3152/colour-tags/t1/targets/511"
Response: 204 No Content
HTTP/2 204

Error codes it can answer (each links to what it means and what to do): NotFound, JobNotAwaitingKeyframes, ColourTagNotFound, MatchColourOff. Any endpoint can also answer RateLimited and InternalError.

POST /jobs/{job_id}/keyframes/{frame}/outline #

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
NameWhereTypeRequiredWhat it is
job_idpathstringyesThe job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
framepathintegeryesThe keyframe's frame number (counted from 0), as frame in GET /jobs/{job_id}/keyframes. Example: 12.
objectsbody (JSON)arrayyesThe 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, mode add (a part of the object) or remove (not this part); at least one add.
replacesbody (JSON)stringno(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 state working, 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.

Request
curl -sS -u "$AUTH" -X POST "$API/jobs/job_3152/keyframes/511/outline" -H "Content-Type: application/json" \
  -d '{"objects": [{"clicks": [{"x": 0.5135, "y": 0.7222, "mode": "add"}]}]}'
Response: 200 OK
{ "state": "ready", "outline_id": "4f0c2a9e41b7", "frame": 511, "version": 3, "error": null,
  "objects": [ { "id": "p9c1e07d2-1", "state": "ready", "clicks": [ "..." ], "area_px": 120176, "score": 0.947,
                 "warnings": [], "warning_texts": [], "outline": { "size": [ 1080, 1480 ], "counts": [ 640013, 18, 1462, "..." ] },
                 "outline_url": "https://www.recuromedia.com/api/2.0/jobs/job_3152/keyframes/511/objects/p9c1e07d2-1.png?v=1763457200" } ] }

Error codes it can answer (each links to what it means and what to do): ValidationFailed, NotFound, JobNotAwaitingKeyframes, MatchColourOff, FeatureUnavailable. Any endpoint can also answer RateLimited and InternalError.

GET /jobs/{job_id}/keyframes/{frame}/outline/{outline_id} #

Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope jobs:read

Shows an outline that answered 202 - poll it every second until state is ready or failed.

Parameters
NameWhereTypeRequiredWhat it is
job_idpathstringyesThe job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
framepathintegeryesThe keyframe's frame number (counted from 0), as frame in GET /jobs/{job_id}/keyframes. Example: 12.
outline_idpathstringyesThe outline_id of the answer of POST .../outline.

What you get back: 200 OK as POST .../outline answers it; 202 Accepted with Retry-After: 1 while it is still working.

Request
curl -sS -u "$AUTH" "$API/jobs/job_3152/keyframes/511/outline/4f0c2a9e41b7"
Response: 200 OK
{ "state": "ready", "outline_id": "4f0c2a9e41b7", "frame": 511, "version": 3, "objects": [ { "id": "p9c1e07d2-1", "...": "..." } ], "error": null }

Error codes it can answer (each links to what it means and what to do): NotFound, JobNotAwaitingKeyframes, MatchColourOff. Any endpoint can also answer RateLimited and InternalError.

GET /jobs/{job_id}/keyframes/{frame}/objects/{object_id}.png #

Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope jobs:read

Downloads our outline of an object as a picture: a grey PNG of the keyframe's size, 255 inside the object and 0 outside.

Parameters
NameWhereTypeRequiredWhat it is
job_idpathstringyesThe job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
framepathintegeryesThe keyframe's frame number (counted from 0), as frame in GET /jobs/{job_id}/keyframes. Example: 12.
object_idpathstringyesAn object's id - of a tag (t1-r, t1-511-1) or of an outline (p9c1e07d2-1).

What you get back: 200 OK with the PNG. Use the address of outline_url: it changes when the outline does.

Request
curl -sS --fail -u "$AUTH" -o t1-511-1.png "$API/jobs/job_3152/keyframes/511/objects/t1-511-1.png" || rm -f t1-511-1.png
Response: 200 OK
HTTP/2 200
content-type: image/png

Error codes it can answer (each links to what it means and what to do): NotFound, JobNotAwaitingKeyframes, MatchColourOff. Any endpoint can also answer RateLimited and InternalError.

POST /jobs/{job_id}/keyframes/{frame}/match-colour #

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
NameWhereTypeRequiredWhat it is
job_idpathstringyesThe job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
framepathintegeryesThe keyframe's frame number (counted from 0), as frame in GET /jobs/{job_id}/keyframes. Example: 12.
Idempotency-Keyheaderstringno (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)objectnoEmpty ({}): 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 (source match_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.

Request
curl -sS -u "$AUTH" -X POST "$API/jobs/job_3152/keyframes/511/match-colour" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" -d '{}'
Response: 202 Accepted
{ "frame": 511, "state": "queued", "phase": "queued", "version": null, "error": null, "warnings": [], "warning_texts": [],
  "tags": [ "t1" ], "started": "2026-11-18T09:20:00Z", "finished": null, "active_version": 3 }

Error codes it can answer (each links to what it means and what to do): ValidationFailed, NotFound, JobNotAwaitingKeyframes, ModifyInProgress, MatchColourOff, FeatureUnavailable, IdempotencyKeyReused. Any endpoint can also answer RateLimited and InternalError.

GET /jobs/{job_id}/keyframes/{frame}/match-colour #

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
NameWhereTypeRequiredWhat it is
job_idpathstringyesThe job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
framepathintegeryesThe keyframe's frame number (counted from 0), as frame in GET /jobs/{job_id}/keyframes. Example: 12.
If-None-MatchheaderstringnoThe 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).

Request
curl -sS -u "$AUTH" "$API/jobs/job_3152/keyframes/511/match-colour"
Response: 200 OK
{ "frame": 511, "state": "done", "phase": null, "version": 5, "error": null, "warnings": [ "coloured_light" ],
  "warning_texts": [ "This keyframe has strongly coloured light. Matching may remove its glow." ], "tags": [ "t1" ],
  "started": "2026-11-18T09:20:00Z", "finished": "2026-11-18T09:20:01Z", "active_version": 5 }

Error codes it can answer (each links to what it means and what to do): NotFound, JobNotAwaitingKeyframes, MatchColourOff. Any endpoint can also answer RateLimited and InternalError.

GET /jobs/{job_id}/keyframes/{frame}/embedding #

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
NameWhereTypeRequiredWhat it is
job_idpathstringyesThe job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
framepathintegeryesThe 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 state working 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.

Request
curl -sS -u "$AUTH" "$API/jobs/job_3152/keyframes/511/embedding"
Response: 200 OK
{ "state": "ready", "frame": 511, "version": 3, "size": [ 1480, 1080 ], "bytes": 8388608, "error": null,
  "layout": { "format": "f16-le-1", "byte_order": "little", "resolution": 1024, "decoder": "outline-decoder-1",
              "tensors": [ { "name": "image_embed", "shape": [ 256, 64, 64 ] }, { "name": "high_res_feats_1", "shape": [ 64, 128, 128 ] },
                           { "name": "high_res_feats_0", "shape": [ 32, 256, 256 ] } ] },
  "url": "https://www.recuromedia.com/api/2.0/jobs/job_3152/keyframes/511/embedding.f16?v=3" }

Error codes it can answer (each links to what it means and what to do): NotFound, JobNotAwaitingKeyframes, MatchColourOff, FeatureUnavailable. Any endpoint can also answer RateLimited and InternalError.

GET /jobs/{job_id}/keyframes/{frame}/embedding.f16 #

Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope jobs:read

Downloads a keyframe's embedding: 8 MiB of 16-bit floating-point numbers, little-endian, in the order of layout.tensors.

Parameters
NameWhereTypeRequiredWhat it is
job_idpathstringyesThe job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
framepathintegeryesThe keyframe's frame number (counted from 0), as frame in GET /jobs/{job_id}/keyframes. Example: 12.
vqueryintegernoThe keyframe version (version of GET .../embedding); without it, the version in use now.

What you get back: 200 OK with the file; with v it never changes and is cached by your client for a day.

Good to know: NotFound (details.reason not_ready) until GET .../embedding has made it.

Request
curl -sS --fail -u "$AUTH" -o keyframe-511-v3.f16 "$API/jobs/job_3152/keyframes/511/embedding.f16?v=3" || rm -f keyframe-511-v3.f16
Response: 200 OK
HTTP/2 200
content-type: application/octet-stream
content-length: 8388608

Error codes it can answer (each links to what it means and what to do): NotFound, JobNotAwaitingKeyframes, MatchColourOff. Any endpoint can also answer RateLimited and InternalError.

GET /jobs/{job_id}/keyframes/{frame}/found-objects #

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
NameWhereTypeRequiredWhat it is
job_idpathstringyesThe job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
framepathintegeryesThe keyframe's frame number (counted from 0), as frame in GET /jobs/{job_id}/keyframes. Example: 12.

What you get back: 200 OK. state ready: 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}).

Request
curl -sS -u "$AUTH" "$API/jobs/job_3152/keyframes/443/found-objects"
Response: 200 OK
{ "frame": 443, "version": 2, "state": "ready", "progress": { "done": 30, "total": 30 },
  "objects": [ { "id": "f443-v2-0", "name": "Dress", "word": "gown", "kind": "dress", "score": 0.93, "area_px": 98351,
                 "box": [ 612, 433, 902, 1079 ], "clicks": [ { "x": 0.5135, "y": 0.7222, "mode": "add" } ],
                 "outline": { "size": [ 1080, 1480 ], "counts": [ 641212, 37, 1443, "..." ] },
                 "cutout_url": "https://www.recuromedia.com/api/2.0/jobs/job_3152/keyframes/443/found-objects/f443-v2-0/cutout.png?v=1763540000" } ] }

Error codes it can answer (each links to what it means and what to do): NotFound, JobNotAwaitingKeyframes, MatchColourOff. Any endpoint can also answer RateLimited and InternalError.

GET /jobs/{job_id}/keyframes/{frame}/found-objects/{found_id}/cutout.png #

Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope jobs:read

Downloads a found garment cut out of its keyframe: a PNG with transparency, at most 256 pixels on its long side - to show it.

Parameters
NameWhereTypeRequiredWhat it is
job_idpathstringyesThe job's id, as POST /jobs or GET /jobs gave it. Example: job_3150.
framepathintegeryesThe keyframe's frame number (counted from 0), as frame in GET /jobs/{job_id}/keyframes. Example: 12.
found_idpathstringyesThe garment's id from GET .../found-objects.

What you get back: 200 OK with the PNG; NotFound when the keyframe shows another picture now.

Good to know: It is made the first time it is asked for, then kept with the job.

Request
curl -sS --fail -u "$AUTH" -o dress-cutout.png "$API/jobs/job_3152/keyframes/443/found-objects/f443-v2-0/cutout.png" || rm -f dress-cutout.png
Response: 200 OK
HTTP/2 200
content-type: image/png

Error codes it can answer (each links to what it means and what to do): NotFound, JobNotAwaitingKeyframes, MatchColourOff. Any endpoint can also answer RateLimited and InternalError.