← Other Eyes
Reel API
Tokens

Drive Other Eyes from your own code

The one metered task, retell, is available over HTTP. It takes up to seven everyday things (one per line), one of six animals and a reader (a kid or a grown-up), and returns a verdict (a different world, a tilted world, or mostly familiar), one frame per thing - what you notice, what the animal probably gets, and why - plus a dead-simple picture of how its senses work, a safe one-minute thing to try, and what scientists are still unsure about.

The division of labour first: the page owns the sense cards, the keyword guess and the verdict rule; the model owns the retelling; the page re-checks the reply. All three come from eyekit.js, which you can run yourself (see Build the input yourself). The sense cards are rounded popular-science summaries, not measurements.

Get a token on the token page (step 2 below also shows how to mint a guest token in code).

Base URL and the envelope

Every endpoint lives under https://api.skillsafe.ai/v1/app-api, and every response uses one envelope:

{ "ok": true,  "data":  { ... } }
{ "ok": false, "error": { "code": "...", "message": "...", "status": 402, "details": { ... } } }

The token is minted for this app (the guest call takes {"slug":"other-eyes"}), so no slug header is needed afterwards. Send it as Authorization: Bearer …. The run body is the input object, sent bare.

StatusCodeMeaning
400validation_errorThe body is not a JSON object, or a required field (task, animal, reader, senses, scene, guess) is missing.
401unauthorizedNo token, or a stale one. Mint a guest token or sign in again.
402insufficient_creditsThe balance is under min_credits. Price with /estimate first.
403forbiddenA guest token tried to run: retelling a reel is metered and needs a personal token.
404not_foundUnknown job id.
429rate_limitedBack off and retry.
5xxserver_errorTransient. Retry with the same Idempotency-Key so a retry never double-bills.

The task field, the shifts and the verdict

Every run sends task: retell; a missing or different one is still answered as retell. Each thing gets one shift, checked in a fixed order:

  1. new - the animal picks something up from the thing through a sense its card says people lack (ultraviolet, polarised light, heat sensing, echoes, ultrasound, infrasound, a magnetic sense).
  2. gone - what a person most notices is something the card says the animal has no sense for at all (red for a honeybee, red or green as colours for a dog, a high sound in the air for a rattlesnake).
  3. sharper - it senses the thing more keenly than a person through a keen sense on its card.
  4. duller - everything else.

The verdict then follows the shifts, first match wins: alien if three or more frames are new or gone; otherwise shifted if one or two are; otherwise familiar. The page computes the same rule over the reply's own frames (EyeKit.verdictFor) and flags a reply that disagrees.

The input

Every value is a string (objects are never sent). app.js builds it with EyeKit.buildInput(form).input.

FieldRequiredWhat it holds
taskyesAlways retell.
animalyes<id> - <name>: shrimp - Mantis shrimp, bee - Honeybee, dog - Dog, bat - Insect-eating bat, snake - Rattlesnake or pigeon - Pigeon.
readeryesStarts with kid or grownup, then a short description in brackets.
sensesyesThe page's sense card for the animal (EyeKit.senseCard): its facts, what is still unsure, the senses it has that people lack, and what it has no sense for at all. The model's only source of animal facts.
sceneyesNumbered lines, 1. ..., one thing per line. At most 7 are sent (the reel holds seven pairs); a line over 160 characters keeps its start and end around [...].
guessyesThe page's keyword guess, one line per thing: <n> | <shift> | <channel>. Only a guess; the shift rules win.
clip_notenoWhat the page shortened, or absent.
retry_notenoSent only on the page's one reformat retry.

The reply

The reply is one JSON object in job.output.output. The page parses it with EyeKit.parseReply and EyeKit.normalize (a cut-off stream is closed by EyeKit.closeJson and shown as "N of 8 sections recovered").

