Skip to main content
POST
cURL
API v1 is deprecated. This version is no longer being developed — new endpoints, parameters and models are added to v2 only. Use the v2 endpoints to stay current: v2 API documentation.
Text-to-Music generates music tracks from text descriptions. You can control genre, tempo, key, time signature, and even provide lyrics. Optionally upload a reference_audio file for style transfer — the model will use it as a stylistic reference for the generated track. The endpoint returns a task ID to track processing status. Ideal for apps needing automated music creation — background tracks, jingles, or full songs with vocals.
Prerequisite: To ensure a successful request, you must first consult the Model Selection endpoint to identify a valid model slug and check specific limits.

​
Field values worth knowing

These constraints are enforced by validation and are easy to trip over. They are identical on the v2 endpoint, POST /api/v2/audio/music.
timesignature is validated as an integer, not as musical notation. If you populate it from a UI dropdown offering values like 4/4 or 6/8, convert to the integer before sending — otherwise only the requests that set the field fail, while the rest keep succeeding.
Reference audio requirements (optional):
  • Supported formats: MP3, OGG, M4A
  • Maximum file size: 10 MB (default; configurable)
  • Duration must be within model-specific limits — 5–60 s on the ACE-Step models (info.limits.min_ref_audio_duration / max_ref_audio_duration)
This endpoint uses multipart/form-data content type to support file uploads.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Accept
enum<string>
default:application/json
required
Available options:
application/json

Body

multipart/form-data

Music generation parameters

​
caption
string
required

Text description of the music to generate

Example:

"upbeat electronic dance music with energetic synths"

​
model
string
required

The model to use for music generation. Available models can be retrieved via the GET /api/v1/client/models endpoint.

Example:

"AceStep_1_5_Turbo"

​
lyrics
string
required

Required, and must not be empty. Lyrics for the music. Use "[Instrumental]" for instrumental tracks without vocals — omitting the field or sending an empty string returns 422 "The lyrics field is required."

Minimum string length: 1
Example:

"[Instrumental]"

​
duration
number
required

Duration in seconds. The accepted range is model-specific - read info.limits.min_duration / info.limits.max_duration for your model from the Model Selection endpoint; a value outside that range is rejected with 422. The turbo models accept 10-300, AceStep_1_5_Base 30-300.

Example:

30

​
inference_steps
integer
required

Number of diffusion inference steps. The accepted range is model-specific - read info.limits.min_steps / info.limits.max_steps for your model from the Model Selection endpoint; a value outside that range is rejected with 422. The turbo models only accept 8; AceStep_1_5_Base accepts 5-100.

Example:

8

​
guidance_scale
number
required

Classifier-free guidance scale. The accepted range is model-specific - read info.limits.min_guidance / info.limits.max_guidance for your model from the Model Selection endpoint; a value outside that range is rejected with 422. The turbo models (AceStep_1_5_Turbo, AceStep_1_5_XL_Turbo_INT8) only accept 1; AceStep_1_5_Base accepts 3-20.

Example:

1

​
seed
integer
required

Random seed. Use -1 for random.

Example:

-1

​
format
enum<string>
required

Audio output format. One of mp3, wav or flac. Any other value returns 422 "The selected format is invalid." mp3 is recommended for size; wav and flac are lossless and produce much larger result files.

Available options:
mp3,
wav,
flac
Example:

"mp3"

​
bpm
integer | null

Beats per minute. The accepted range is model-specific - read info.limits.min_bpm / info.limits.max_bpm for your model from the Model Selection endpoint. The ACE-Step models accept 50-200.

Example:

120

​
keyscale
string | null

Musical key/scale, as a free-form string (e.g. "C major", "F# minor", "D minor"). Not validated against a fixed list — the value is passed to the model as a hint.

Example:

"C major"

​
timesignature
enum<integer> | null

Time signature, as the number of beats per bar. Integer only — one of 2, 3, 4 or 6. Musical notation strings such as "4/4" or "3/4" are rejected with 422 "The timesignature field must be an integer." Map the numerator of a x/4 signature to this field (4/4 -> 4, 3/4 -> 3, 2/4 -> 2, 6/8 -> 6). Signatures that cannot be expressed as 2, 3, 4 or 6 (e.g. 5/4, 7/8) are not supported. Omit the field or send an empty value to let the model choose automatically.

Available options:
2,
3,
4,
6
Example:

4

​
vocal_language
string | null

Language for vocals, as a free-form string. Both ISO codes ("en", "es", "fr") and language names ("English") are accepted. Not validated against a fixed list — the value is passed to the model as a hint.

Example:

"en"

​
reference_audio
file | null

Optional reference audio file for style transfer. Supported formats: mp3, ogg, m4a. Max size configurable (default 15MB). Duration must be within model-specific limits.

​
webhook_url
string<uri> | null

Optional HTTPS URL to receive webhook notifications for job status changes (processing, completed, failed). Must be HTTPS. Max 2048 characters.

Maximum string length: 2048
Example:

"https://your-server.com/webhooks/deapi"

Response

ID of the inference request.

​
data
object

Information from success endpoint