API Sonilo

A API Sonilo autentica pedidos com chaves de API. Gere e faça a gestão de chaves na página Chaves de API. As chaves começam por sk_ e são mostradas uma vez na criação — copie-as imediatamente. Passe a chave como token Bearer em cada pedido:

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

Trate as chaves como palavras-passe: mantenha-as no lado do servidor e carregue-as a partir de variáveis de ambiente — nunca as confirme ou envie em código de cliente. Se uma chave for exposta, revogue-a na página Chaves de API e crie uma nova. As chaves revogadas entram em vigor imediatamente e devolvem 401 em qualquer pedido subsequente.

Todos os pedidos de API partilham um único URL base:

https://api.sonilo.com/v1

Os caminhos dos endpoints nesta referência são relativos a esta base. A API é disponibilizada apenas via HTTPS — os pedidos HTTP simples são rejeitados.

Cada pedido deve incluir um cabeçalho Authorization. Os endpoints de geração requerem adicionalmente um Content-Type:

• Authorization: Bearer sk_… — obrigatório em cada pedido.
• Content-Type: multipart/form-data — para os endpoints de geração /v1/text-to-music e /v1/video-to-music, que recebem campos de formulário e uploads de ficheiros. Os endpoints de conta são pedidos GET sem body.

Sonilo disponibiliza dois endpoints de geração e dois endpoints de conta. Siga qualquer caminho abaixo para a referência completa de pedido e resposta.

Os endpoints de conta devolvem uma única resposta application/json. Os endpoints de geração devolvem um fluxo application/x-ndjson — um objeto JSON por linha, cada um com um campo type. Leia o body linha a linha e analise cada linha independentemente.

Os fluxos de geração utilizam um conjunto pequeno e estável de tipos de eventos:

• title — título da faixa gerada; emitido uma vez por fluxo.
• audio_chunk — fragmento de áudio codificado em base64. Agrupe os fragmentos por stream_index e concatene por ordem.
• complete — o fluxo terminou com sucesso.
• error — a geração falhou; contém code e message.

Consulte a referência de Vídeo para Música para o esquema completo de eventos.

Todos os erros devolvem um body JSON com code e message. O estado HTTP indica a classe de falha:

A sua conta tem limites de taxa partilhados que se aplicam a todos os endpoints de geração. Os limites predefinidos para o nível padrão são apresentados abaixo.

• Pedidos por minuto (RPM): 60
• Máximo de tarefas simultâneas: 5

Consulte as Definições para os limites reais da sua conta.

• Exceder os limites de taxa devolve 429 Too Many Requests
• Exceder o tamanho do ficheiro devolve 413 Request Entity Too Large
• Exceder a duração do vídeo devolve 422 Unprocessable Entity

Para solicitar limites mais altos, entre em contato pelo [email protected].

Siga o Início Rápido para fazer o seu primeiro pedido em cinco minutos, depois avance para a referência de Vídeo para 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.