{"task": "retell", "verdict": "alien | shifted | familiar", "verdict_reason": "...", "title": "...",
 "big_idea": "...", "picture": "...",
 "frames": [{"n": 1, "shift": "new | gone | sharper | duller",
             "channel": "colour | uv | polarized | smell | hearing | ultrasound | infrasound | heat | echo | vibration | magnetic | motion",
             "you_notice": "...", "it_gets": "...", "why": "..."}],
 "try_it": "...", "not_sure": "..."}
FieldRule
framesExactly one entry per numbered thing, same numbers and order. you_notice at most 12 words from the thing's own line; it_gets at most 24 words, hedged; why one card fact of at most 18 words. A new frame's channel is one of the animal's extra senses; no other frame uses an extra-sense channel.
big_ideaOne sentence of at most 25 words, the way you would tell a five-year-old.
pictureTwo or three short sentences: one everyday comparison ("Imagine ...") built only from the card.
try_itOne safe thing to do at home in a minute, at most 30 words - never the sun, bright lights, lasers, ultraviolet lamps, wild animals or anything hot.
not_sureOne sentence from the card's "Still unsure".

The page then checks the reply against its own facts (EyeKit.check): one frame per thing, the verdict against the reply's own frames, every extra sense one the animal's card lists, no extra-sense channel on a frame not marked as one, nothing gone for an animal whose card lists nothing it cannot sense, the keyword guess where it differs, an unsafe try-it idea, and no internal field name in the prose.

Worked examples, one per verdict

These are the four free samples on the page: the exact input and a stand-in model's reply, unedited.

Honeybee at the kitchen table - alien

Input:

{
 "task": "retell",
 "animal": "bee - Honeybee",
 "reader": "kid (a curious reader aged about 6 to 9: short everyday words, one idea per sentence)",
 "senses": "Honeybee (a flower-visiting insect). Three kinds of colour receptors like ours, but tuned to ultraviolet, blue and green - there is no red one, so red looks dark. Many petals carry ultraviolet patterns, like landing stripes, that people cannot see. Reads polarised light in the sky to keep its direction, and smells keenly through its antennae. Still unsure: Exactly how a bee's brain blends its colours into what it experiences is still being worked out. Senses it has that people lack: ultraviolet light, polarised light. Has no sense at all for: the colour red (it has no red receptor).",
 "scene": "1. A bunch of yellow sunflowers in a vase\n2. A ripe red strawberry on a plate\n3. Blue sky through the open window\n4. A bowl of white sugar\n5. A jar of honey with the lid off",
 "guess": "1 | new | uv\n2 | gone | colour\n3 | new | polarized\n4 | duller | colour\n5 | sharper | smell"
}

Reply:

{
 "task": "retell",
 "verdict": "alien",
 "verdict_reason": "Two things reach it through senses you lack and one is gone for it, making three unusual shifts in total.",
 "title": "How a Honeybee Senses These Things",
 "big_idea": "A honeybee sees colours differently from you, catches light patterns you cannot see, and smells very well with its antennae.",
 "picture": "Imagine petals have hidden stripes painted on them, like a landing strip only the bee can see. To you the petal looks plain, but to the bee the stripes point the way in.",
 "frames": [
  {
   "n": 1,
   "shift": "new",
   "channel": "uv",
   "you_notice": "A bunch of yellow sunflowers in a vase",
   "it_gets": "It likely sees ultraviolet patterns on the petals, like landing stripes no person can see, guiding it toward the flower.",
   "why": "Many petals carry ultraviolet patterns, like landing stripes, that people cannot see."
  },
  {
   "n": 2,
   "shift": "gone",
   "channel": "colour",
   "you_notice": "A ripe red strawberry on a plate",
   "it_gets": "It probably sees the strawberry as a dark shape rather than red.",
   "why": "It has no red colour receptor, so red looks dark to it."
  },
  {
   "n": 3,
   "shift": "new",
   "channel": "polarized",
   "you_notice": "Blue sky through the open window",
   "it_gets": "It likely reads the polarised light pattern in the sky, which helps it know which way is home.",
   "why": "It reads polarised light in the sky to keep its direction."
  },
  {
   "n": 4,
   "shift": "duller",
   "channel": "colour",
   "you_notice": "A bowl of white sugar",
   "it_gets": "The bee probably sees the white sugar about the way a person does, with no extra colour clues.",
   "why": "None of its special senses is tuned to this white colour."
  },
  {
   "n": 5,
   "shift": "sharper",
   "channel": "smell",
   "you_notice": "A jar of honey with the lid off",
   "it_gets": "The bee likely smells the honey very strongly through its antennae, picking up more than a person would.",
   "why": "It smells keenly through its antennae."
  }
 ],
 "try_it": "Close your eyes and smell a flower or some honey. Notice how much your nose can tell you without looking.",
 "not_sure": "Scientists are still not sure exactly how a bee's brain blends its colours into what it experiences."
}

