API Sonilo

L'API Sonilo autentica le richieste con chiavi API. Genera e gestisci le chiavi dalla pagina Chiavi API. Le chiavi iniziano con sk_ e vengono mostrate una sola volta alla creazione — copiale immediatamente. Passa la chiave come token Bearer su ogni richiesta:

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

Tratta le chiavi come password: tienile lato server e caricale da variabili di ambiente — non committarle né includerle nel codice client. Se una chiave viene esposta, revocala nella pagina Chiavi API e creane una nuova. Le chiavi revocate hanno effetto immediato e restituiscono 401 per qualsiasi richiesta successiva.

Tutte le richieste API condividono un unico URL di base:

https://api.sonilo.com/v1

I percorsi degli endpoint in questo riferimento sono relativi a questa base. L'API è servita solo tramite HTTPS — le richieste HTTP semplice vengono rifiutate.

Ogni richiesta deve includere un'intestazione Authorization. Gli endpoint di generazione richiedono inoltre un Content-Type:

• Authorization: Bearer sk_… — obbligatoria su ogni richiesta.
• Content-Type: multipart/form-data — per gli endpoint di generazione /v1/text-to-music e /v1/video-to-music, che accettano campi modulo e upload di file. Gli endpoint account sono richieste GET senza corpo.

Sonilo espone due endpoint di generazione e due endpoint account. Segui qualsiasi percorso di seguito per il riferimento completo su richiesta e risposta.

Gli endpoint account restituiscono una singola risposta application/json. Gli endpoint di generazione restituiscono uno stream application/x-ndjson — un oggetto JSON per riga, ciascuno con un campo type. Leggi il corpo riga per riga e analizza ogni riga indipendentemente.

Gli stream di generazione usano un piccolo set stabile di tipi di evento:

• title — titolo della traccia generata; emesso una volta per stream.
• audio_chunk — frammento audio codificato in base64. Raggruppa i chunk per stream_index e concatenali in ordine.
• complete — lo stream è terminato con successo.
• error — la generazione è fallita; contiene code e message.

Consulta il riferimento Video in Musica per lo schema completo degli eventi.

Tutti gli errori restituiscono un corpo JSON con un code e un message. Lo stato HTTP indica la classe di errore:

Il tuo account ha limiti di velocità condivisi che si applicano a tutti gli endpoint di generazione. I limiti predefiniti per il livello standard sono mostrati di seguito.

• Richieste al minuto (RPM): 60
• Attività concorrenti massime: 5

Consulta le Impostazioni per i limiti effettivi del tuo account.

• Il superamento dei limiti di velocità restituisce 429 Too Many Requests
• Il superamento delle dimensioni del file restituisce 413 Request Entity Too Large
• Il superamento della durata del video restituisce 422 Unprocessable Entity

Per richiedere limiti più alti, contatta [email protected].

Segui la guida di Avvio rapido per effettuare la tua prima richiesta in cinque minuti, poi passa al riferimento Video in Musica.

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.