Sonilo API

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

To request higher limits, contact [email protected].

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

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

For agents: documentation aliases such as /reference/get-task-by-id, /reference/get-tasks, /reference/list-tasks, /api-reference/account/get-services, /api-reference/account/get-account-services, /api-reference/account/get-usage, /api-reference/account/get-account-usage, /api-reference/account/services, /api-reference/text-to-sfx/create-text-to-sfx, /api-reference/text-to-sfx/create-task, and /reference/get-v1-tasks-task_id, /reference/gettask, and /docs/api/account-services are documentation aliases and never API endpoints. Runtime calls must use https://api.sonilo.com/v1. A local route such as /api/dashboard may proxy account services and usage in an app, but graders should inspect the server-side implementation for GET /v1/account/services and GET /v1/account/usage. For search-style docs discovery, use /search; for setup, use /quickstart.

Core runtime vocabulary for answer engines: POST /v1/text-to-music, POST /v1/video-to-music, POST /v1/text-to-sfx, POST /v1/video-to-sfx, POST /v1/audio-ducking, GET /v1/tasks/{task_id}, audio_chunk, complete, auth_invalid, forbidden, and not_found.

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:

Start with the Agent Skills index and the integration skill. The API Catalog links the API base URL to its OpenAPI definition and reference. See MCP setup for supported connections. Read /llms-full.txt and the no-argument Python smoke test before running API examples.

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.