Pigeon in the town square - shifted

Input:

{
 "task": "retell",
 "animal": "pigeon - Pigeon",
 "reader": "kid (a curious reader aged about 6 to 9: short everyday words, one idea per sentence)",
 "senses": "Pigeon (a city bird). Four kinds of colour receptors, one reaching into ultraviolet light. Eyes on the sides of its head give it a very wide view, nearly all the way around. Can detect very low sounds, far below what people hear, and is thought to sense Earth's magnetic field to find home. Still unsure: How birds sense the magnetic field is still debated by scientists. Senses it has that people lack: ultraviolet light, magnetic sense, infrasound. Has no sense at all for: nothing on this list.",
 "scene": "1. Breadcrumbs scattered on the pavement\n2. A bus rumbling past\n3. People walking all around the square\n4. A yellow umbrella\n5. The fountain splashing",
 "guess": "1 | duller | colour\n2 | new | infrasound\n3 | sharper | motion\n4 | sharper | colour\n5 | duller | colour"
}

Reply:

{
 "task": "retell",
 "verdict": "shifted",
 "verdict_reason": "One thing reaches it through a sense you lack, and none is gone for it.",
 "title": "How a Pigeon Senses the Square",
 "big_idea": "A pigeon sees far more around it at once, sees extra colours, and may feel low rumbles and the Earth's pull for home.",
 "picture": "Imagine having eyes on the sides of your head so you could watch almost the whole square without turning your head. Now imagine feeling a quiet pull, like a compass, nudging you toward home.",
 "frames": [
  {
   "n": 1,
   "shift": "duller",
   "channel": "colour",
   "you_notice": "Breadcrumbs on the pavement",
   "it_gets": "It probably sees the crumbs about as plainly as you do, with nothing special drawing its eye.",
   "why": "None of its special senses is especially tuned to this."
  },
  {
   "n": 2,
   "shift": "new",
   "channel": "infrasound",
   "you_notice": "A bus rumbling past",
   "it_gets": "It may pick up a deep rumble from the bus, in sounds far too low for you to hear.",
   "why": "It can detect very low sounds, far below what people hear."
  },
  {
   "n": 3,
   "shift": "sharper",
   "channel": "motion",
   "you_notice": "People walking all around the square",
   "it_gets": "It likely notices people moving all around it at once, in a wider view than you have.",
   "why": "Eyes on the sides of its head give it a very wide view, nearly all around."
  },
  {
   "n": 4,
   "shift": "sharper",
   "channel": "colour",
   "you_notice": "A yellow umbrella",
   "it_gets": "It probably sees the umbrella's yellow very clearly, a bit sharper than most people would notice.",
   "why": "It has four kinds of colour receptors, one reaching into ultraviolet light."
  },
  {
   "n": 5,
   "shift": "duller",
   "channel": "hearing",
   "you_notice": "The fountain splashing",
   "it_gets": "It probably hears the splashing about as well as you do, with nothing extra there for it.",
   "why": "None of its special senses is especially tuned to ordinary splashing sounds."
  }
 ],
 "try_it": "Hold your arms out to the sides and try to see them without turning your head, to feel how wide a pigeon's view is.",
 "not_sure": "Scientists still debate exactly how birds sense Earth's magnetic field."
}

