> ## 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. # Discard a license draft > **Planned contract — unavailable in test and live modes.** This operation is a protocol reference, not a callable endpoint. Start with the [working sandbox quickstart](/quickstart). Discards an open draft. Needs a mandate with `issue_licenses` for the talent. Its `signing_url` stops working at once. Restricted keys need `license_drafts:write`. ## OpenAPI ````yaml /api-reference/openapi.yaml post /license_drafts/{draft_id}/discard openapi: 3.1.0 info: title: Reflections Talent API version: '2026-10-15' summary: The license server for a person's name, likeness and voice in generative AI. description: > This document defines the target Talent API contract. Each operation declares its current test and live availability. Test mode serves a limited fictional sandbox. Live keys support account details and reading the caller's own licenses. The initial live image check, submission and receipt implementation is deployed, but requires separate live signing activation and production acceptance. Start at https://docs.reflections.ai/quickstart for test mode. The target API lets any product that can generate a real person check whether a use is licensed, verify the output it made, prove that verification to anyone downstream, report usage, and honor revocations. Protected requests use a secret key in the `Authorization` header. The target contract defines test keys (`rk_test_…`) and live keys (`rk_live_…`) use the same base URL; the key decides the mode. A decision is never an error. `deny` and `escalate` are `200` responses that carry a decision. Errors use RFC 9457 problem details. contact: name: Reflections developer support url: https://docs.reflections.ai/production/support email: developers@reflections.ai servers: - url: https://app.reflections.ai/v1 description: >- Fictional test sandbox and conditional live support; availability and activation are separate security: - SecretKey: [] tags: - name: Account description: The account that owns the calling key. - name: Talent description: >- People whose name, likeness and voice are protected and licensed through Reflections. - name: Facets description: >- The parts of a talent's identity a license can cover, such as a voice or a likeness. - name: Resolutions description: Find which talent a prompt, image or voice sample invokes. - name: Licenses description: Signed licenses and their revisions. - name: License requests description: Ask a talent for a new license or a wider one. - name: Connections description: A licensee's permission for a platform to use its licenses. - name: Files description: References and outputs uploaded for checks and generations. - name: Checks description: Decide whether a use may proceed, before anything is generated. - name: Generations description: Check an output against the license its check relied on. - name: Sessions description: Authorize live voice and video with short-lived tokens and sampled checks. - name: Receipts description: Signed, portable proof of a decision. - name: Verifications description: Verify a file, manifest or receipt. - name: Revocations description: Every narrowing of consent, and the platform's acknowledgement of it. - name: Usage records description: Report usage for settlement and audit. - name: Statements description: Monthly amounts owed under a license, reconciled against observed usage. - name: Mandates description: A representative's authority to act for a talent, and its powers. - name: Escalations description: >- The review queue. Checks and held outputs waiting for the talent's side to decide. - name: License drafts description: Terms prepared for a talent's signature. Only a person signs. - name: Webhook endpoints description: Where Reflections sends events. - name: Events description: The record of everything that happened to your objects. - name: Test helpers description: Act as a talent or reviewer in test mode. - name: Discovery description: The public discovery document and signing keys. Neither needs a key. - name: OAuth description: > Authorization for connections, MCP clients and RSL clients, and the metadata that describes it. paths: /license_drafts/{draft_id}/discard: post: tags: - License drafts summary: Discard a license draft description: > **Planned contract — unavailable in test and live modes.** This operation is a protocol reference, not a callable endpoint. Start with the [working sandbox quickstart](/quickstart). Discards an open draft. Needs a mandate with `issue_licenses` for the talent. Its `signing_url` stops working at once. Restricted keys need `license_drafts:write`. operationId: discardLicenseDraft parameters: - $ref: '#/components/parameters/ReflectionsVersion' - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/LicenseDraftId' responses: '200': description: The discarded draft. headers: Request-Id: $ref: '#/components/headers/RequestId' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/LicenseDraft' examples: discarded: summary: A discarded draft value: id: ldr_ddnyf8nhrged1gk09qg30hamjd object: license_draft livemode: true status: discarded kind: issue talent: tal_9t0wxyhk5zba2q8v1m3n7p4r6s licensee: acct_2q8v1m3n7p4r6s9t0wxyhk5zba license: null license_request: null scope: facets: - fct_5zba2q8v1m3n7p4r6s9t0wxyhk modalities: - image kinds: - depiction purposes: - advertising commercial: true channels: - social - web territories: - US - CA window: starts_at: '2026-10-01T00:00:00-04:00' ends_at: '2027-03-31T00:00:00-04:00' time_zone: America/New_York adjustments: reframe: true background_extension: true lighting: true text_overlay: true body_and_age: false expression: false hair: false pose: false wardrobe: true objects: true skin_retouch: false endorsement: false prohibited_changes: - body_and_age - expression - hair - pose - skin_retouch - endorsement required_attributes: - identity.samePerson - appearance.bodyAndAge - appearance.expression - appearance.hair - appearance.pose - appearance.skinRetouch - context.endorsement rules: never: - Do not show alcohol or tobacco. always: [] brief: null release_policy: per_output_review escalation_window: P7D final_deliverables: 24 sessions: permitted: false material_access: [] platforms: mode: any_connected accounts: [] sublicense: none training: prohibited disclosure: brand attribution: null post_revocation: policy: retain exclusivity: exclusive: false category: null conflicts: [] compensation: type: per_unit per_unit: units: placements rate: amount: 25000 currency: usd per: 1 minimum: amount: 500000 currency: usd schedule: monthly terms_digest: >- sha256:39f18c8bef02b5226b9feaa92e526ed30b81b91650d8a10b503281b169f44431 signer: representative signing_url: null signed_as_drafted: null license_revision: null decision_note: null note: Social and web in the US and Canada, October to March. created_by: acct_6m8n0p2q4r6s8t0v2w4x6y8z0b expires_at: '2026-10-22T14:05:00Z' signed_at: null declined_at: null metadata: deal_id: RDG-FW26-014 created_at: '2026-09-22T14:05:00Z' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/MandateRequired' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/Unprocessable' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/Unavailable' security: - SecretKey: - license_drafts:write x-codeSamples: - lang: bash label: cURL source: > # Set a unique key once per new action; persist it and reuse it for every retry. : "${REFLECTIONS_KEY:?Set REFLECTIONS_KEY before running this example}" : "${REFLECTIONS_DISCARD_LICENSE_DRAFT_IDEMPOTENCY_KEY:?Set REFLECTIONS_DISCARD_LICENSE_DRAFT_IDEMPOTENCY_KEY before running this example}" curl --fail-with-body --max-time 30 -X POST 'https://app.reflections.ai/v1/license_drafts/ldr_hz4ngq81vhagynxm3ds9q2acz4/discard' \ -H "Authorization: Bearer $REFLECTIONS_KEY" \ -H "Reflections-Version: 2026-10-15" \ -H "Idempotency-Key: $REFLECTIONS_DISCARD_LICENSE_DRAFT_IDEMPOTENCY_KEY" - lang: typescript label: TypeScript source: > import { env, exit } from "node:process"; // Set a unique key once per new action; persist it and reuse it for every retry. const apiKey = env.REFLECTIONS_KEY; if (!apiKey) throw new Error("Set REFLECTIONS_KEY before running this example"); const idempotencyKey = env.REFLECTIONS_DISCARD_LICENSE_DRAFT_IDEMPOTENCY_KEY; if (!idempotencyKey) throw new Error("Set REFLECTIONS_DISCARD_LICENSE_DRAFT_IDEMPOTENCY_KEY before running this example"); const response = await fetch("https://app.reflections.ai/v1/license_drafts/ldr_hz4ngq81vhagynxm3ds9q2acz4/discard", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Reflections-Version": "2026-10-15", "Idempotency-Key": idempotencyKey, }, signal: AbortSignal.timeout(30_000), }); const responseBody = await response.text(); if (!response.ok) { console.error(`HTTP ${response.status}: ${responseBody}`); exit(1); } console.log(responseBody); - lang: python label: Python source: > import os from urllib.error import HTTPError from urllib.request import Request, urlopen # Set a unique key once per new action; persist it and reuse it for every retry. apiKey = os.environ["REFLECTIONS_KEY"] if not apiKey: raise ValueError("Set REFLECTIONS_KEY before running this example") idempotencyKey = os.environ["REFLECTIONS_DISCARD_LICENSE_DRAFT_IDEMPOTENCY_KEY"] if not idempotencyKey: raise ValueError("Set REFLECTIONS_DISCARD_LICENSE_DRAFT_IDEMPOTENCY_KEY before running this example") headers = { "Authorization": f"Bearer {apiKey}", "Reflections-Version": "2026-10-15", "Idempotency-Key": idempotencyKey, } request = Request("https://app.reflections.ai/v1/license_drafts/ldr_hz4ngq81vhagynxm3ds9q2acz4/discard", method="POST", headers=headers) try: with urlopen(request, timeout=30) as response: print(response.read().decode("utf-8")) except HTTPError as error: error_body = error.read().decode("utf-8") raise RuntimeError(f"HTTP {error.code}: {error_body}") from error - lang: go label: Go source: | package main import ( "fmt" "io" "net/http" "os" "time" ) func main() { // Set a unique key once per new action; persist it and reuse it for every retry. apiKey := os.Getenv("REFLECTIONS_KEY") if apiKey == "" { panic("Set REFLECTIONS_KEY before running this example") } idempotencyKey := os.Getenv("REFLECTIONS_DISCARD_LICENSE_DRAFT_IDEMPOTENCY_KEY") if idempotencyKey == "" { panic("Set REFLECTIONS_DISCARD_LICENSE_DRAFT_IDEMPOTENCY_KEY before running this example") } request, err := http.NewRequest("POST", "https://app.reflections.ai/v1/license_drafts/ldr_hz4ngq81vhagynxm3ds9q2acz4/discard", nil) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer " + apiKey) request.Header.Set("Reflections-Version", "2026-10-15") request.Header.Set("Idempotency-Key", idempotencyKey) client := &http.Client{Timeout: 30 * time.Second} response, err := client.Do(request) if err != nil { panic(err) } defer response.Body.Close() responseBody, err := io.ReadAll(response.Body) if err != nil { panic(err) } if response.StatusCode < 200 || response.StatusCode >= 300 { panic(fmt.Sprintf("HTTP %d: %s", response.StatusCode, responseBody)) } fmt.Print(string(responseBody)) } components: parameters: ReflectionsVersion: name: Reflections-Version in: header required: false description: >- The dated API version. Defaults to the version your account is pinned to. schema: type: string example: '2026-10-15' IdempotencyKey: name: Idempotency-Key in: header required: false description: > A unique key for this operation, up to 255 characters. In test mode, POST keys are scoped to your account and mode and bind the endpoint and body for 24 hours. A different endpoint or body with the same key is refused. Initial live check and generation creation require a nonempty key. Each operation has a separate account-scoped namespace; retain the same API key, body and idempotency key for retries within 24 hours of creation. A pending check returns `202` with `status: "checking"`. Completed checks replay their sealed response; successful generation POSTs replay the original accepted `202`, so use GET for current state. Live verification is a read-only query that returns a fresh verification ID on each call, without exact response caching. The broader delegated-account contract also scopes keys to `Reflections-Account`; delegated requests and the other planned live POST operations remain unsupported. schema: type: string maxLength: 255 LicenseDraftId: name: draft_id in: path required: true description: The draft's ID. example: ldr_hz4ngq81vhagynxm3ds9q2acz4 schema: type: string pattern: ^ldr_[0-9a-hjkmnp-tv-z]{26}$ headers: RequestId: description: Identifies this request. Include it when you contact support. schema: type: string example: req_8f2k4m6p8r0t2v4x6z8b0d2f4h RateLimit: description: >- Remaining quota and seconds until it resets, as IETF RateLimit header fields. schema: type: string example: '"checks";r=184;t=1' RateLimitPolicy: description: The policy the RateLimit field reports against. schema: type: string example: '"checks";q=200;w=1' RetryAfter: description: Seconds to wait before retrying. schema: type: integer schemas: LicenseDraft: type: object required: - id - object - livemode - status - kind - talent - licensee - scope - terms_digest - signer - created_by - expires_at - created_at properties: id: type: string pattern: ^ldr_[0-9a-hjkmnp-tv-z]{26}$ description: The draft's ID, `ldr_…`. object: type: string const: license_draft description: Always `license_draft`. livemode: type: boolean description: '`true` in live mode, `false` in test mode.' status: $ref: '#/components/schemas/LicenseDraftStatus' description: > `open` until the signer signs or declines it, it is discarded, or it passes `expires_at`. kind: type: string enum: - issue - change_request - amend - renew description: > What signing creates. `issue`: a new license. `change_request`: a new revision answering a request of kind `change`. `amend`: new terms for `license`. `renew`: a new window for `license`. talent: type: string pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$ description: The talent the license is for. licensee: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: > The account that holds or will hold the license. It accepts what is signed on its hosted acceptance page. license: type: - string - 'null' pattern: ^lic_[0-9a-hjkmnp-tv-z]{26}$ description: >- The license this draft changes, or, once an `issue` draft is signed, the license it became. license_request: type: - string - 'null' pattern: ^lrq_[0-9a-hjkmnp-tv-z]{26}$ description: The license request this draft answers. `null` when it answers none. scope: $ref: '#/components/schemas/LicenseScope' description: >- The full terms the signer will see, with the current revision's values filled in. terms_digest: $ref: '#/components/schemas/Digest' description: > The `terms_digest` the revision will carry if it is signed as drafted. Compare it with the signed revision's to see whether the signer changed anything. signer: type: string enum: - talent - representative description: > Who signs. `talent`: the talent, in the Talent Portal. `representative`: a person at your account with `issue_licenses`. signing_url: type: - string - 'null' format: uri description: >- The Talent Portal page where the signer reads and signs the draft with a passkey. Present while `open`. signed_as_drafted: type: - boolean - 'null' description: Once signed, `false` when the signer changed terms before signing. license_revision: type: - string - 'null' pattern: ^lrv_[0-9a-hjkmnp-tv-z]{26}$ description: The revision that signing created. decision_note: type: - string - 'null' description: The signer's note when they declined. note: type: - string - 'null' description: >- Shown to the licensee on the acceptance page. `null` when you sent none. created_by: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: The representative account that prepared the draft. expires_at: type: string format: date-time description: > When the draft can no longer be signed. 30 days after it was created, unless you set an earlier time. signed_at: type: - string - 'null' format: date-time description: When the signer signed. `null` unless `signed`. declined_at: type: - string - 'null' format: date-time description: When the signer declined. `null` unless `declined`. metadata: $ref: '#/components/schemas/Metadata' description: Keys and values of your own. created_at: type: string format: date-time description: When you created the draft. LicenseDraftStatus: type: string description: > `open`: waiting for a signature at `signing_url`. `signed`: signed; `license` and `license_revision` name the result. `declined`: the signer declined it. `discarded`: you discarded it, or the mandate ended. `expired`: not signed by `expires_at`. enum: - open - signed - declined - discarded - expired LicenseScope: type: object description: > The license's terms in normalized, snake_case form. Generated from the signed `terms`; when they disagree, `terms` wins. Live license reads currently return only `window`, `required_attributes`, `release_policy` and `final_deliverables`, plus `external_creation` only when that grant is explicitly signed. Omitted fields grant nothing; this partial projection is not the complete signed document. properties: facets: type: array items: type: string pattern: ^fct_[0-9a-hjkmnp-tv-z]{26}$ description: > The facets the license covers, by ID. A use of any other facet denies with `facet_not_licensed`. modalities: type: array items: $ref: '#/components/schemas/Modality' description: > What may be generated under the license. Any other modality denies with `modality_not_licensed`. kinds: type: array items: $ref: '#/components/schemas/UseKind' description: > How the talent may appear in outputs. Any other kind denies with `kind_not_licensed`. purposes: type: array items: $ref: '#/components/schemas/Purpose' description: > What outputs may be used for. Any other purpose denies with `purpose_not_licensed`. commercial: type: boolean description: > Whether commercial use is licensed. When `false`, a commercial use denies with `commercial_use_not_licensed`. channels: type: array items: $ref: '#/components/schemas/Channel' description: > Where outputs may appear. A use that names any other channel denies with `channel_not_licensed`. From `terms.channels`. territories: type: array items: $ref: '#/components/schemas/Territory' description: > Where outputs may appear, as ISO 3166-1 alpha-2 codes or `WW`. A use that names any other territory denies with `territory_not_licensed`. From `terms.territories`. window: type: object description: > When the license is in force. From `terms.startsAt`, `terms.endsAt` and `terms.windowTimeZone`. properties: starts_at: type: string format: date-time description: > When the license comes into force. Before it, checks deny with `window_not_started`. ends_at: type: string format: date-time description: > When the license ends. From then, checks deny with `window_ended` and the license is `expired`. time_zone: type: - string - 'null' description: The IANA time zone the window's days were signed in. adjustments: type: object description: Each adjustment and whether it is allowed. From `terms.adjustments`. additionalProperties: false properties: reframe: type: boolean description: '`true` allows cropping or reframing the composition.' background_extension: type: boolean description: '`true` allows extending or replacing the background.' lighting: type: boolean description: '`true` allows changing the lighting.' text_overlay: type: boolean description: '`true` allows adding text over the output.' body_and_age: type: boolean description: '`true` allows changing the talent''s body or apparent age.' expression: type: boolean description: '`true` allows changing the talent''s facial expression.' hair: type: boolean description: '`true` allows changing the talent''s hair.' pose: type: boolean description: '`true` allows changing the talent''s pose.' wardrobe: type: boolean description: '`true` allows changing what the talent wears.' objects: type: boolean description: '`true` allows adding or changing objects in the scene.' skin_retouch: type: boolean description: '`true` allows retouching the talent''s skin.' endorsement: type: boolean description: '`true` allows outputs that imply the talent endorses something.' prohibited_changes: type: array items: $ref: '#/components/schemas/AdjustmentKind' description: Adjustments that are never allowed. From `terms.prohibitedChanges`. required_attributes: type: array items: $ref: '#/components/schemas/ProtectedAttribute' description: > What every output must keep, checked on the output bytes. Always includes `identity.samePerson`. From `terms.requiredAttributes`. rules: type: object description: >- Rules the talent wrote, as written. From `terms.neverExtras`, `terms.alwaysExtras` and `terms.creationBrief`. properties: never: type: array items: type: string maxLength: 160 description: > What outputs must never show or say, as the talent wrote it, up to 160 characters each. From `terms.neverExtras`. always: type: array items: type: string maxLength: 160 description: > What every output must show or keep, as the talent wrote it, up to 160 characters each. From `terms.alwaysExtras`. brief: type: - string - 'null' maxLength: 160 description: | The talent's brief for outputs, as written. `null` if none. From `terms.creationBrief`. external_creation: type: string enum: - images.v1 description: > The exact signed `terms.externalCreation` grant, when present. `images.v1` is prospective permission for still images made in the licensee's tools using inputs it lawfully holds, subject to request and output checks and mandatory talent release. It grants no export of private references, their identifiers or source bytes. Absence grants nothing; this value is never inferred from `make`, a creation profile or `offPlatformProduction`. This is reader support only: issuance cannot add this term yet, and live checks, output submission and receipts remain unavailable. release_policy: type: string enum: - after_checks - per_output_review description: > `after_checks`: an output that passes its checks is allowed. `per_output_review`: a person releases each output. From `terms.releasePolicy` (`dualCheckBrandRelease`, `perOutputTalentReview`). escalation_window: $ref: '#/components/schemas/Duration' description: > How long an escalation under the license waits for a decision, when shorter than the default 7 days. final_deliverables: type: - integer - 'null' minimum: 1 description: Outputs that may be delivered under the license in total. monthly_limits: type: - object - 'null' description: > Caps on use per month. Past one, checks deny with `monthly_limit_reached`. `null` when the license sets none. properties: outputs: type: integer description: Outputs per month. seconds: type: integer description: Seconds of generated audio or video per month. characters: type: integer description: Characters of generated text or speech per month. asks: type: integer description: >- Knowledge questions per month. From `terms.knowledgeGrant.asksPerMonth`. sessions: type: object description: Whether live sessions may run, and how they are sampled. properties: permitted: type: boolean description: > Whether live sessions may run under the license. When `false`, or when `release_policy` is `per_output_review`, a session is denied with `session_not_permitted`. sampling: $ref: '#/components/schemas/Sampling' description: > How each session must be sampled: the longest audio window, transcripts, and the frame interval for video. material_access: type: array description: >- Facets whose reference material the licensee may download and send to a model. items: type: string pattern: ^fct_[0-9a-hjkmnp-tv-z]{26}$ knowledge: type: - object - 'null' description: From `terms.knowledgeGrant`. properties: volume_title: type: string description: The title of the Volume a model may draw on. answers: type: string enum: - summarised - quoted description: > `summarised`: answers paraphrase the Volume. `quoted`: answers may quote it. about: type: array items: type: string description: Topics a model may answer from the Volume. never: type: array items: type: string description: Topics a model must never answer. platforms: type: object description: Which platforms may run checks under this license. properties: mode: type: string enum: - any_connected - listed description: > `any_connected`: any platform the licensee connects. `listed`: only the accounts in `accounts`. accounts: type: array items: type: string pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$ description: > The platforms that may run checks when `mode` is `listed`. Empty for `any_connected`. sublicense: type: string enum: - none - end_users_personal description: >- `end_users_personal`: a platform's end users may make personal, non-commercial outputs under the platform's license. training: type: string enum: - prohibited - permitted default: prohibited description: > Whether covered material and outputs may train a model. `prohibited` puts a `no_training` obligation on each use. Recorded, not enforced. disclosure: type: string enum: - nothing - licensed - brand - scope description: >- The label outputs carry. `licensed` says the likeness is licensed; `brand` adds who licensed it; `scope` adds the use. attribution: type: - string - 'null' description: > A credit line each output must show, delivered as an `attribution` obligation. `null` when the license requires none. Recorded, not enforced. post_revocation: type: object description: What happens to released outputs if the license is revoked. properties: policy: type: string enum: - retain - cease_distribution - withdraw description: > `retain`: released outputs stay usable within their scope and window. `cease_distribution`: no new placements after the revocation. `withdraw`: take them down within `withdraw_within`; only for revocation for cause. withdraw_within: $ref: '#/components/schemas/Duration' description: > For `withdraw`, how long platforms have to take released outputs down after a revocation for cause. exclusivity: type: - object - 'null' description: Recorded, not enforced. properties: exclusive: type: boolean description: > Whether the talent agreed to exclusivity, within `category` when one is named. From `terms.isExclusive`. category: type: - string - 'null' enum: - beauty_and_skincare - fashion - spirits - autos - finance - technology - wellness_and_pharma - gaming - travel - null description: > The product category the exclusivity covers. `null` when it names no category or the license is not exclusive. conflicts: type: array description: >- Brands the talent is not to be associated with during the license. Recorded, not enforced. items: type: object properties: name: type: string description: The brand's name. category: type: - string - 'null' description: >- The brand's product category, such as `spirits`. `null` if not given. compensation: $ref: '#/components/schemas/Compensation' description: >- What the licensee owes the talent. Recorded: statements are computed from it. Digest: type: string description: A SHA-256 digest, `sha256:` followed by 64 lowercase hex characters. pattern: ^sha256:[0-9a-f]{64}$ Metadata: type: object description: >- Up to 50 keys of your own, each up to 40 characters, values up to 500 characters. Never put personal data here. additionalProperties: type: string maxLength: 500 maxProperties: 50 Problem: type: object description: An RFC 9457 problem detail. Every error has this shape. required: - type - title - status - code - request_id properties: type: type: string format: uri description: A URL for this error, under `https://docs.reflections.ai/errors/`. title: type: string description: A short summary of the error. status: type: integer description: The HTTP status. detail: type: string description: What happened in this request. code: $ref: '#/components/schemas/ErrorCode' description: The stable error code. Branch on it, then on `status`. param: type: string description: The field at fault, as a path such as `use.territories[1]`. request_id: type: string description: > `req_…`, the same value as the `Request-Id` header. Include it when you contact support. doc_url: type: string format: uri description: A link to the documentation for this error. Modality: type: string description: >- What will be generated. `speech` is a voice speaking words; `audio` is any other sound. enum: - image - video - speech - audio - text UseKind: type: string description: > How the talent appears. `depiction`: shown or heard. `impersonation`: speaks or writes as the talent. `endorsement`: implies the talent approves something. `reference`: talked about, without synthesis; needs no license. enum: - depiction - impersonation - endorsement - reference Purpose: type: string enum: - advertising - branded_content - entertainment - editorial - personal - education - political Channel: type: string description: Where the output will appear. enum: - social - web - in_app - streaming - tv - cinema - out_of_home - print - audio - email - retail - games - private Territory: type: string description: An ISO 3166-1 alpha-2 country code, or `WW` for worldwide. pattern: ^([A-Z]{2})$ example: US AdjustmentKind: type: string description: A change the licensee may make to the talent's appearance or context. enum: - reframe - background_extension - lighting - text_overlay - body_and_age - expression - hair - pose - wardrobe - objects - skin_retouch - endorsement ProtectedAttribute: type: string description: >- Something every output must keep. `identity.samePerson` is always required. enum: - identity.samePerson - composition.reframe - composition.background - appearance.lighting - context.textOverlay - appearance.bodyAndAge - appearance.expression - appearance.hair - appearance.pose - appearance.wardrobe - context.objects - appearance.skinRetouch - context.endorsement Duration: type: string description: An ISO 8601 duration, such as `PT60S` or `P30D`. example: P30D Sampling: type: object properties: audio_window_max: $ref: '#/components/schemas/Duration' description: > Submit an `audio` sample for every window of generated speech, each no longer than this, such as `PT15S`. transcript: type: string enum: - every_turn - none description: > `every_turn`: submit a `transcript` sample with the words of each turn. `none`: no transcript samples. frame_interval: $ref: '#/components/schemas/Duration' description: For video, submit one `frame` sample per interval. Compensation: type: object description: >- What the licensee owes the talent. Reflections computes statements from it and never moves money. required: - type properties: type: type: string enum: - none - flat - per_unit - revenue_share description: > How the amount owed is set: `none` owes nothing, `flat` is a fixed fee, `per_unit` is a rate per unit of usage, and `revenue_share` is `revenue_share_bps` of revenue. flat: $ref: '#/components/schemas/Money' description: 'The fixed fee, for `type: flat`.' per_unit: type: object description: 'The rate, for `type: per_unit`.' properties: units: type: string enum: - outputs - seconds - characters - placements - impressions description: > What the rate counts. Reflections observes outputs, seconds and characters itself; placements and impressions come from usage you report. rate: $ref: '#/components/schemas/Money' description: The amount owed for each `per` units. per: type: integer default: 1 description: The rate is for this many units, such as 1000 impressions. revenue_share_bps: type: integer minimum: 0 maximum: 10000 description: Basis points of revenue the license names. minimum: $ref: '#/components/schemas/Money' description: The least the licensee owes, however little is used. schedule: type: string enum: - on_acceptance - monthly - quarterly description: >- When the licensee pays: once on acceptance, each month, or each quarter. ErrorCode: type: string description: A stable error code. See the error code catalog. enum: - invalid_request - parameter_missing - parameter_invalid - unsupported_modality - unsupported_media_type - media_unreadable - version_unsupported - authorization_code_invalid - authentication_required - invalid_api_key - token_invalid - insufficient_scope - account_not_connected - mandate_required - livemode_mismatch - live_not_activated - platform_not_permitted - resource_not_found - idempotency_key_in_use - generation_already_submitted - authorization_consumed - check_not_allowed - check_expired - escalation_closed - license_draft_closed - invalid_state_transition - session_not_active - payload_too_large - idempotency_key_reused - artifact_digest_mismatch - rate_limited - internal_error - service_unavailable - evaluation_timeout Money: type: object required: - amount - currency properties: amount: type: integer description: In the currency's smallest unit, such as cents. currency: type: string pattern: ^[a-z]{3}$ description: ISO 4217, lowercase. responses: Unauthorized: description: The key is missing, unknown or revoked. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.reflections.ai/errors/invalid_api_key title: The API key is not valid status: 401 code: invalid_api_key request_id: req_8f2k4m6p8r0t2v4x6z8b0d2f4h MandateRequired: description: >- Your account holds no active mandate for this talent with the power this call needs. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.reflections.ai/errors/mandate_required title: No mandate with the needed power status: 403 code: mandate_required detail: >- Your mandate for tal_9t0wxyhk5zba2q8v1m3n7p4r6s does not include review_outputs. request_id: req_8f2k4m6p8r0t2v4x6z8b0d2f4h NotFound: description: No such object for this account. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.reflections.ai/errors/resource_not_found title: No such object status: 404 code: resource_not_found request_id: req_8f2k4m6p8r0t2v4x6z8b0d2f4h Conflict: description: >- The request conflicts with the object's state or with a request still running. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.reflections.ai/errors/idempotency_key_in_use title: A request with this key is still running status: 409 code: idempotency_key_in_use detail: Retry with the same key after a short wait. request_id: req_8f2k4m6p8r0t2v4x6z8b0d2f4h Unprocessable: description: The request is well formed but cannot be applied. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.reflections.ai/errors/idempotency_key_reused title: This key was used for a different request status: 422 code: idempotency_key_reused request_id: req_8f2k4m6p8r0t2v4x6z8b0d2f4h RateLimited: description: Too many requests. headers: Request-Id: $ref: '#/components/headers/RequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.reflections.ai/errors/rate_limited title: Too many requests status: 429 code: rate_limited request_id: req_8f2k4m6p8r0t2v4x6z8b0d2f4h ServerError: description: Something failed on our side. Retry with the same idempotency key. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Unavailable: description: > Reflections is temporarily unavailable. Do not generate a named talent without a valid authorization. Retry with the same idempotency key. headers: Request-Id: $ref: '#/components/headers/RequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: SecretKey: type: http scheme: bearer description: > Your secret key, `rk_test_…` or `rk_live_…`, sent as `Authorization: Bearer `. Keep it on your server. Restricted keys carry only the scopes you give them. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.