Text to Music

Generate music from a text prompt with a caller-specified duration. By default (mode=stream) returns a streaming NDJSON response. Pass mode=async to instead get 202 Accepted with a task_id; poll GET /v1/tasks/:task_id until the task reaches a terminal status.

POST/v1/text-to-musicmultipart/form-data

Streaming (default) — basic prompt

curl -N -X POST https://api.sonilo.com/v1/text-to-music \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "prompt=lofi hiphop beat" \
  -F "duration=60"

import json
import requests

with requests.post(
    "https://api.sonilo.com/v1/text-to-music",
    headers={"Authorization": "Bearer sk_your_api_key"},
    files={
        "prompt": (None, "lofi hiphop beat"),
        "duration": (None, "60"),
    },
    stream=True,
    timeout=300,
) as resp:
    resp.raise_for_status()
    for line in resp.iter_lines(decode_unicode=True):
        if not line:
            continue
        event = json.loads(line)
        print(event["type"], event)

const form = new FormData();
form.append("prompt", "lofi hiphop beat");
form.append("duration", "60");

const resp = await fetch("https://api.sonilo.com/v1/text-to-music", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_your_api_key",
  },
  body: form,
});

if (!resp.ok) {
  throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
}

const reader = resp.body.getReader();
const decoder = new TextDecoder();
let buf = "";
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });
  let nl;
  while ((nl = buf.indexOf("\n")) !== -1) {
    const line = buf.slice(0, nl);
    buf = buf.slice(nl + 1);
    if (!line) continue;
    console.log(JSON.parse(line));
  }
}

Streaming (default) — segmented prompt

curl -N -X POST https://api.sonilo.com/v1/text-to-music \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "prompt=cinematic orchestral score" \
  -F "duration=60" \
  -F 'segments=[{"start": 0, "label": "intro", "prompt": "soft solo piano"}, {"start": 20, "label": "chorus", "prompt": "full orchestra, soaring strings"}, {"start": 45, "label": "outro", "prompt": "strings fade to silence"}]'

import json
import requests

segments = [
    {"start": 0, "label": "intro", "prompt": "soft solo piano"},
    {"start": 20, "label": "chorus", "prompt": "full orchestra, soaring strings"},
    {"start": 45, "label": "outro", "prompt": "strings fade to silence"},
]

with requests.post(
    "https://api.sonilo.com/v1/text-to-music",
    headers={"Authorization": "Bearer sk_your_api_key"},
    files={
        "prompt": (None, "cinematic orchestral score"),
        "duration": (None, "60"),
        "segments": (None, json.dumps(segments)),
    },
    stream=True,
    timeout=300,
) as resp:
    resp.raise_for_status()
    for line in resp.iter_lines(decode_unicode=True):
        if not line:
            continue
        event = json.loads(line)
        print(event["type"], event)

const segments = [
  { start: 0, label: "intro", prompt: "soft solo piano" },
  { start: 20, label: "chorus", prompt: "full orchestra, soaring strings" },
  { start: 45, label: "outro", prompt: "strings fade to silence" },
];

const form = new FormData();
form.append("prompt", "cinematic orchestral score");
form.append("duration", "60");
form.append("segments", JSON.stringify(segments));

const resp = await fetch("https://api.sonilo.com/v1/text-to-music", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_your_api_key",
  },
  body: form,
});

if (!resp.ok) {
  throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
}

const reader = resp.body.getReader();
const decoder = new TextDecoder();
let buf = "";
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });
  let nl;
  while ((nl = buf.indexOf("\n")) !== -1) {
    const line = buf.slice(0, nl);
    buf = buf.slice(nl + 1);
    if (!line) continue;
    console.log(JSON.parse(line));
  }
}

{
  "type": "title",
  "title": "Sunset Drive"
}
{
  "type": "audio_chunk",
  "sample_rate": 44100,
  "channels": 2,
  "stream_index": 0,
  "num_streams": 1,
  "data": "<base64>"
}
{
  "type": "complete"
}

Async mode (mode=async)

Returns 202 Accepted immediately with a task_id instead of streaming; poll GET /v1/tasks/:task_id for the result.

curl -X POST https://api.sonilo.com/v1/text-to-music \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "prompt=lofi hiphop beat" \
  -F "duration=60" \
  -F "mode=async"
# => {"task_id": "9f5f2f7e-...", "status": "processing"}

curl https://api.sonilo.com/v1/tasks/9f5f2f7e-... \
  -H "Authorization: Bearer sk_your_api_key"
