Sonilo API

Die Sonilo API authentifiziert Anfragen mit API-Schlüsseln. Generieren und verwalten Sie Schlüssel auf der API-Schlüssel-Seite. Schlüssel beginnen mit sk_ und werden einmalig bei der Erstellung angezeigt – kopieren Sie sie sofort. Übergeben Sie den Schlüssel als Bearer-Token bei jeder Anfrage:

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());

Behandeln Sie Schlüssel wie Passwörter: Bewahren Sie sie serverseitig auf und laden Sie sie aus Umgebungsvariablen – übergeben Sie sie niemals direkt im Code oder Client-Code. Wenn ein Schlüssel kompromittiert wurde, widerrufen Sie ihn auf der API-Schlüssel-Seite und erstellen Sie einen neuen. Widerrufene Schlüssel werden sofort wirksam und geben bei jeder nachfolgenden Anfrage 401 zurück.

Alle API-Anfragen teilen eine gemeinsame Basis-URL:

https://api.sonilo.com/v1

Endpunktpfade in dieser Referenz sind relativ zu dieser Basis. Die API wird ausschließlich über HTTPS bereitgestellt – einfache HTTP-Anfragen werden abgelehnt.

Jede Anfrage muss einen Authorization-Header enthalten. Generierungsendpunkte erfordern zusätzlich einen Content-Type:

• Authorization: Bearer sk_… – bei jeder Anfrage erforderlich.
• Content-Type: multipart/form-data – für die Generierungsendpunkte /v1/text-to-music und /v1/video-to-music, die Formularfelder und Datei-Uploads akzeptieren. Kontoendpunkte sind GET-Anfragen ohne Body.

Sonilo stellt zwei Generierungsendpunkte und zwei Kontoendpunkte bereit. Folgen Sie einem der Pfade unten für die vollständige Anfrage- und Antwortreferenz.

Kontoendpunkte geben eine einzelne application/json-Antwort zurück. Generierungsendpunkte geben einen application/x-ndjson-Stream zurück – ein JSON-Objekt pro Zeile, jedes mit einem type-Feld. Lesen Sie den Body zeilenweise und parsen Sie jede Zeile einzeln.

Generierungsstreams verwenden einen kleinen, stabilen Satz von Ereignistypen:

• title – generierter Tracktitel; wird einmal pro Stream ausgegeben.
• audio_chunk – base64-kodiertes Audiofragment. Gruppieren Sie Chunks nach stream_index und verketten Sie sie in der richtigen Reihenfolge.
• complete – der Stream wurde erfolgreich abgeschlossen.
• error – Generierung fehlgeschlagen; enthält code und message.

Das vollständige Ereignisschema finden Sie in der Video zu Musik-Referenz.

Alle Fehler geben einen JSON-Body mit code und message zurück. Der HTTP-Status gibt die Fehlerklasse an:

Ihr Konto hat gemeinsame Ratenlimits, die für alle Generierungsendpunkte gelten. Die Standardlimits für den Standardtarif sind unten aufgeführt.

• Anfragen pro Minute (RPM): 60
• Max. gleichzeitige Aufgaben: 5

Unter Einstellungen finden Sie die tatsächlichen Limits Ihres Kontos.

• Bei Überschreitung der Ratenlimits wird 429 Too Many Requests zurückgegeben
• Bei Überschreitung der Dateigröße wird 413 Request Entity Too Large zurückgegeben
• Bei Überschreitung der Videodauer wird 422 Unprocessable Entity zurückgegeben

Um höhere Limits anzufordern, wenden Sie sich an [email protected].

Folgen Sie dem Schnellstart, um Ihre erste Anfrage in fünf Minuten zu stellen, und tauchen Sie dann in die Video zu Musik-Referenz ein.

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.