API Sonilo

L'API Sonilo authentifie les requêtes avec des clés API. Générez et gérez les clés depuis la page Clés API. Les clés commencent par sk_ et sont affichées une seule fois à la création — copiez-les immédiatement. Transmettez la clé en tant que token Bearer à chaque requête :

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

Traitez les clés comme des mots de passe : conservez-les côté serveur et chargez-les depuis des variables d'environnement — ne les committez jamais et ne les incluez pas dans le code client. Si une clé est exposée, révoquez-la sur la page Clés API et créez-en une nouvelle. Les clés révoquées prennent effet immédiatement et retournent 401 pour toute requête ultérieure.

Toutes les requêtes API partagent une URL de base unique :

https://api.sonilo.com/v1

Les chemins d'endpoint dans cette référence sont relatifs à cette base. L'API est uniquement accessible via HTTPS — les requêtes HTTP simples sont rejetées.

Chaque requête doit inclure un en-tête Authorization. Les endpoints de génération nécessitent également un Content-Type :

• Authorization: Bearer sk_… — obligatoire pour chaque requête.
• Content-Type: multipart/form-data — pour les endpoints de génération /v1/text-to-music et /v1/video-to-music, qui acceptent des champs de formulaire et des fichiers téléversés. Les endpoints de compte sont des requêtes GET sans corps.

Sonilo expose deux endpoints de génération et deux endpoints de compte. Suivez n'importe quel chemin ci-dessous pour la référence complète des requêtes et des réponses.

Les endpoints de compte retournent une seule réponse application/json. Les endpoints de génération retournent un flux application/x-ndjson — un objet JSON par ligne, chacun portant un champ type. Lisez le corps ligne par ligne et analysez chaque ligne indépendamment.

Les flux de génération utilisent un petit ensemble stable de types d'événements :

• title — titre de la piste générée ; émis une fois par flux.
• audio_chunk — fragment audio encodé en base64. Regroupez les fragments par stream_index et concaténez-les dans l'ordre.
• complete — le flux s'est terminé avec succès.
• error — la génération a échoué ; contient code et message.

Consultez la référence Vidéo vers musique pour le schéma complet des événements.

Toutes les erreurs retournent un corps JSON avec un code et un message. Le statut HTTP indique la classe d'échec :

Votre compte dispose de limites de débit partagées qui s'appliquent à tous les endpoints de génération. Les limites par défaut pour le niveau standard sont indiquées ci-dessous.

• Requêtes par minute (RPM) : 60
• Tâches simultanées max : 5

Consultez les Paramètres pour les limites réelles de votre compte.

• Dépasser les limites de débit retourne 429 Too Many Requests
• Dépasser la taille de fichier retourne 413 Request Entity Too Large
• Dépasser la durée vidéo retourne 422 Unprocessable Entity

Pour demander des limites plus élevées, contactez [email protected].

Suivez le Démarrage rapide pour effectuer votre première requête en cinq minutes, puis plongez dans la référence Vidéo vers musique.

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.