# poll until "status" is "succeeded" or "failed"

import time
import requests

headers = {"Authorization": "Bearer sk_your_api_key"}

submit = requests.post(
    "https://api.sonilo.com/v1/text-to-music",
    headers=headers,
    files={
        "prompt": (None, "lofi hiphop beat"),
        "duration": (None, "60"),
        "mode": (None, "async"),
    },
    timeout=30,
)
submit.raise_for_status()
task_id = submit.json()["task_id"]

while True:
    task = requests.get(
        f"https://api.sonilo.com/v1/tasks/{task_id}",
        headers=headers,
        timeout=30,
    ).json()
    if task["status"] != "processing":
        break
    time.sleep(3)

if task["status"] == "succeeded":
    for stream in task["audio"]:
        print(stream["stream_index"], stream["url"])
else:
    print(task["error"])

const headers = { Authorization: "Bearer sk_your_api_key" };

const form = new FormData();
form.append("prompt", "lofi hiphop beat");
form.append("duration", "60");
form.append("mode", "async");

const submit = await fetch("https://api.sonilo.com/v1/text-to-music", {
  method: "POST",
  headers,
  body: form,
});
const { task_id } = await submit.json();

let task;
do {
  await new Promise((r) => setTimeout(r, 3000));
  task = await (
    await fetch(`https://api.sonilo.com/v1/tasks/${task_id}`, { headers })
  ).json();
} while (task.status === "processing");

if (task.status === "succeeded") {
  for (const stream of task.audio) {
    console.log(stream.stream_index, stream.url);
  }
} else {
  console.log(task.error);
}

{
  "task_id": "9f5f2f7e-…",
  "status": "processing"
}

Authorization

Authenticate via Bearer token. Generate keys at the API Keys page and pass them in the Authorization header on every request.

Authorization: Bearer sk_your_api_key

Body Parameters

promptstringrequired

Text prompt describing the music to generate. Max length 2000 characters.

durationintegerrequired

Desired duration of the output track in seconds. Min 5, max 360.

modestring

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_formatstring

Optional. m4a (default) returns AAC-encoded audio. wav returns 16-bit PCM WAV instead, transcoded server-side after generation. Requires mode=async (the streaming response always returns m4a — see GET /v1/tasks/:task_id's audio[].content_type).

segmentsstring

Optional JSON array of timed segment prompts; the music changes style at each boundary. Each item has start (seconds; the first must be 0, starts strictly increasing and at least 5 seconds apart, the last at least 5 seconds before duration), prompt (1-200 characters), and an optional label that must be exactly one of these values — any other value is rejected with a 422 error, and it defaults to none when omitted: intro, verse, pre-chorus, chorus, bridge, break, silence, outro, none. 1-30 items.

Response

titleevent

Generated track title. Appears once near the start of the stream.

audio_chunkevent

Base64-encoded AAC/fMP4 audio fragment. Includes stream_index and num_streams; group by stream_index and append in order.

errorevent

Generation failed. Contains code and message.

completeevent

Stream finished successfully.

Streaming (default) — basic prompt

curl -N -X POST https://api.sonilo.com/v1/text-to-music \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "prompt=lofi hiphop beat" \
  -F "duration=60"

import json
import requests

with requests.post(
    "https://api.sonilo.com/v1/text-to-music",
    headers={"Authorization": "Bearer sk_your_api_key"},
    files={
        "prompt": (None, "lofi hiphop beat"),
        "duration": (None, "60"),
    },
    stream=True,
    timeout=300,
) as resp:
    resp.raise_for_status()
    for line in resp.iter_lines(decode_unicode=True):
        if not line:
            continue
        event = json.loads(line)
        print(event["type"], event)

const form = new FormData();
form.append("prompt", "lofi hiphop beat");
form.append("duration", "60");

const resp = await fetch("https://api.sonilo.com/v1/text-to-music", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_your_api_key",
  },
  body: form,
});

if (!resp.ok) {
  throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
}

const reader = resp.body.getReader();
const decoder = new TextDecoder();
let buf = "";
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });
  let nl;
  while ((nl = buf.indexOf("\n")) !== -1) {
    const line = buf.slice(0, nl);
    buf = buf.slice(nl + 1);
    if (!line) continue;
    console.log(JSON.parse(line));
  }
}

Streaming (default) — segmented prompt

