Skip to main content
POST
cURL
Tip: The replacement lyrics should have some overlap with the original lyrics, and ideally the timing should align.infill_lyrics: The new lyric segment you want to fill in or replace.prompt: The context—concatenate the original lyrics before and after the new lyrics.Example: Original lyrics are [Verse 1]AA [Chorus]BB [Verse 2]CC [Chorus]DD [Outro]EE. If you want to replace CC with OO:
  • Set infill_lyrics to OO (the new lyrics to insert).
  • Set prompt to BB [Verse 2]OO[Chorus]DD (include part of the original lyrics before and after OO to form the context).
This allows the model to generate the best result based on the surrounding context in prompt and the new lyrics in infill_lyrics.

Authorizations

TT-API-KEY
string
header
required

You can obtain your API key from the TTAPI Dashboard.

Body

application/json
music_id
string
required

Audio ID

infill_start_s
number
required

Replacement start time, in seconds.

infill_end_s
number
required

Replacement end time, in seconds.

mv
enum<string>
default:chirp-v6
required

Model to use. Available values: chirp-v6, chirp-v6-wild, chirp-v6-mini. Suno legacy models have all been discontinued; passing a legacy name maps it to chirp-v6. See Model Mapping. After creating a custom model, you can also pass chirp-custom:{model_id}. See Create Model. persona_id and chirp-custom cannot be used together.

Available options:
chirp-v6,
chirp-v6-wild,
chirp-v6-mini
prompt
string

Context lyrics.

infill_lyrics
string

New lyrics.

title
string

Music title.

Used in custom mode (custom=true). Maximum length: 80 characters.

tags
string

Music style or genre.

Used in custom mode (custom=true). Maximum length: 1000 characters.

Example:

"rock, blues, hip-hop, r&b"

negative_tags
string

Music styles or genres that should be excluded from generation.

Used in custom mode (custom=true).

variety
enum<string>

Style variety. Controls how much the generated result varies from the specified style.

  • off: Exact style
  • normal: Balanced variety
  • high: Distinct styles
  • extra: Bold exploration
  • max: Unreasonably varied
Available options:
off,
normal,
high,
extra,
max
max_mode
boolean
default:false

Whether to use more compute to maximize consistency throughout the song. Custom mode only.

  • false: No (default)
  • true: Yes. Credit consumption is doubled when enabled
audio_format
enum<string>

Audio format of audioUrl after the job succeeds.

Available options:
mp3,
m4a,
wav
Example:

"mp3"

hookUrl
string

Callback notification URL

isStorage
boolean
default:true
deprecated

Whether to store the generated audio.

  • true: The audio will be stored and a TTAPI CDN URL will be returned
  • false: The original source URL will be returned

Response

Request successful

status
string
required
Example:

"SUCCESS"

message
string
required
Example:

"success"

data
object
required
Example:
Last modified on March 21, 2026