Speech generation API

Updated 2026-09-18 · Suno-API team

Endpoint description

Speech turns a speech script or a one-line description into "talking/speech" audio, optionally with background music. It suits speeches, toasts, narration, voice-over scripts, audio content and similar scenarios.

Please note: this endpoint generates speech audio, not a sung song (no melody, no sung vocals). If you need singing, use the simple mode generation API or the custom mode generation API.

Endpoint: POST /api/music/speech

Billing: Paid, currently 0.6 ¥ per call by default. Each call usually returns 2 audio items; the amount actually charged follows the back-office price configuration.

Max Mode / Variety: this endpoint supports the optional parameters max_mode and variety (0-4). With max_mode on, this call is billed at 2× the price (0.6 → 1.2 ¥ per call); variety costs nothing extra. What they mean and how to send them is in the "Advanced parameters" section of the New API overview.

Wait times and timeouts (important): this is a synchronous endpoint — an order is only accepted and handed to generation when the response arrives. Measured, most requests return within seconds (1–10 s); but like other synchronous generation endpoints, it can take longer in extreme cases. Set your client timeout to 300 seconds or more; no response does not mean nothing was generated, and do not retry immediately after a timeout (that duplicates the order and charges again). If the connection dropped, confirm later with GET /api/music/songs. See "Wait times and timeout settings" in the New API overview.

Content compliance: the platform checks the script for copyright and content policy. If it is judged to involve copyrighted material (for example quoting someone else's lyrics or the verbatim text of a well-known work), this call fails and the full amount is refunded automatically. Switch to your own wording, or turn the quotation into a paraphrase, and try again.

Request parameters

Headers

Body parameters

This endpoint does not support duration: sending it returns HTTP 400 rather than being silently ignored. The speech length is determined by the content length of script.

Request examples

Minimal request (just the script)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Good morning, everyone! Today my talk is about making the most of our time and pressing on."
  }'

Full request (with tone, gender and background music off)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Good evening everyone, thank you all for coming to celebrate this special day with us.",
    "tone": "warm and slow, wedding reception",
    "song_title": "Wedding Toast",
    "gender": "f",
    "backing_music": false,
    "model": "suno-v6"
  }'

Python example

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/speech',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'script': 'Good afternoon, colleagues. Let me report on this week\'s progress.',
        'tone': 'calm and clear, meeting report',
        'gender': 'male',
        'backing_music': True,
    },
    timeout=300,
)
response.raise_for_status()
items = response.json()          # usually 2 items
for item in items:
    print(item['song_id'], item['status'])

Parameter notes

script (the speech, required)

• Paste the content you want to deliver; you can also write a single description and let the model generate the speech (for example "a half-time pep talk for a team twenty points behind, from a low murmur to a full-throated roar").
• Line breaks, paragraphs and stage directions such as [pause] can all be written straight in, and the model will follow them as far as it can.
• The limit is 3000 characters (counted in Unicode characters, one Chinese character counting as 1); longer text returns 400 and is not charged.

tone (tone and setting, optional)

It describes how to speak rather than what to say. Include four kinds of information: tone, pace/rhythm, emotion, setting.

Energetic and forceful, speeding up from slow, clear pauses; school hall, addressing all students and staff
Warm and soft, an even pace; wedding reception
Composed and restrained, steady and clear; board report

The limit is 1000 characters. When omitted, the model judges from the content of script.

gender / vocal_gender (speaker gender, optional)

• Pass m or male for a male voice, f or female for a female voice; the server normalises them to m / f.
• Both field names work — use either one: gender is the recommended form for this endpoint; if you already use the custom mode, you can keep using vocal_gender.
• Omitting it means "any", and the model decides.

backing_music (background music, optional)

• Defaults to true (with background music), matching the default on the Suno web app.
• Passing false gives a voice-only speech, handy if you want to add your own score or dubbing later.
• Must be a JSON boolean true / false; the strings "true" and "1" are also accepted, but booleans are recommended.

model (model, optional)

All three customer-facing models are available at the same price (0.6 ¥ per call). Speech is generated by the Suno v6 family; when omitted it is treated as suno-v6. Unless you have a specific preference, you normally do not need to send this field.

Parameter validation and text limits

The following cases return HTTP 400, and all of them are blocked before billing, so no charge is produced:

Text field limits

Over-length text also returns HTTP 400 and does not start generation or pre-charge anything. Counting is by Unicode characters (one Chinese character counts as 1), and leading/trailing spaces are included:

The error looks like script must not exceed 3000 characters; received 4120: the first word is the field that exceeded the limit and the end is the actual count, so on a 400 you can trim straight from those two numbers.

Response

The response is an array of songs exactly like that of the other generation endpoints (usually 2 items); save the song_id and use the song query API to check the final status and audio address:

[
  {
    "song_id": "b7529174-b495-465b-8c5e-cd21bea2df8c",
    "song_title": "Making the Most of Our Time",
    "status": "pending",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-10-08T01:00:00Z"
  }
]

Generation failure and refunds

When generation fails, the charge for that call is refunded in full automatically; there is no need to contact support. The reason can be seen in the response or in the error_message of the song query API.

The most common failure is the platform judging the content to involve copyrighted material, for example:

Your lyrics contain copyrighted material. Please change it and try again.

In that case, replace the script with your own wording (or turn the quotation into a paraphrase) and submit again.

FAQ

Q: Why is the result "speech" instead of singing? A: This is the speech endpoint, and its output is speech audio. For singing, use the generation or custom mode endpoints.

Q: Why do I get 2 items each time? A: Like the platform's other generation endpoints, one generation produces 2 candidates; query them separately by song_id and keep the one you like.

Q: How do I control the length? A: It is determined by the length of script; this endpoint does not accept a duration parameter.

Q: Can I specify a voice (for example my cloned voice)? A: The current version does not support that. Speech uses a fixed set of speech voices, and gender selects male or female; if you need your own voice, use the related capability of the voice profile creation API (recommended).

Q: What happens if I omit tone? A: The model judges tone and rhythm from the content of script. To reproduce a style reliably, write tone, pace and setting into tone.

Compatible fields

New integrations should use snake_case throughout. The other fields (script, tone, song_title, backing_music) have no camelCase aliases.

Next steps

Once you have the song_id:

1. Use the song query API to check the generation status and audio address;
2. When it completes, use the song media download and preview API to download or preview it;
3. For batch downloads or copying to your own storage, see the download centre endpoints.