Mantis shrimp at a desk - shifted

Input:

{
 "task": "retell",
 "animal": "shrimp - Mantis shrimp",
 "reader": "grown-up (plain words for an adult, still no jargon)",
 "senses": "Mantis shrimp (a reef crustacean). About 12 kinds of colour receptors - people have 3 - including several for ultraviolet light. Sees polarised light, the direction light waves wiggle, including a kind almost no other animal is known to see. Each eye sits on a stalk and moves on its own, scanning the scene in strips. Still unsure: Lab tests suggest it is worse than people at telling two close colours apart, so it may recognise colours quickly rather than finely. Senses it has that people lack: ultraviolet light, polarised light. Has no sense at all for: nothing on this list.",
 "scene": "1. A glass of water on the windowsill\n2. My phone screen lit up with a message\n3. A bowl of oranges\n4. A striped beach towel on the chair\n5. A poster of tropical fish on the wall",
 "guess": "1 | new | polarized\n2 | new | polarized\n3 | duller | motion\n4 | duller | motion\n5 | duller | motion"
}

Reply:

{
 "task": "retell",
 "verdict": "shifted",
 "verdict_reason": "Two things reach it through senses you lack, and the other three come through the same ordinary senses as yours.",
 "title": "How the Mantis Shrimp Sees Your Room",
 "big_idea": "A mantis shrimp sees many more kinds of light than you do, including kinds you cannot see at all.",
 "picture": "Imagine wearing special glasses that show a hidden shimmer in ordinary light, a pattern no one around you can see. A mantis shrimp sees that shimmer naturally, with eyes that sit on stalks and scan the scene on their own.",
 "frames": [
  {
   "n": 1,
   "shift": "new",
   "channel": "polarized",
   "you_notice": "A glass of water on the windowsill",
   "it_gets": "It probably sees a shimmer of polarised light bouncing off the water and the glass that you cannot see.",
   "why": "Mantis shrimp can see polarised light, a sense people do not have."
  },
  {
   "n": 2,
   "shift": "new",
   "channel": "polarized",
   "you_notice": "A phone screen lighting up with a message",
   "it_gets": "It probably picks up a pattern of polarised light in the screen's glow that you cannot notice at all.",
   "why": "It senses polarised light, something people cannot detect at all."
  },
  {
   "n": 3,
   "shift": "duller",
   "channel": "motion",
   "you_notice": "A bowl of oranges",
   "it_gets": "It probably takes in the bowl of oranges about as plainly as you do, maybe a little less.",
   "why": "None of its special senses is tuned to this ordinary sight."
  },
  {
   "n": 4,
   "shift": "duller",
   "channel": "motion",
   "you_notice": "A striped beach towel on the chair",
   "it_gets": "It likely notices the towel about as well as you do, or perhaps a bit less clearly.",
   "why": "None of its special senses is tuned to this ordinary pattern."
  },
  {
   "n": 5,
   "shift": "duller",
   "channel": "motion",
   "you_notice": "A poster of tropical fish on the wall",
   "it_gets": "It probably sees the poster about as clearly as you do, maybe a little less sharply.",
   "why": "None of its special senses is tuned to this ordinary picture."
  }
 ],
 "try_it": "Hold a pair of polarised sunglasses in front of a phone or computer screen and slowly turn them to watch the brightness change.",
 "not_sure": "Scientists are still unsure whether it can tell two very similar colours apart, since tests suggest it may recognise colours quickly rather than finely."
}

Dog in the front hall - familiar

Input:

