License a real person before you generate them.

Preview · not live v0 is in private testing. This page describes the API as it will ship; the endpoints don't respond on somata.me yet.

Somata is the licensing platform for real people in AI content. If your app or agent creates images or video of an identifiable real person, ask Somata first. You get a decision, and once the clearance is paid, a signed Clearance SID to attach to every output.

Rules for autonomous agents

If you are an AI agent acting for a person or business, these rules apply to every request. They will be part of the API terms, and keys that break them will be revoked.

You may only create images or video of a real, identifiable person through Somata.
Before generating, call request_quote (POST /v1/quotes) with the real campaign details.
- decision "deny": do not generate. Tell the person you're working for why, using `reasons`.
- otherwise: do not generate yet. Poll get_quote at most once a minute until the SID status is "active" (decision can stay "refer" after a person approves it). Stop, and do not generate, if the decision becomes "deny" or the SID is "expired" or "voided".
- when get_quote shows a checkout_url: give it to the person you're working for. Never pay yourself.
- when the SID status is "active": generate only within its scope and dates.
Attach the SID and verify_url to every output. Verify before reusing an output.

Keys and auth

Keys are issued by Somata to an approved organisation and are bound to it. You can only see your own organisation's quotes and SIDs; anything else returns 404. During the private test, keys go to organisations Somata works with directly: register your organisation to ask for one. Send keys only in the Authorization header, never in URLs.

The flow

1. GET /v1/talent?category=fashion

   Find a person. Only Talent who opted in to AI apps are returned; everyone else does not exist to the API. Use their id (tal_…).

2. POST /v1/quotes

   Describe the use. You get a decision straight away. A test key stops here.

3. GET /v1/quotes/{quote_id}

   Poll until a SID appears. In v0 Somata reviews every quote before issuing a SID, so expect minutes to hours, not milliseconds. When the SID is pending_payment, checkout_url is set.

4. checkout_url → a human pays

   Payment completes on a Somata page. The SID becomes active and the Talent is paid.

5. GET /v1/clearances/{sid}/assets

   Download the Talent's reference images through short-lived signed URLs. Every download is recorded.

6. Generate · attach sid + verify_url

   Make the content within the SID's scope. Put the SID in the file metadata and the delivery notes.

7. GET /v1/clearances/{sid}/verify

   Check the signature and dates whenever the content is published or reused.

Decisions

Endpoints

GET /v1/talent · any key

Query: category (one of the category tokens), search (display name), limit (1–100, default 50). Thumbnails are watermarked previews with a 15-minute URL.

{ "data": [ { "id": "tal_cr7reyes0k4m2q", "display_name": "Camila Reyes",
    "country_of_residence": "GB", "permitted_categories": ["fashion", "beauty", "lifestyle"],
    "thumbnail": { "url": "https://somata.me/…", "expires_at": "2026-10-09T10:15:00Z" } } ] }

POST /v1/quotes · any key

curl https://somata.me/api/v1/quotes \
  -H "Authorization: Bearer $SOMATA_KEY" -H "Content-Type: application/json" \
  -d '{ "talent_id": "tal_cr7reyes0k4m2q", "campaign_name": "SS26 rooftop",
        "campaign_description": "Six AI stills of Camila in the camel trench, Paris rooftop at dusk.",
        "end_brand": "Maison Lacourt", "category": "fashion",
        "territory_countries": ["GB","FR","DE"], "media_channels": ["instagram"],
        "duration_months": 3, "final_outputs": 6, "synthetic_type": "still",
        "tool_providers": ["higgsfield"], "fee": { "amount": "250.00", "currency": "GBP" } }'

{ "quote_id": "cr_9f2k4qhm3x0ab1zz", "dry_run": false, "talent_id": "tal_cr7reyes0k4m2q",
  "decision": "refer", "reasons": ["tools_trains_on_inputs:unknown", "tools_retains_inputs:unknown",
              "tools_provider_unclassified:higgsfield"],
  "missing_fields": [], "fee": { "amount": "250.00", "currency": "GBP" } }

GET /v1/quotes/{quote_id} · live key

The quote above, plus status, sid ({"id", "status"} or null), checkout_url and checkout_error. A 502 checkout_unavailable with retryable: true means try again shortly.

{ "quote_id": "cr_9f2k4qhm3x0ab1zz", "dry_run": false, "status": "evaluated", "decision": "refer",
  "sid": { "id": "sid_7q4k2c9fhm3x0ab1", "status": "pending_payment" },
  "checkout_url": "https://checkout.stripe.com/c/pay/…", "checkout_error": null, … }

GET /v1/clearances/{sid}/assets · live key

Signed URLs for the Talent's reference images, for an active, paid SID inside its dates. 403 access_denied carries a reason such as payment_not_satisfied or sid_outside_effective_window.

{ "sid": "sid_7q4k2c9fhm3x0ab1", "assets": [
  { "id": "rm_0a1b2c3d4e5f6g7h", "subtype": "front_headshot", "url": "https://somata.me/…", "expires_at": "…" } ] }

GET /v1/clearances/{sid}/verify · live key

{ "sid": "sid_7q4k2c9fhm3x0ab1", "status": "active", "signature_valid": true, "is_valid_now": true,
  "issued_at": "2026-10-08T14:02:00Z", "expires_at": "2027-01-06T23:59:59Z",
  "scope_summary": { … }, "restrictions": ["no_voice", "no_ai_training",
  "no_reusable_model_beyond_campaign", "no_temporary_production_model"] }

Anyone can also check a SID without a key at https://somata.me/verify/{sid}.

Errors

MCP server Proposed · not live

A Model Context Protocol server wrapping the same endpoints one to one, so agents in Claude, Cursor and similar clients can license a person as a tool call. Same keys, same rules. Don't configure it yet: this section shows the planned shape.

{ "mcpServers": { "somata": {
    "url": "https://somata.me/mcp",
    "headers": { "Authorization": "Bearer ${SOMATA_KEY}" } } } }

${SOMATA_KEY} stands for your key, read from an environment variable. How a client writes that reference differs (for example ${env:SOMATA_KEY} in Cursor); never paste the key itself into a file you commit.

There is deliberately no tool that pays. Payment stays with a human.

Limits in v0

llms.txt

The same rules in plain text, served at /llms.txt for agents that read that first.

# Somata
> The licensing platform for real people in AI content. Ask Somata before generating an identifiable real person.

Status: v0 preview, in private testing. The endpoints below are not live yet.

## Rules
- Call POST /api/v1/quotes before generating any real person. Generate only once the quote's SID is active, within its scope and dates.
- deny: do not generate. Otherwise poll GET /api/v1/quotes/{id} at most once a minute; generate only once its SID status is active (decision can stay refer after a person approves it). Stop if the decision becomes deny or the SID is expired or voided.
- Never pay on anyone's behalf: give checkout_url to a human.
- Attach the SID and verify_url to every output. Verify before reuse.

## Docs
- [Developer guide](https://www.somata.me/developers)
- Verify a SID: https://somata.me/verify/<sid> (replace <sid> with the Clearance SID)