Voice and API guide
Create a voice and generate speech
Generate speech in the Playground within minutes using a built-in voice, then clone your own voice and call the API. Every step names the exact button you will see.
Start here
Choose a voice path
The shortest path depends on whether the voice already exists. You do not need to clone anything to make your first request.
Your invitation determines which products your workspace can use. Text to Speech opens Voices, Playground, Integrations, and Usage & credits, subject to your workspace role. These settings apply to the website, API, and CLI; switching clients does not grant additional access.
Use a built-in voice
Use a ready voice — rows marked Built-in in the Voices list. Open the Playground, pick one, and generate immediately.
Clone an authorized speaker
Upload clean recordings or record the speaker in the Dashboard, save exact transcripts, confirm permission, then clone it in the Playground.
Workspace Owners, Admins, and Builders can create, import, edit, clone, configure, and delete workspace voices, including voices created by teammates. Everyone, including Reviewers, can browse voices, use Auto Tag, and generate speech in the Playground. Only clone a voice when you have the speaker’s permission; the Dashboard requires this confirmation before creating anything.
Navigation
Find the Voices page
Voices and the Playground live in the Text to Speech product area.
Sign in to the Dashboard
Open the login page and sign in. If you were invited by a teammate, use the account attached to that invitation.
Switch to the right product
In the top-left corner of the Dashboard, select the Aniwaffle product switcher and choose Text to Speech. The sidebar changes to that product’s pages.
Open Voices
Select Voices in the sidebar, or go directly to /app/voices.
The list shows each voice once, with its clone status, recording and transcript counts, and stable voice id. Models are selected where the voice is used. Built-in voices show Built-in in the Updated column and are ready without any setup.
Voice model
One voice, one cloned copy
Aniwaffle separates the identity of a voice from the cloned copy that produces audio.
| Object | What it contains | Why it matters |
|---|---|---|
| Voice | The stable workspace identity and voice_id. | It exists as soon as you create the voice, before cloning. |
| Source samples | Authorized recordings, language, and exact transcripts. | These let the app create or update the cloned voice. |
| Cloned voice | The Waffle copy created from the recordings. | All Waffle models reuse this copy; switching models does not clone again. |
| Model | The Waffle model selected in the Playground. | Its emotion tags apply to that request. |
| API default | The model used with the canonical voice_id. | Set it on the voice detail page. |
Dashboard workflow
Clone a voice
This is the complete path from an authorized recording to a voice you can select in the Playground and in API requests.
Open the Create voice dialog
The Create voice button is at the top right of the Voices page. Choose Upload or Record.
Upload or record the speaker
Upload accepts clean audio or video of one speaker — no music, no background voices. Record shows a ~10-second script in 中文, 日本語, or English, and saves that script as the transcript automatically.
Name the voice and verify the sample
Enter a Name that identifies the speaker and purpose. For uploads, the Verify the sample block appears: listen once, select the spoken language, and type the exact words into the transcript field (placeholder “Exact words spoken”).
Confirm speaker permission
Tick “I have the speaker's permission to use and clone this voice”. The Create button stays disabled until you do.
Select Create voice
The app saves the voice and opens its detail page. Its identity already exists before cloning. Finish any missing transcripts on the Samples tab.
Use the voice
In Playground, choose the voice, then select Clone to Waffle if it has not been cloned yet. You can also use Clone now on the voice detail page.
Test before relying on it
Once the cloned voice is ready, select Test in playground, choose a model, generate representative text, and listen. Switching models reuses the cloned voice and does not clone again.
Input quality
Recordings and transcripts
A clone can only reproduce what the recordings make clear. Clean, representative input matters more than volume.
Good source audio
- One speaker, recorded clearly and at a consistent distance.
- No music, overlapping speech, strong room echo, or background noise.
- The language, accent, tone, and delivery you want the generated voice to keep.
- Several clean clips beat many inconsistent ones.
Complete transcripts
- Choose the language actually spoken in each sample.
- Enter every spoken word exactly, including repetitions.
- Replay the sample before saving the transcript.
- Every recording needs a transcript before cloning is allowed.
When you upload several files at once, the dialog warns: “This transcript is saved to the first recording. Add the remaining transcripts on the voice page before cloning.” Open the voice’s Samples tab — the counter (for example 3/4 transcripts) shows what is missing, and each recording row has an Edit button for its language and transcript.
You can select Add recordings on the voice page at any time. New samples are used on the next clone, so the voice shows Update available until you update it (see below).
Cloned voice
Manage a cloned voice, defaults, and failures
The voice detail page shows the cloned copy and its status. Choose the synthesis model where you use the voice.
Dashboard acceptance
Test the voice with real content
Use the Playground before code so audio-quality problems are separated from integration problems.
Open the voice → Test in playground
The button in the voice header carries the voice into the Playground. You can also open the Playground directly and pick any ready voice in Settings → Voice.
Use representative text
Test names, numbers, abbreviations, domain vocabulary, mixed-language phrases, punctuation, questions, and the emotional range your product needs.
Add emotion tags where supported
On tag-capable models, type
[to search tags inline, or use Auto Tag to let the editor suggest them. See Emotion tags for the full list.Tune output settings
Under Settings, choose the Output format (PCM, AAC, or Opus) and an optional Speed override, then select Generate speech.
Review History
Successful generations are saved to the voice’s History → Generations tab with model, tags, format, and playable audio.
API quickstart
Generate your first audio file
A one-shot HTTP request is the shortest path from complete text to a playable audio file.
The default API endpoint and the example below use the United States. Standard Waffle requests from either region use the same throughput pool. Mono Waffle requests with realtime: true use the Japan latency pool and require the Japan endpoint. Stereo requests always use the shared throughput pool; channels: 2 with realtime: true is rejected before synthesis or billing. Realtime and standard requests share the 20,000-character limit per request, including voice tags and all text events. Split longer text into separate requests; over-limit input is rejected before its synthesis. Audio already generated by earlier WebSocket flushes is billed normally. Synthesis time and queueing still depend on the request and current load.
For direct TTS calls, use https://jp.aniwaffle.com/v1/tts for HTTP or wss://jp.aniwaffle.com/v1/tts/stream for WebSocket. The hostname selects the region; the TTS request body has no region field. See all regional endpoints.
Open Integrations in the Dashboard
Name and create the key
Enter a descriptive Label such as
checkout-voice-prodand select Create key.Copy the key immediately
A banner shows the full key exactly once: “Key created. Copy it now, it won’t be shown again.” The key starts with
awp_. Only a hash is stored, so a lost key must be replaced, not recovered.Store it server-side
Put the key in your backend’s secret manager. Never ship it in browser or mobile code — browsers use short-lived tokens instead. The Issued keys table shows each key’s prefix, status, and last-used time, and a Revoke button that disables it immediately.
Get a voice id
Copy it from the voice’s page in the Dashboard, or call
GET /v1/voiceswith your key and pick anidfrom the response.Send complete text
POST
/v1/ttswithtext,voice_id, and anoutput_formatthe voice supports. The response body is the audio bytes.
curl --request POST https://aniwaffle.com/v1/tts \
--header 'Authorization: Bearer awp_your_key_here' \
--header 'Content-Type: application/json' \
--data '{
"text": "Hello from Narya.",
"voice_id": "<id from GET /v1/voices>",
"output_format": "aac_44100_128"
}' \
--output speech.aacRealtime output
Stream text and play audio incrementally
Use WebSocket streaming when text arrives incrementally or playback must start before the full text is known. Complete prompts are simpler over HTTP.
Connect
Open
wss://…/v1/tts/streamwith your workspace key as a bearer token. To keep the permanent key away from short-lived processes, your backend can instead callPOST /v1/tts/stream-tokensand pass the returned 2-minute token.Start a generation
Send the start event with the voice, format, and request options documented in the event reference.
Append text in order
Send text chunks as they become available. Signal with stop when no more text will arrive.
Play audio in order
Decode each audio chunk using the delivered format. Do not reorder chunks, and handle terminal and error events explicitly.
Expressive speech
Add emotion, delivery, and human sounds
Waffle voices understand a fixed set of tags. Use them to change how a line is spoken, or to insert a sound such as a laugh or a sigh.
| Type | Tags | What it does |
|---|---|---|
| Emotion | happy, sad, angry, afraid, disgusted, surprised, embarrassed, aroused | Colors the tone of the text it wraps. |
| Delivery | whispering, shouting | Changes how loudly the text it wraps is spoken. |
| Human sound | sighing, gasping, panting, sniffing, laughing, groaning, crying, coughing, licking | Inserts a single sound at that point. |
Tag text in the Playground
Type
[or<in the editor to search tags, or open the Tags menu. Select text first to wrap it in an emotion or delivery tag; otherwise the tag covers the rest of the paragraph. Click any inserted tag to change it.Let Auto Tag suggest tags
Select Auto Tag to have the editor add tags that fit your text. Every workspace member with Text to Speech access can use it. Review the result and listen before saving it into your content.
Send tags through the API
Wrap exact spans in
text, such as<happy>Hello.</happy>or<happy><whispering>Hello.</whispering></happy>, and use[laughing]for a single sound.
{
"text": "<happy>I am so glad you came.</happy> [laughing] <whispering>Let me tell you a secret.</whispering>",
"voice_id": "<id from GET /v1/voices>",
"output_format": "pcm_24000"
}Put emotion outside delivery when you nest them. Unknown tags, unbalanced tags, and wrong nesting return invalid_request. To speak a literal [, <, or \, put a backslash in front of it. Tag effects vary by voice, so listen to representative lines before you ship.
Common failures
Troubleshooting
| Symptom | Why it happens | What to do |
|---|---|---|
| The Create voice button is missing | Voice management requires a workspace Owner, Admin, or Builder. | Ask an Owner or Admin to assign you the Builder role. |
| Clone is disabled | The permission checkbox is unconfirmed, a recording is missing its transcript, or there are no recordings. | Open the voice’s Samples tab: complete every transcript (the counter must read n/n) and confirm permission in Settings. |
| The voice has not been cloned | The voice has recordings but no cloned copy yet. | Use Clone now on the voice detail page, or Clone to Waffle in the Playground. |
| The clone shows Failed | The clone attempt could not complete. | Open History, read the failure summary, fix the cause, then retry the clone. |
| The voice shows Update available | Recordings changed since the voice was cloned. | Select Update on the voice detail page. |
| Emotion tags have no effect | The tag is not in the model's vocabulary, or its effect varies with the voice. | Check the emotion tag guide and test representative text. |
| The API cannot find the voice | The voice id belongs to another workspace, or the voice has not finished cloning. | Copy the id again from the voice page or GET /v1/voices with the same key you use for synthesis. |
Before launch
Production checklist
- Keep documented speaker permission and retain the authorized source recordings.
- Verify every managed recording has the correct language and exact transcript.
- Choose and test a ready default model with representative production text.
- Keep workspace API keys on the backend.
- Use a voice_id returned for the same workspace.
- Set explicit timeouts and handle service and credit errors.
- Respect the selected output format when decoding or storing audio.
- Use streaming only when its latency benefit justifies the longer lifecycle.