> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reflections.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> The OpenAPI document at /api-reference/openapi.yaml defines the target contract. Its x-reflections-availability field and each operation's availability notice identify supported test and live forms. Do not infer implementation from a schema or code sample. Live keys support account details, reads of the licenses the calling account holds as licensee or issued as talent (GET /v1/licenses?role=issuer), and GET /v1/generations?license=… for the state of outputs under such a license (summaries only: no prompt, reference, bytes or metadata). Live image checks, submissions and receipts are built but not activated: until activation, a live POST /v1/checks or /v1/generations returns 403 live_not_activated, which must not be retried. Discovery and JWKS are at the origin root (https://app.reflections.ai/.well-known/...), not under /v1.
> Three rules hold everywhere: a decision is never an error (deny and escalate are 200 responses, and a live check still evaluating is a 202 with status checking); generate nothing for a named talent without an allow; deliver nothing until the generation is allow.
> The sandbox accepts personal rk_test_ keys. Persist a separate Idempotency-Key and body for each logical /v1 POST; retry an unknown outcome with the same key and body. OAuth and Talent API MCP remain planned.
# Talent and facets
> Who a talent is in the API, their public posture, and the facets a license can cover.
Sandbox and protocol reference. The public sandbox catalog contains fictional talent, facets
and licenses. It provides no real identity verification, licensed material or provider voice
access.
Start with the [runnable quickstart](/quickstart) and [sandbox support matrix](/sandbox).
A **talent** is a person whose name, likeness and voice are protected through Reflections. A
**facet** is one part of that identity that a license can cover, such as a likeness or a voice.
Licenses name facets, checks resolve to facets, and revocations can withdraw a single facet.
## Talent
| Field | What it holds |
| - | - |
| `name`, `aliases` | The name and the other names the talent confirmed, such as a stage name or a transliteration |
| `status` | `active`, or `withdrawn` when the talent withdrew consent everywhere |
| `verification` | Whether a real adult controls the account and signed its licenses |
| `protection` | Whether reference images and voice samples are matched against this talent's face and voice (`references`), and in which `modalities` |
| `posture` | The talent's standing public answers for uses with no license |
| `representation` | Accounts with a mandate to act for the talent, with `role` and `powers` |
| `facets` | Each facet's `id`, `type`, `label` and `status` |
| `hcs_subject_id` | The talent's subject ID in the Human Consent Registry, when registered there |
Read a talent with [`GET /v1/talent/{talent_id}`](/api-reference/talent/retrieve-a-talent) and list
them with [`GET /v1/talent`](/api-reference/talent/list-talent). When a talent's names, aliases,
posture or protection change, you receive `talent.updated`.
## Posture
A talent's **posture** is their public answer for each kind of use before any license exists. Each
rule in `posture.rules` matches on `modality`, `kind`, `purpose` and `commercial` (an omitted field
matches every value) and carries a `declaration`:
| Declaration | Meaning | What a check returns |
| - | - | - |
| `allowed` | No license needed | `allow` with the rule's `obligations`, and `license: null` |
| `license_required` | A license is needed | `allow` if a license covers the use; otherwise `deny` with `no_license` and a `license_request` remedy |
| `prohibited` | Never | `deny` with `talent_prohibits` and no remedy |
The most specific rule wins, and `prohibited` wins a tie. `posture.default` applies when no rule
matches. A license can widen `license_required`, never `prohibited`. When `accepts_requests` is
`false`, the talent does not take license requests through the API, so a `deny` carries no
`license_request` remedy.
## Verification
`verification.verified` proves that a real adult controls the talent's account and signed their
licenses, by `id_document` or through a `representative`. It does not prove who owns every right
in the name. See [What we enforce](/concepts/what-we-enforce).
## Facets
| `type` | What it covers | Typical `modalities` |
| - | - | - |
| `name` | The name in text | `text` |
| `likeness` | Face and body in images and video | `image`, `video` |
| `voice` | The voice in speech | `speech` |
| `twin` | A persona that speaks or writes as the talent | `text`, `speech` |
| `knowledge` | A Volume of the talent's own words a model may draw on | `text` |
A facet's `modalities` field is the exact list for that facet. A talent can have several facets of
one type, such as two voices. Name one on a check with `facet`; otherwise the license decides.
A facet's `status` is `preparing` (not usable yet), `ready` (licensable) or `withdrawn`. Licenses
that cover a withdrawn facet deny, and the withdrawal arrives as a revocation with
`scope: "facet"`.
### Reference material
Some facets have reference material behind them, such as the stills of a likeness. When a license's
`scope.material_access` lists a facet, the licensee may download that material with
[`GET /v1/facets/{facet_id}/material`](/api-reference/facets/retrieve-licensed-material) and send it
to a model. The URLs expire after 5 minutes, each item carries its `sha256`, and every download is
recorded on the talent's record. The response carries `obligations`, such as `no_training` and
`delete_material`, that apply to the material.
### Provider bindings
A facet can live at a model provider, such as a voice created at a voice provider.
`provider_bindings` records each copy: `provider`, `kind` (`voice`, `adapter` or `persona`),
`external_id` and `status` (`active` or `deleted`). A binding is shown only to that provider and to
licensees whose license includes material access. When a facet is withdrawn or a license is
revoked, the revocation lists the copies you must delete in `provider_copies`.
## Example: Maya Okafor
```bash cURL theme={null}
curl https://app.reflections.ai/v1/talent/tal_9t0wxyhk5zba2q8v1m3n7p4r6s \
-H "Authorization: Bearer rk_test_…" \
-H "Reflections-Version: 2026-10-15"
```
```typescript TypeScript theme={null}
const talent = await fetch(
"https://app.reflections.ai/v1/talent/tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
{
headers: {
Authorization: `Bearer ${process.env.REFLECTIONS_KEY}`,
"Reflections-Version": "2026-10-15",
},
},
).then((r) => r.json());
```
```python Python theme={null}
import os, requests
talent = requests.get(
"https://app.reflections.ai/v1/talent/tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
headers={
"Authorization": f"Bearer {os.environ['REFLECTIONS_KEY']}",
"Reflections-Version": "2026-10-15",
},
).json()
```
```json theme={null}
{
"id": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
"object": "talent",
"name": "Maya Okafor",
"aliases": [],
"status": "active",
"verification": { "verified": true, "method": "id_document", "verified_at": "2026-03-02T14:20:00Z" },
"protection": { "references": true, "modalities": ["image", "video", "speech"] },
"posture": {
"default": "license_required",
"rules": [{ "purpose": "political", "declaration": "prohibited" }],
"accepts_requests": true
},
"facets": [
{ "id": "fct_5zba2q8v1m3n7p4r6s9t0wxyhk", "type": "likeness", "label": "Studio likeness", "status": "ready" },
{ "id": "fct_v1m3n7p4r6s9t0wxyhk5zba2q8", "type": "voice", "label": "Speaking voice", "status": "ready" }
],
"hcs_subject_id": null
}
```
Any use of Maya Okafor needs a license, political uses are never allowed, and she accepts license
requests. Her likeness and her voice are separate facets, so a license for images does not cover
her voice.
## Related
The names and credits behind resolution.
What a license covers, and how it changes.
How a prompt is matched to talent.
Withdrawing a facet, a license or all consent.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.