{
 "task": "retell",
 "animal": "dog - Dog",
 "reader": "grown-up (plain words for an adult, still no jargon)",
 "senses": "Dog (a pet that greets you at the door). Two kinds of colour receptors - blue and yellow - so reds and greens look alike, a dull yellowish grey. A nose far keener than ours, with a large part of the brain given to smell. Hears high pitches above the top of human hearing, and spots movement well in dim light. Still unsure: Nobody can measure exactly how much keener a dog's nose is; published estimates vary enormously. Senses it has that people lack: ultrasound. Has no sense at all for: red and green as colours (they look alike).",
 "scene": "1. A pot of soup bubbling on the stove\n2. The doorbell ringing\n3. A blue ball under the chair\n4. A newspaper on the table\n5. Muddy boots by the door",
 "guess": "1 | sharper | smell\n2 | sharper | hearing\n3 | duller | colour\n4 | duller | colour\n5 | sharper | smell"
}

Reply:

{
 "task": "retell",
 "verdict": "familiar",
 "verdict_reason": "All five things reach it through senses it already has: three sharper than yours and two duller.",
 "title": "A Dog's Senses Around the House",
 "big_idea": "A dog explores the world mostly through its nose and ears, noticing smells and sounds far more than colours.",
 "picture": "Imagine turning up a radio so quiet sounds become easy to hear. A dog's nose works a bit like that, picking up faint smells that a person would never notice.",
 "frames": [
  {
   "n": 1,
   "shift": "sharper",
   "channel": "smell",
   "you_notice": "A pot of soup bubbling on the stove.",
   "it_gets": "It probably catches the soup's smell far more strongly than a person would, its nose keenly tuned to such scents.",
   "why": "Its nose is far keener than a person's, with a large part of its brain devoted to smell."
  },
  {
   "n": 2,
   "shift": "sharper",
   "channel": "hearing",
   "you_notice": "The doorbell ringing.",
   "it_gets": "It probably hears the doorbell's ring more keenly than a person does, its hearing sharper overall.",
   "why": "It hears high pitches above what a person's ears can reach."
  },
  {
   "n": 3,
   "shift": "duller",
   "channel": "colour",
   "you_notice": "A blue ball under the chair.",
   "it_gets": "It probably sees the ball's blue about the same as a person, or a little less vividly.",
   "why": "None of its special senses is tuned especially to this blue ball."
  },
  {
   "n": 4,
   "shift": "duller",
   "channel": "colour",
   "you_notice": "A newspaper on the table.",
   "it_gets": "It probably takes little notice of the newspaper, since paper means much less to it than to a person.",
   "why": "None of its special senses is tuned to a newspaper like this one."
  },
  {
   "n": 5,
   "shift": "sharper",
   "channel": "smell",
   "you_notice": "Muddy boots by the door.",
   "it_gets": "It likely catches the mud's scent powerfully, its nose far more sensitive to such smells than a person's.",
   "why": "Its nose is far keener than a person's, with much of its brain devoted to smell."
  }
 ],
 "try_it": "Close your eyes and try to name a scent from across the room - a dog could likely do this with smells far fainter than you can catch.",
 "not_sure": "Scientists are still unsure exactly how much keener a dog's nose is, since estimates vary widely."
}

Build the input yourself

Load the script in node (global.window = global; require("./eyekit.js")), then:

const K = EyeKit;
const form = K.form({ animal: "snake", reader: "kid",
  scene: "A mug of hot tea\nA wind chime by the door\nThe dog asleep on the rug\nA bowl of crisps" });
K.things(form);                                  // one thing per line, with the page's shift and channel guess
K.verdictFor(K.counts(K.things(form)));          // {verdict: "alien", why: [...]} - the page's rule over its guesses
K.senseCard(K.animal("snake"));                  // the sense card the model is given
const built = K.buildInput(form);
const wire = K.toWire(built.input);              // POST this to /estimate and /run
// then: const reply = K.normalize(K.parseReply(job.output.output));
// K.check(reply, built).notes                   // the page's re-check of the reply
// K.md(built, reply)                            // the reel as Markdown

