curl --request POST \
--url https://api.fish.audio/v1/audio/infill \
--header 'Authorization: Bearer <token>' \
--header 'model: drama-3' \
--form 'audio=@take.wav' \
--form-string 'transcript=Next, load the wafer into chamber B and run the standard CVD recipe.' \
--form 'prefix_frames=45' \
--form 'suffix_frames=62' \
--form 'format=mp3' \
--output edited.mp3{
"status": 123,
"message": "<string>",
"reason": "<string>"
}{
"status": 123,
"message": "<string>",
"reason": "<string>"
}{
"status": 123,
"message": "<string>",
"reason": "<string>"
}{
"status": 123,
"message": "<string>",
"reason": "<string>"
}TTS (v1)
Audio Infill
Regenerate part of a recording with drama-3 and get the whole take back: request shapes, positions, length of the new span, response, and streaming
POST
/
v1
/
audio
/
infill
curl --request POST \
--url https://api.fish.audio/v1/audio/infill \
--header 'Authorization: Bearer <token>' \
--header 'model: drama-3' \
--form 'audio=@take.wav' \
--form-string 'transcript=Next, load the wafer into chamber B and run the standard CVD recipe.' \
--form 'prefix_frames=45' \
--form 'suffix_frames=62' \
--form 'format=mp3' \
--output edited.mp3{
"status": 123,
"message": "<string>",
"reason": "<string>"
}{
"status": 123,
"message": "<string>",
"reason": "<string>"
}{
"status": 123,
"message": "<string>",
"reason": "<string>"
}{
"status": 123,
"message": "<string>",
"reason": "<string>"
}Send the request as
multipart/form-data (file uploads) or
application/msgpack. You must include the model: drama-3 header: only
drama-3 serves this endpoint.transcript, and the span to replace. Drama 3 regenerates that span in the speaker’s voice, taken from the audio around it, and returns the whole take with the new span in place. There is no reference_id.
For a walkthrough with examples, see the Audio Infill guide.
Request shapes
A request takes one of two shapes. Both requiretranscript. Mixing them, for example audio together with prefix_audio, returns 400.
| Shape | Send | Use it to |
|---|---|---|
| Edit a take | audio, the start of the span (prefix_frames or prefix_seconds), and its end (suffix_frames or suffix_seconds) | Replace or insert speech inside one recording. |
| Join two clips | prefix_audio and, optionally, suffix_audio | Generate the speech between two clips, or continue a clip. |
Request fields
| Field | Required | Default | Description |
|---|---|---|---|
transcript | Yes | — | The full text of the result: the kept audio before the change, the new span, and the kept audio after it, with the edit already applied. Sent to the model as written, without text normalization. A missing, empty, or whitespace-only value returns 400. |
audio | Edit a take | — | The whole recording to edit, as an audio file. |
prefix_frames | Edit a take: this or prefix_seconds | — | The frame where the regenerated span starts. Everything before it is kept. A whole number of 0 or more; 0 keeps nothing before the span. |
prefix_seconds | Edit a take: this or prefix_frames | — | The start of the span in seconds from the start of the take, 0 or more, rounded to the nearest frame. |
suffix_frames | Edit a take: this or suffix_seconds | — | The frame where the regenerated span ends and the kept audio resumes. A whole number of 0 or more. Equal to the start inserts new speech at that point; the take’s length keeps nothing after the span. |
suffix_seconds | Edit a take: this or suffix_frames | — | The end of the span in seconds from the start of the take, 0 or more, rounded to the nearest frame. |
prefix_audio | Join two clips | — | The clip before the generated speech. Sent alone, the model continues it. |
suffix_audio | No | — | The clip after the generated speech. Requires prefix_audio. |
format | No | mp3 | Output audio format: wav, pcm, mp3, or opus. |
sample_rate | No | Unset | Output sample rate in Hz. When unset, the format’s default is used: 44100 Hz for most formats, 48000 Hz for opus. |
mp3_bitrate | No | 128 | MP3 bitrate in kbps: 64, 128, or 192. Only applies when format is mp3. |
opus_bitrate | No | -1000 | Opus bitrate in bps: -1000 (automatic), 24000, 32000, 48000, or 64000. Only applies when format is opus. |
format, sample_rate, mp3_bitrate, and opus_bitrate have the same meaning as on /v1/tts.
- Multipart: send each audio file as a file part and every other field as a text part. Write numbers as decimal text, such as
prefix_seconds=2.1. Let your HTTP client set the multipartContent-Typeand boundary. - MessagePack: set
Content-Type: application/msgpack, use the same field names, and send each audio file as binary bytes. - Number fields accept a number or numeric text in both bodies. Frame positions must be whole numbers:
1.5forprefix_framesreturns 400. - With curl, send
transcriptwith--form-stringinstead of--form(-F): curl reads a--formvalue that starts with<or@as a file.
Positions
When you edit a take, frames[start, end) are regenerated and the audio before and after them is kept.
- Give each side in frames (
prefix_frames,suffix_frames) or in seconds (prefix_seconds,suffix_seconds). Each side takes one of the two: both for the same side returns 400, and so does a side left out. - Positions are absolute, counted from the start of the take, at 44100 / 2048 (about 21.53) frames per second. Seconds are rounded to the nearest frame:
frames = round(seconds × 44100 / 2048). - A start equal to the end inserts new speech at that point.
- Some original audio has to stay. A start of 0 together with an end at the end of the take returns 400: with no original audio left, there is no voice to continue, and the model would read the line in a voice it picks itself, different on every request. Keeping only one side, to change the first or the last words of a take, is allowed.
- For the best results, keep at least 0.75 s of the original on each side and replace at least 0.2 s.
- The endpoint does not search the audio or the transcript for the words to change. You supply the positions.
Join two clips
Sendprefix_audio and, optionally, suffix_audio. Drama 3 generates the speech between them. With prefix_audio alone, it continues the clip. No positions are needed, and transcript covers both clips and the new speech. suffix_audio without prefix_audio returns 400.
Length of the new span
The model decides how long the regenerated span is, up to 1024 frames (about
47 s). There is no way to request an exact length yet, so the span can come
out shorter or longer than the speech it replaces, and the returned take
shorter or longer than the original. If the audio has to stay in sync with
picture, such as video or lip-sync, check the length of the result.
Response
A successful response (HTTP 200) is the whole take as one audio file informat, with nothing else in the body. For a join, it is both clips with the new speech between them.
The kept parts are re-synthesized together with the new span rather than copied byte for byte. On a human recording, the kept parts also pass through the model’s audio codec.
Stream events
SendAccept: text/event-stream to receive server-sent events instead. Each event is a data: line with a JSON object, told apart by its type, and the stream ends with data: [DONE].
type | Fields | Description |
|---|---|---|
start | format, sample_rate, middle_start_seconds | Sent first. middle_start_seconds is where the new span starts in the result. |
audio.delta | audio | A base64-encoded piece of the result. Concatenate the decoded audio of every audio.delta in arrival order to get the same file. |
done | output_frames, middle_end_seconds, total_seconds | Sent last. output_frames is the number of frames generated for the new span, middle_end_seconds is where the new span ends in the result, and total_seconds is the length of the result. |
middle_start_seconds and middle_end_seconds to find the new span in the result.
Errors
| Status | When |
|---|---|
400 | transcript is missing or empty; the two shapes are mixed; neither audio nor prefix_audio is sent; a side of the span is left out or given twice; the span covers the whole take; suffix_audio is sent without prefix_audio; a frame position is not a whole number; or an audio file can’t be decoded. Read the message. |
401 | Invalid or missing API key. |
402 | No API credit for drama-3. |
502 | The model returned no audio for the new span. |
Authorizations
Headers
Body
multipart/form-dataapplication/msgpack
Response
Request fulfilled, document follows
Was this page helpful?

