speech

Generate spoken audio: a narrator, a news read, an ad voice-over, a character line. Direct the delivery with tone, pacing and emotion, with or without background music.

This is an async endpoint — submit the request, receive a task_id, then poll for the result.

Credits cost: 20 per request (two takes are returned). Credits are refunded automatically if the task fails.

Two modes, chosen by custom_mode:

custom_mode: true — your script. prompt is read aloud as written. Use tags to direct the voice: tone, pacing, emotion, scene (for example calm, warm, steady pace, evening news).

custom_mode: false — from a description. A script is written and read from gpt_description_prompt (for example Read an evening news segment in a calm male voice at a steady pace). tags, background_music, vocal_gender and variety are not accepted in this mode.

Workflow:

Submit the request

Receive a task_id in the response

Poll GET /api/v1/sonic/task/{task_id} until the task completes, or pass webhook_url

The completed task returns two clips, each with audio_url, duration, title and tags

Audio is delivered as MP3.

Polling Result

{
  "code": 200,
  "data": [
    {
      "clip_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "state": "succeeded",
      "title": "Good Evening",
      "tags": "Warm mid-range female voice, calm evening newsreader, steady measured pace",
      "lyrics": "Good evening. Here is tonight's news.",
      "audio_url": "https://files.musicapi.ai/media/xxxxxxxx-audio_url.mp3",
      "duration": 13.6
    },
    {
      "clip_id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
      "state": "succeeded",
      "title": "Good Evening",
      "audio_url": "https://files.musicapi.ai/media/yyyyyyyy-audio_url.mp3",
      "duration": 13.2
    }
  ],
  "message": "success"
}

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/json

Example

{
  "custom_mode": true,
  "prompt": "Good evening. Here is tonight's news.",
  "tags": "calm, warm, steady pace, evening news",
  "background_music": false,
  "vocal_gender": "f"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Request

Request Code Samples

Responses