Generate Audio
generate_audioGenerate spoken audio from text: narration, a voiceover, a read-aloud script, or a multi-voice dialogue. Pass text (up to 3000 chars) — the words to be spoken. To speak in one of YOUR saved voices, pass voice with the voice NAME (or id): users speak plain language and never know ids, so resolve the name yourself (the voice tool, action "list", shows every saved voice) and never ask the user for an id. Reference voices, trained clones and preset voices are all routed correctly by kind. To match a voice instantly from a clip instead, pass reference_audio_url (a short clip) or up to 3 reference_audio_urls and address them as @Audio1, @Audio2, @Audio3 in the text for dialogue. Alternatively pass image_url to voice a scene from a picture (cannot combine with reference audio). Pass delivery to direct HOW it should sound in plain English — the voice (gender, age, accent, emotion, tone, speed), the mic and room, and any background sound or music — e.g. "soft, warm and a little flirty, unhurried, close clear mic, no echo"; it works with any saved voice (trained clones included), with clips, or with no voice. To fix the length of a sentence, put a time window in front of it inside text, e.g. [5.5s:8.0s] before the sentence. Optional speech_rate (-50..100), pitch (-12..12), loudness (-50..100). Before writing a delivery line, a multi-voice scene or timed lines, call load_workflow_playbook with id playbook/audio-prompting: it holds the prompt order, the voice description fields, the @Audio tagging rules, timing control and the limits. Returns a playable audio_url, duration_seconds, and generation_id (also saved to your library). A longer line (roughly 20 seconds of speech or more) may instead return status "rendering" with a request_id: the take is still being made and is not lost — call get_audio_status with that request_id every 15 seconds until audio_url comes back, and never re-run the same line. To find an earlier take, call list_my_audio.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The words to speak / narrate / perform. Max 3000 chars. For dialogue, address voices as @Audio1, @Audio2, @Audio3. Optional per-sentence timing: put [start:end] seconds in front of a sentence, e.g. [5.5s:8.0s]. | |
| pitch | No | Optional. Pitch, -12 to 12. 0 is normal. | |
| voice | No | Optional. A saved voice — pass its NAME (or id); it is resolved and routed by kind automatically. Omit for a natural default voice. | |
| format | No | Optional output format. Default mp3. | |
| delivery | No | Optional. How it should SOUND, in plain English: the voice (gender, age, accent, emotion, tone, speed), mic and room, background sound or music — e.g. "young woman, warm Latin accent, soft, a little flirty, unhurried, clear close mic, no echo". Under 400 chars. Not the words themselves. | |
| loudness | No | Optional. Loudness, -50 (quieter) to 100 (louder). 0 is normal. | |
| image_url | No | Optional. Voice a scene from a picture. Cannot be combined with reference audio. | |
| timestamps | No | Optional. true returns sentences: [{start, end, text, words: [{start, end, text}]}] in seconds. For a two-voice scene the on-camera person's lines become speak_spans for sync3_lip_sync_video: when you wrote a time window like [3.6s:6.6s] in front of each line, use THOSE windows for her lines (the provider keeps them and they are exact); use sentences and words only for lines you did not time, and check every span holds only her words, because the provider can glue short lines into one sentence. | |
| speech_rate | No | Optional. Speaking speed, -50 (slower) to 100 (faster). 0 is normal. | |
| reference_audio_url | No | Optional. A short clip URL to instantly match that voice. | |
| reference_audio_urls | No | Optional. Up to 3 reference clip URLs for multi-voice dialogue. |