curl -N -X POST https://api.sonilo.com/v1/text-to-music \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "prompt=cinematic orchestral score" \
  -F "duration=60" \
  -F 'segments=[{"start": 0, "label": "intro", "prompt": "soft solo piano"}, {"start": 20, "label": "chorus", "prompt": "full orchestra, soaring strings"}, {"start": 45, "label": "outro", "prompt": "strings fade to silence"}]'

import json
import requests

segments = [
    {"start": 0, "label": "intro", "prompt": "soft solo piano"},
    {"start": 20, "label": "chorus", "prompt": "full orchestra, soaring strings"},
    {"start": 45, "label": "outro", "prompt": "strings fade to silence"},
]

with requests.post(
    "https://api.sonilo.com/v1/text-to-music",
    headers={"Authorization": "Bearer sk_your_api_key"},
    files={
        "prompt": (None, "cinematic orchestral score"),
        "duration": (None, "60"),
        "segments": (None, json.dumps(segments)),
    },
    stream=True,
    timeout=300,
) as resp:
    resp.raise_for_status()
    for line in resp.iter_lines(decode_unicode=True):
        if not line:
            continue
        event = json.loads(line)
        print(event["type"], event)

const segments = [
  { start: 0, label: "intro", prompt: "soft solo piano" },
  { start: 20, label: "chorus", prompt: "full orchestra, soaring strings" },
  { start: 45, label: "outro", prompt: "strings fade to silence" },
];

const form = new FormData();
form.append("prompt", "cinematic orchestral score");
form.append("duration", "60");
form.append("segments", JSON.stringify(segments));

const resp = await fetch("https://api.sonilo.com/v1/text-to-music", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_your_api_key",
  },
  body: form,
});

if (!resp.ok) {
  throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
}

const reader = resp.body.getReader();
const decoder = new TextDecoder();
let buf = "";
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });
  let nl;
  while ((nl = buf.indexOf("\n")) !== -1) {
    const line = buf.slice(0, nl);
    buf = buf.slice(nl + 1);
    if (!line) continue;
    console.log(JSON.parse(line));
  }
}

{
  "type": "title",
  "title": "Sunset Drive"
}
{
  "type": "audio_chunk",
  "sample_rate": 44100,
  "channels": 2,
  "stream_index": 0,
  "num_streams": 1,
  "data": "<base64>"
}
{
  "type": "complete"
}

Async mode (mode=async)

Returns 202 Accepted immediately with a task_id instead of streaming; poll GET /v1/tasks/:task_id for the result.

curl -X POST https://api.sonilo.com/v1/text-to-music \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "prompt=lofi hiphop beat" \
  -F "duration=60" \
  -F "mode=async"
# => {"task_id": "9f5f2f7e-...", "status": "processing"}

curl https://api.sonilo.com/v1/tasks/9f5f2f7e-... \
  -H "Authorization: Bearer sk_your_api_key"
# poll until "status" is "succeeded" or "failed"

import time
import requests

headers = {"Authorization": "Bearer sk_your_api_key"}

submit = requests.post(
    "https://api.sonilo.com/v1/text-to-music",
    headers=headers,
    files={
        "prompt": (None, "lofi hiphop beat"),
        "duration": (None, "60"),
        "mode": (None, "async"),
    },
    timeout=30,
)
submit.raise_for_status()
task_id = submit.json()["task_id"]

while True:
    task = requests.get(
        f"https://api.sonilo.com/v1/tasks/{task_id}",
        headers=headers,
        timeout=30,
    ).json()
    if task["status"] != "processing":
        break
    time.sleep(3)

if task["status"] == "succeeded":
    for stream in task["audio"]:
        print(stream["stream_index"], stream["url"])
else:
    print(task["error"])

const headers = { Authorization: "Bearer sk_your_api_key" };

const form = new FormData();
form.append("prompt", "lofi hiphop beat");
form.append("duration", "60");
form.append("mode", "async");

const submit = await fetch("https://api.sonilo.com/v1/text-to-music", {
  method: "POST",
  headers,
  body: form,
});
const { task_id } = await submit.json();

let task;
do {
  await new Promise((r) => setTimeout(r, 3000));
  task = await (
    await fetch(`https://api.sonilo.com/v1/tasks/${task_id}`, { headers })
  ).json();
} while (task.status === "processing");

if (task.status === "succeeded") {
  for (const stream of task.audio) {
    console.log(stream.stream_index, stream.url);
  }
} else {
  console.log(task.error);
}

{
  "task_id": "9f5f2f7e-…",
  "status": "processing"
}