Documentation

Claim a handle

1. Sign in with a Google or Microsoft account, or an email address. 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 (* or an ISO 3166-1 country code), and an optional note. Grants are evaluated in the order you publish them; the first match decides. Publish the specific grant before the general one.

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 a reason of no_matching_grant: the holder has said nothing about that use, which is different from permitting it.

Endpoints

• GET /v1/voice/@handle resolves 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/ serves 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 resolves a 16-bit audio payload to its record.
• GET /v1/records/<sha256> looks up an issuance by the hash of the audio file.
• GET /healthz is liveness.

Metered endpoints (POST /v1/audio, POST /v1/jobs, GET /v1/jobs/:id) require an active plan and either a same-origin session or an Authorization: Bearer API key from the console with the matching scope. Audio uploads must be 16-bit PCM WAV. Every request that changes state also needs an Origin that matches this site, or an API key, and an Idempotency-Key header.

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 phrase aloud in the console and a speaker model matched that reading to the sample enrolled on the account. None of these levels states who a person is.

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 the level that was current when it was generated.

The voice library

A speaker with a verified handle can list a voice: enrol a reference sample, set the listing terms (which use classes, which territories, and the rate per minute or the plan it is included in), and publish a marked demo. Speakers manage listings at /v1/listings; licensees search at GET /v1/library (filters language, gender, age, style, tag, access, q), hear the 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, the approval also creates a licence: the licensee may then synthesize with that voice in the Studio or 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. Speakers are paid their share on the schedule shown in the console.

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.

A customer may also connect its own account with a third-party speech provider. Speech generated that way goes to that provider under the customer's own agreement with it, is still watermarked and fingerprinted on the way back, and is still subject to the listing terms.

Watermark and fingerprint

Every file the Studio produces carries an inaudible watermark and a fingerprint registered to the licence it was made under. A detected watermark shows that the audio passed through this service under some licence; it does not identify a speaker, prove who requested the audio, or prove that the words spoken are true. A fingerprint match narrows the audio to one issuance under one licence. Use the public verification page to check a file.

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.