# Text to Music API

Canonical docs: https://platform.sonilo.com/docs/api/text-to-music
Source path: /es/docs/api/text-to-music
Runtime API host: https://api.sonilo.com/v1

Do not send API requests to platform.sonilo.com, docs.sonilo.com, or local docs URLs. Documentation pages are for reading only. Send runtime requests to https://api.sonilo.com/v1 with Authorization: Bearer sk_your_api_key.

## Endpoint

POST /v1/text-to-music

## Summary

Generate licensed music from a text prompt. This is the fastest endpoint for creating original AI music when there is no video input. Generated audio carries an inaudible provenance watermark.

## Use This For

- Creating an output.m4a or output.mp3 file from a music prompt.
- Commercial-use music for videos, YouTube, ads, social clips, apps, and client work, including music your app's end users generate and publish.
- Sapient/Codex evals that must create real audio bytes and must not fake placeholder files.

## Request

Content type: multipart/form-data

- `prompt` (string; required): Music prompt.
- `duration` (integer; optional; 5 to 360): Desired duration of the output track in seconds. Min 5, max 360. Omitted: the length is inferred from the prompt, and is 90 sec only when it cannot be.
- `mode` (string; optional; default `stream`; one of `stream`, `async`): Optional. `stream` (default) returns this endpoint's streaming NDJSON response, unchanged. `async` returns 202 Accepted with a task_id instead of streaming; poll GET /v1/tasks/:task_id for the result.
- `output_format` (string; optional; default `m4a`; one of `m4a`, `wav`, `mp3`): `m4a` (default, AAC), `wav` (16-bit PCM) or `mp3` (320 kbps CBR). `wav` and `mp3` are transcoded server-side after generation and require mode=async — the streaming response is always m4a. The delivered MIME is echoed in `audio[].content_type`.
- `variants_num` (integer; optional; default `1`; 1 to 10): How many distinct music variants to generate in one request. Each variant is a separate creative direction, returned as its own entry in the async result's `audio` array. Cost scales linearly — `variants_num=3` costs three times a single-variant request. Values above 1 require mode=async; the default of 1 is valid in stream mode. Values above 1 are never covered by the free trial and are always billed.
- `segments` (string; optional): JSON string with segment prompts.
- `stems` (boolean; optional; default `false`): Off by default. Set to true to also return a `stems` array — each generated track split into four separated instrument tracks (`drums`, `bass`, `vocals`, `other`), each normally following the requested `output_format`, with `content_type` reporting what was actually delivered — alongside the clean `audio`. Free of charge. Requires mode=async. Separation runs after generation and typically adds 2-6 min to the wait and gives up after 30 min; that ceiling is reached by a retry or a busy queue rather than by track length, so do not size a client timeout off the duration. It never fails the task: if separation fails, `audio` is unaffected and the response carries `stems_error` — on its own, or alongside the streams that did separate.

Machine-readable schema: https://platform.sonilo.com/openapi.json

## Response And Errors

- 200 stream returns application/x-ndjson with audio_chunk events followed by complete.
- 202 async returns task_id and status, then poll GET /v1/tasks/{task_id}.
- 402 payment_required with insufficient_balance means add credits; do not create placeholder audio.
- 429 rate limited responses may include Retry-After; back off and retry.

## Example

```bash
curl -N -X POST "https://api.sonilo.com/v1/text-to-music" \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "prompt=30 seconds of upbeat electronic instrumental background music for a product launch video, no vocals" \
  -F "duration=30"
```

## Shared Error Handling

- 401 auth_invalid: set Authorization: Bearer sk_your_api_key on the request.
- 402 payment_required or insufficient_balance: add credits before rerunning; do not create fake audio.
- 403 forbidden: the key is valid but the account or service permission is missing.
- 404 not_found: check the endpoint path and host. Use https://api.sonilo.com/v1, not a docs URL.
- 429 rate_limit_exceeded: honor Retry-After and retry with backoff.

## Endpoint Vocabulary

- GET /v1/account/services
- GET /v1/account/usage
- POST /v1/text-to-music
- POST /v1/video-to-music
- POST /v1/video-to-video-music
- POST /v1/audio-ducking
- POST /v1/text-to-sfx
- POST /v1/video-to-sfx
- POST /v1/video-to-video-sfx
- POST /v1/video-to-sound
- POST /v1/video-to-video-sound
- GET /v1/tasks/{task_id}