API de Sonilo

La API de Sonilo autentica las solicitudes con claves API. Genera y administra claves desde la página Claves API. Las claves comienzan con sk_ y se muestran una sola vez al crearse — cópialas de inmediato. Envía la clave como token Bearer en cada solicitud:

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

Trata las claves como contraseñas: mantenlas del lado del servidor y cárgalas desde variables de entorno — nunca las confirmes en el repositorio ni las incluyas en el código del cliente. Si una clave queda expuesta, revócala en la página Claves API y crea una nueva. Las claves revocadas tienen efecto inmediato y devuelven 401 en cualquier solicitud posterior.

Todas las solicitudes a la API comparten una única URL base:

https://api.sonilo.com/v1

Las rutas de los endpoints en esta referencia son relativas a esta base. La API solo se sirve mediante HTTPS — las solicitudes HTTP sin cifrar son rechazadas.

Cada solicitud debe incluir un encabezado Authorization. Los endpoints de generación además requieren un Content-Type:

• Authorization: Bearer sk_… — requerido en cada solicitud.
• Content-Type: multipart/form-data — para los endpoints de generación /v1/text-to-music y /v1/video-to-music, que reciben campos de formulario y cargas de archivos. Los endpoints de cuenta son solicitudes GET sin cuerpo.

Sonilo expone dos endpoints de generación y dos endpoints de cuenta. Sigue cualquiera de las rutas a continuación para la referencia completa de solicitud y respuesta.

Los endpoints de cuenta devuelven una única respuesta application/json. Los endpoints de generación devuelven un stream application/x-ndjson — un objeto JSON por línea, cada uno con un campo type. Lee el cuerpo línea por línea y analiza cada línea de forma independiente.

Los streams de generación usan un conjunto pequeño y estable de tipos de evento:

• title — título de la pista generada; se emite una vez por stream.
• audio_chunk — fragmento de audio codificado en base64. Agrupa los fragmentos por stream_index y concaténalos en orden.
• complete — el stream finalizó exitosamente.
• error — la generación falló; contiene code y message.

Consulta la referencia de Video a Música para el esquema completo de eventos.

Todos los errores devuelven un cuerpo JSON con un code y un message. El estado HTTP indica la clase de fallo:

Tu cuenta tiene límites de frecuencia compartidos que se aplican a todos los endpoints de generación. A continuación se muestran los límites predeterminados para el nivel estándar.

• Solicitudes por minuto (RPM): 60
• Máximo de tareas concurrentes: 5

Consulta Configuración para ver los límites reales de tu cuenta.

• Superar los límites de frecuencia devuelve 429 Too Many Requests
• Superar el tamaño de archivo devuelve 413 Request Entity Too Large
• Superar la duración del video devuelve 422 Unprocessable Entity

Para solicitar límites más altos, escribe a [email protected].

Sigue el Inicio rápido para realizar tu primera solicitud en cinco minutos, luego pasa a la referencia de Video a Música.

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.