Resolution

Protocol reference. The current sandbox matches fictional talent by explicit ID or text. Standalone resolution, a downloadable name index and image or voice recognition remain planned. Start with the runnable quickstart and sandbox support matrix.

Resolution finds which talent a request invokes. Every check resolves its inputs, including when you name talent yourself. Resolution never clears anything: it says who is in a request, and the license decides what may be done.

How a request invokes a talent

How the request invokes them	`matched_by`	Typical `confidence`
You pass the talent’s ID in `talent`, from a cast picker or catalog	`explicit`	`exact`
The name or a confirmed alias appears in text	`name`, `alias`	`high`, `medium` or `low`
An indirect reference, such as “the host of Ridge Runners”	`indirect`	Usually `medium`
A reference image or voice sample of the talent	`reference_image`, `voice_sample`	Depends on the match score
A description with no name or credit	Not resolved

Names, aliases, transliterations and credits come from Atlas. Reference media is matched against the face and voice of every talent with protection.references on. A description alone is not resolved, and outputs are checked only for the talent the check covered; see Generation checks.

Matching is inclusive

A check treats every candidate at medium confidence or higher as invoked, and its decision is the most restrictive across them. This produces false positives for common names: a prompt about a different person who shares a name with a protected talent is checked against that talent too. To remove the friction, narrow the check:

Pass talent with explicit IDs when your product already knows who the user means. A name in the inputs that a talent in talent carries counts as that talent, not as a match for someone else who shares it.
Pass exclude_talent with the IDs of talent your user confirmed they did not mean.

The alternative, matching only when certain, would let a misspelled or renamed prompt through, and that failure would land on the talent. Inclusive matching puts the cost on a confirmation step in your product instead.

No match is not permission

When no protected talent is found, a check returns allow with talent: []. That means only that the request names no one Reflections protects. It is not a license for any person the output shows. A resolution with status: "none" means the same thing.

Use kind

Resolution also classifies how the inputs use a talent, as use_kind:

`use_kind`	Meaning	License needed
`depiction`	The talent is shown or heard	Yes
`impersonation`	Speaks or writes as the talent	Yes
`endorsement`	Implies the talent approves something	Yes
`reference`	Talked about, without synthesis, such as a news question	No

This keeps an assistant from refusing ordinary questions about public figures. It is a classification for routing, not a legal finding. The use.kind you send on a check must describe what your model will produce.

Resolving before the check

Checks resolve automatically, so most platforms never call resolution directly. Call POST /v1/resolutions when your own interface needs the candidates, for example to ask “did you mean Maya Okafor?” before you check. A resolution’s status is matched, ambiguous (more than one candidate, or one weak candidate) or none. Each candidate carries matched_by, confidence, the span of input text that matched, whether the licensee holds an active license for that talent (licensed), and the talent’s declaration for the use.

The name index

If you do not want to send every prompt, download the signed name index and match names on your side. It holds every protected talent’s names, aliases and transliterations, normalized with nfkc_casefold. Normalize prompt text the same way before you match. An entry with common: true is a name common enough that a match alone is weak evidence. Verify the index’s signature against the JWKS before you use it, refresh it at least hourly with If-None-Match, and stop matching against it after expires_at. A local match tells you to send a check. No local match does not clear a prompt: indirect references and reference media need the server. See Privacy for the prompt modes that pair with local matching.

Example: a podcast intro

curl https://app.reflections.ai/v1/resolutions \
  -H "Authorization: Bearer rk_test_…" \
  -H "Reflections-Version: 2026-10-15" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{ "role": "prompt", "text": "A podcast intro read by Maya Okafor" }],
    "modality": "speech"
  }'

const resolution = await fetch("https://app.reflections.ai/v1/resolutions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.REFLECTIONS_KEY}`,
    "Reflections-Version": "2026-10-15",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    inputs: [{ role: "prompt", text: "A podcast intro read by Maya Okafor" }],
    modality: "speech",
  }),
}).then((r) => r.json());

import os, uuid, requests

resolution = requests.post(
    "https://app.reflections.ai/v1/resolutions",
    headers={
        "Authorization": f"Bearer {os.environ['REFLECTIONS_KEY']}",
        "Reflections-Version": "2026-10-15",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "inputs": [{"role": "prompt", "text": "A podcast intro read by Maya Okafor"}],
        "modality": "speech",
    },
).json()

{
  "id": "res_2d4f6h8k0m2p4r6t8v0x2z4b6c",
  "object": "resolution",
  "status": "matched",
  "candidates": [
    {
      "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
      "name": "Maya Okafor",
      "matched_by": "name",
      "confidence": "high",
      "span": { "input": 0, "start": 24, "end": 35, "text": "Maya Okafor" },
      "licensed": true,
      "declaration": "license_required"
    }
  ],
  "use_kind": "impersonation"
}

The app shows “Maya Okafor” as the voice, then sends the check with talent: ["tal_9t0wxyhk5zba2q8v1m3n7p4r6s"] and the voice facet in facet, so the check skips resolution and decides against her voice license.

Atlas

The names and credits resolution matches against.

Resolving talent

Explicit IDs, autocomplete, disambiguation and the name index.

Several talent

The most restrictive rule across talent.

Resolve talent

The endpoint reference.

Get started

Quickstarts

Concepts

Integration guides

Build

Go to production

How a request invokes a talent

Matching is inclusive

No match is not permission

Use kind

Resolving before the check

The name index

Example: a podcast intro

Atlas

Resolving talent

Several talent

Resolve talent

​How a request invokes a talent

​Matching is inclusive

​No match is not permission

​Use kind

​Resolving before the check

​The name index

​Example: a podcast intro

​Related

Atlas

Resolving talent

Several talent

Resolve talent

How a request invokes a talent

Matching is inclusive

No match is not permission

Use kind

Resolving before the check

The name index

Example: a podcast intro

Related