AniwaffleDocsHomeContact our team
Developer preview. Public API access is not open yet. Contact our team to discuss integration.

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.

Who can do what

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.

  1. 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.

  2. 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.

  3. 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.

ObjectWhat it containsWhy it matters
VoiceThe stable workspace identity and voice_id.It exists as soon as you create the voice, before cloning.
Source samplesAuthorized recordings, language, and exact transcripts.These let the app create or update the cloned voice.
Cloned voiceThe Waffle copy created from the recordings.All Waffle models reuse this copy; switching models does not clone again.
ModelThe Waffle model selected in the Playground.Its emotion tags apply to that request.
API defaultThe 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.

  1. Open the Create voice dialog

    The Create voice button is at the top right of the Voices page. Choose Upload or Record.

  2. 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.

  3. 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”).

  4. Confirm speaker permission

    Tick “I have the speaker's permission to use and clone this voice”. The Create button stays disabled until you do.

  5. 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.

  6. 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.

  7. 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.

Clone nowCreates the cloned voice from the authorized recordings.
Default for requests that only name this voiceUse Default model to select the model for callers using the canonical voice_id.
EnabledEnables or disables the cloned voice.
Emotion tagsThe model picker shows the selected model's tag support. See Emotion tags.
Clone statesReady, Cloning, Failed, Blocked, or Update available.
UpdateAfter adding recordings, use the Update action to rebuild the clone from the sample set. Existing ready audio remains usable while an update is available.
HistoryInspect clone attempts and their failure summaries. Use Try again after fixing the cause. A failed clone does not erase an existing usable copy.

Dashboard acceptance

Test the voice with real content

Use the Playground before code so audio-quality problems are separated from integration problems.

  1. 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.

  2. Use representative text

    Test names, numbers, abbreviations, domain vocabulary, mixed-language phrases, punctuation, questions, and the emotional range your product needs.

  3. 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.

  4. Tune output settings

    Under Settings, choose the Output format (PCM, AAC, or Opus) and an optional Speed override, then select Generate speech.

  5. 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.

Choose the endpoint for your request

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.

  1. Open Integrations in the Dashboard

    Sign in at /login, then select Integrations in the sidebar (under the Config group), or go directly to /app/keys. The page is titled API keys. Workspace Owners, Admins, and Builders can access it — other roles get “API key management requires an organization Owner, Admin, or Builder.”

  2. Name and create the key

    Enter a descriptive Label such as checkout-voice-prod and select Create key.

  3. 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.

  4. 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.

  1. Get a voice id

    Copy it from the voice’s page in the Dashboard, or call GET /v1/voices with your key and pick an id from the response.

  2. Send complete text

    POST /v1/tts with text, voice_id, and an output_format the voice supports. The response body is the audio bytes.

Terminal
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.aac
See request and response fields

Realtime 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.

  1. Connect

    Open wss://…/v1/tts/stream with your workspace key as a bearer token. To keep the permanent key away from short-lived processes, your backend can instead call POST /v1/tts/stream-tokens and pass the returned 2-minute token.

  2. Start a generation

    Send the start event with the voice, format, and request options documented in the event reference.

  3. Append text in order

    Send text chunks as they become available. Signal with stop when no more text will arrive.

  4. Play audio in order

    Decode each audio chunk using the delivered format. Do not reorder chunks, and handle terminal and error events explicitly.

Open the WebSocket event reference

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.

TypeTagsWhat it does
Emotionhappy, sad, angry, afraid, disgusted, surprised, embarrassed, arousedColors the tone of the text it wraps.
Deliverywhispering, shoutingChanges how loudly the text it wraps is spoken.
Human soundsighing, gasping, panting, sniffing, laughing, groaning, crying, coughing, lickingInserts a single sound at that point.
  1. 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.

  2. 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.

  3. 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.

Request body
{
  "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"
}
Rules to keep in mind

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.

See every tag rule and the streaming format

Common failures

Troubleshooting

SymptomWhy it happensWhat to do
The Create voice button is missingVoice management requires a workspace Owner, Admin, or Builder.Ask an Owner or Admin to assign you the Builder role.
Clone is disabledThe 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 clonedThe 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 FailedThe clone attempt could not complete.Open History, read the failure summary, fix the cause, then retry the clone.
The voice shows Update availableRecordings changed since the voice was cloned.Select Update on the voice detail page.
Emotion tags have no effectThe 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 voiceThe 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.

Contact our team

Tell us about your character and what you’d like to build.