Documentation

Claim a handle

1. Sign in with a Google account. Claiming a handle is free and needs no subscription.
2. Choose a handle of 3–30 characters, using lowercase letters, digits and single hyphens.
3. Publish the record so it resolves at your-handle.speech.name. A private record is stored but never resolved for anyone else.

Publish grants

A grant is one statement about one kind of use. It carries a use class (commercial, editorial, parody_satire, research, personal), a subject (anyone, a named handle, or a domain), a decision (permit, deny, require_agreement), a territory (worldwide or an explicit list of ISO 3166-1 alpha-2 codes), an optional start and end, and an optional note.

Grants are an ordered list. Evaluation walks them in order and the first one that matches all four of use class, subject, territory and term wins. Put your specific exceptions above your general rule.

Resolve a record

Resolution is a public GET and needs no API key. The response carries the decision, the grant that produced it, the reason it matched, the verification level of the record, and the policy version at the time of the check — keep it as evidence of the diligence you performed.

When nothing matches, the decision is require_agreement with reason no_grants or no_matching_grant. The registry never returns an implied yes, and an empty record is not permission.

A caller that cannot state a territory matches only worldwide grants. Narrowing an unknown location into a specific list would be a guess in the caller's favour, so the registry refuses to make it.

Endpoints

• GET /v1/voice/@handle — resolve a record. Query parameters: use (default commercial), territory (ISO 3166-1 alpha-2), licensee (anyone, handle:name or domain:example.com). Public, no key required.
• GET https://<handle>.speech.name/ — the same record as a human-readable page. Each handle is served on its own hostname; there is no path form.
• GET /v1/identity/:messageBits — resolve a 16-bit audio payload to its record, for the deferred watermarking add-on.
• GET /healthz — liveness.

Metered endpoints for the watermarking add-on (POST /v1/audio, POST /v1/jobs, GET /v1/jobs/:id) require an active entitlement and either a same-origin session or an Authorization: Bearer sn_gcp_… API key with the matching scope. Audio uploads must be 16-bit PCM WAV.

The voice library uses the same authentication. Speakers manage listings at /v1/listings; licensees search at GET /v1/library (filters language, gender, age, style, tag, access, q), hear a marked demo at GET /v1/library/:id/demo, and ask for a voice at POST /v1/library/:id/requests. A speaker's approval writes a permit grant for the licensee's handle onto the speaker's record, so GET /v1/voice/@handle remains the one place a consumer resolves permission. When the listing carries templated terms (a rate per minute, a term and a retention class), the approval also creates a licence: the licensee may then synthesize with that voice through POST /v1/jobs, every second produced is metered, and GET /v1/statements?period=YYYY-MM returns the month's earned and owed statements with the platform share applied. GET /v1/licenses lists licences held and granted; either party may end one. A speaker proves a cloned voice is theirs with a reading challenge (POST /v1/voices/:id/verification, then the recording); a pass adds voice_verified to the record beside the domain level, and every resolution response carries it as voiceVerification.

Verification levels

Every record and every response states its level. self_asserted means someone registered this handle and we have verified nothing about them. domain_verified means the holder proved control of a named domain; the claim binds to that domain, not to a person. Separately, voice_verified means the holder read a challenge sentence in their own voice and it matched the sample behind one of their listed voices: it proves the voice belongs to the holder, not who the holder is. No level asserts that the holder has authority to grant what the record grants. See the handle and dispute policy.

To prove a domain, name it in your record and publish either proof:

• a DNS TXT record at _speech-name.<domain> whose value is speech-name-verification=<token>; or
• a file at https://<domain>/.well-known/speech-name containing the token on its own line.

DNS is checked first, because a TXT record at that name needs authority over the zone, whereas serving one file can be delegated. The token is derived from your account and the domain together, so a token read out of someone else's DNS proves nothing for your handle, and a token for one domain proves nothing for another.

Checks run when you ask for one. A check that finds no matching proof downgrades the record to self_asserted at once, so a domain you stop controlling does not keep asserting a proof we can no longer see; public resolution responses carry max-age=60, so a downgrade can take up to a minute to be visible through a shared cache. Every response carries verifiedAt, checkedAt and the method. verifiedAt is when the proof first succeeded and checkedAt is when we last looked, so the gap between them is how stale the evidence is — judge it yourself. Checks run when a holder asks for one; we do not publish a re-check cadence we have not configured.

Watermarking

Audio watermarking is a metered add-on and is currently deferred. It is not part of the free registry, and no part of the registry depends on it.

Export and deletion

To access, export, correct or delete your account and record data, contact legal@gridheap.com from the address on the account. Do not send cookies, tokens, or authorization headers. We verify the requester before acting.