Step 1 — a tiny client helper

One function that sends JSON and unwraps the envelope. Paste a personal token from /tokens.html, or leave it empty and mint a guest token in step 2.

BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="paste-your-token-here"   # from https://other-eyes.skillsafe.ai/tokens.html
api() { # api METHOD PATH [JSON-BODY]
  curl -s -X "$1" "$BASE$2" -H "Content-Type: application/json" \
    ${TOKEN:+-H "Authorization: Bearer $TOKEN"} ${3:+--data "$3"}
}

Step 2 — a token

A guest token is enough for /me and /estimate. A run is metered, so it needs a personal token: sign in on /tokens.html and copy it from there.

# a guest token (enough for /me and /estimate); a run needs your personal token from /tokens.html
TOKEN=$(curl -s -X POST "$BASE/guest" -H "Content-Type: application/json" -d '{"slug":"other-eyes"}' | jq -r '.data.token')

Step 3 — GET /me

Who the token is (subject_type: user or guest) and the credit balance.

api GET /me | jq '.data | {subject_type, credits}'

Step 4 — POST /estimate

Free. The body is the run input itself, the bare object (never wrapped in {"input": ...}). hold_credits is a reservation, not the price; min_credits is what the balance must cover; model_alias reads gpt-terra.

# input.json: the run input object - {"task": "retell", "animal": "shrimp - Mantis shrimp", "reader": "grown-up (plain words for an adult, still no jargon)", "senses": "Mantis shrimp (a reef crustacean). About 12 kinds of colour receptors - people have 3 - including several for ultraviolet light. Sees polarised light, the direction light waves wiggle, including a kind almost no other animal is known to see. Each eye sits on a stalk and moves on its own, scanning the scene in strips. Still unsure: Lab tests suggest it is worse than people at telling two close colours apart, so it may recognise colours quickly rather than finely. Senses it has that people lack: ultraviolet light, polarised light. Has no sense at all for: nothing on this list.", "scene": "1. A glass of water on the windowsill\n2. My phone screen lit up with a message\n3. A bowl of oranges\n4. A striped beach towel on the chair\n5. A poster of tropical fish on the wall", "guess": "1 | new | polarized\n2 | new | polarized\n3 | duller | motion\n4 | duller | motion\n5 | duller | motion"}
api POST /estimate "$(cat input.json)" | jq '.data | {hold_credits, min_credits, model, model_alias, markup_bps, warnings}'

Step 5 — POST /run, then poll the job

Send an Idempotency-Key built from the lane and the input: a retry with the same key never bills twice. The page uses other-eyes:<task>:<inputHash>:a<attempt> (the one task is retell), and its one reformat retry (with retry_note added) is attempt 2, a new key and a second run. The job's output.output is the reply text; truncated: true means the balance cut it short.

KEY="other-eyes:retell:$(shasum -a 256 input.json | cut -c1-16):a1"
JOB=$(curl -s -X POST "$BASE/run" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $KEY" --data @input.json | jq -r '.data.job_id')
while :; do
  J=$(api GET "/jobs/$JOB"); S=$(echo "$J" | jq -r '.data.status')
  case "$S" in succeeded|failed|cancelled) break;; esac; sleep 2
done
echo "$J" | jq -r '.data.output.output' > reply.json   # one JSON object, the reply contract
echo "$J" | jq '.data | {charged_credits, truncated}'

Step 6 — POST /run-stream

The same run as Server-Sent Events, with the same input.json. Browsers receive progress ticks rather than text deltas; the final done event carries the reply.

# Server-Sent Events: tick/delta events while the job runs, then a final event with the job
curl -N -s -X POST "$BASE/run-stream" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: other-eyes:retell:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json