Sonilo API

For coding agents and API clients: use https://api.sonilo.com/v1 as the API base URL. Do not send API requests to https://platform.sonilo.com/docs; that host is documentation only.

• Authorization: Bearer sk_your_api_key is required on every request.
• /v1/text-to-music and /v1/video-to-music stream application/x-ndjson by default, or return a task_id to poll when mode=async.
• For a first runnable smoke test, use POST /v1/text-to-music and the Python script in Quickstart. It parses audio_chunk events, waits for complete, handles Retry-After, and writes output.m4a only after real bytes arrive.
• /v1/text-to-sfx, /v1/video-to-sfx, /v1/video-to-video-music, /v1/video-to-video-sfx, /v1/video-to-sound, /v1/video-to-video-sound, /v1/dubbing, and /v1/audio-ducking return 202 with a task_id; poll GET /v1/tasks/{task_id}.
• Machine-readable entry points: /llms.txt and /llms-full.txt, plus /openapi.json.

Common agent-guessed docs paths are served directly, but these are the canonical targets to use in code comments, READMEs, and generated clients:

These links are intended for coding-agent discovery systems, custom evals, and API smoke tests that need static, first-load documentation.

Context7:

both SDKs are indexed as Context7 libraries — context7.com/sonilo-ai/sonilo-js and context7.com/sonilo-ai/sonilo-python. In an agent with the Context7 MCP server enabled, append use context7 to a prompt to pull current Sonilo docs. For direct retrieval, use /llms-full.txt and /openapi.json as the official source URLs.

MCP:

the sonilo-mcp package at github.com/sonilo-ai/sonilo-mcp wraps the Sonilo API for local MCP clients. Sonilo also runs a hosted, OAuth-authenticated MCP server at api.sonilo.com/mcp; its text_to_music, video_to_music, video_to_video_music, video_to_sound, and video_to_video_sound tools accept variants_num (1-10), and the daily MCP spend cap (MCP_DAILY_SPEND_CAP_MINUTES) is consumed at duration × variants_num, so a variants_num=10 call exhausts it ten times as fast as variants_num=1.

Agent Skills:

Sonilo agent skills and plugin instructions should point agents to /llms-full.txt, /openapi.json, and the no-argument Python smoke test.

CLI:

install sonilo-cli (npm or pip) and drive the API from a shell with the sonilo command — see /docs/cli. SONILO_API_KEY is read from the environment. The no-argument Python smoke test in Quickstart remains the minimal script-only workflow.

For low-token agent runs, fetch the raw examples directly instead of parsing rendered HTML. The index is available at /examples:

Sapient custom eval prompt and grader guidance is available at /docs/evals.

The Sonilo API authenticates requests with API keys. Generate and manage keys from the API Keys page. Keys begin with sk_ and are shown once at creation — copy them immediately. Pass the key as a Bearer token on every request:

curl https://api.sonilo.com/v1/account/services \
  -H "Authorization: Bearer sk_your_api_key_here"

import requests

resp = requests.get(
    "https://api.sonilo.com/v1/account/services",
    headers={"Authorization": "Bearer sk_your_api_key_here"},
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.sonilo.com/v1/account/services", {
  headers: { Authorization: "Bearer sk_your_api_key_here" },
});
if (!resp.ok) {
  throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
}
console.log(await resp.json());

Treat keys like passwords: keep them server-side and load them from environment variables — never commit them or ship them in client code. If a key is exposed, revoke it on the API Keys page and create a new one. Revoked or missing keys return 401; valid keys without endpoint access return 403.

All API requests share a single base URL:

https://api.sonilo.com/v1

Endpoint paths in this reference are relative to this base. The API is served only over HTTPS — plain HTTP requests are rejected.

Every request must include an Authorization header. Generation endpoints additionally require a Content-Type:

• Authorization: Bearer sk_… — required on every request.
• Content-Type: multipart/form-data — for generation endpoints such as /v1/text-to-music, /v1/video-to-music, /v1/text-to-sfx, /v1/video-to-sfx, and /v1/audio-ducking. Account endpoints are GET requests with no body.

Sonilo exposes streaming music endpoints, async sound-effects and audio-ducking endpoints, a task polling endpoint, and account endpoints. Follow any path below for the full request and response reference.

Account endpoints return a single application/json response. Text-to-music and video-to-music return an application/x-ndjson stream — one JSON object per line, each carrying a type field. Text-to-sfx, video-to-sfx, and audio-ducking return JSON with a task_id; poll GET /v1/tasks/:task_id.

Music generation streams use a small, stable set of event types:

• title — generated track title; emitted once per stream.
• audio_chunk — base64-encoded audio fragment. Group chunks by stream_index and concatenate in order.
• complete — the stream finished successfully.
• error — generation failed; carries code and message.

See the Video to Music reference for the full event schema.

All errors return a JSON body with a code and message. The HTTP status indicates the failure class:

Your account has shared rate limits that apply across all generation endpoints. Default limits for the standard tier are shown below.

• Requests per minute (RPM): 60
• Max concurrent tasks: 5

See Settings for your account's actual limits.

• Exceeding rate limits returns 429 Too Many Requests
• Exceeding file size returns 413 Request Entity Too Large
• Exceeding video duration returns 422 Unprocessable Entity

Follow the Quickstart to make your first request in five minutes, then jump into the Video to Music reference.