Sonilo API

Sonilo API 使用 API 密钥对请求进行认证。在 API 密钥 页面生成和管理密钥。密钥以 sk_ 开头，创建时仅显示一次——请立即复制。在每次请求中以 Bearer 令牌形式传入密钥：

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

请像对待密码一样保管密钥：仅在服务器端使用，并从环境变量中加载——切勿将其提交到代码仓库或包含在客户端代码中。如果密钥泄露，请在 API 密钥 页面立即撤销并创建新密钥。撤销立即生效，后续任何使用该密钥的请求均会返回 401。

所有 API 请求共享同一基础 URL：

https://api.sonilo.com/v1

本参考文档中的端点路径均相对于此基础 URL。API 仅通过 HTTPS 提供服务——纯 HTTP 请求会被拒绝。

每个请求都必须包含 Authorization 请求头。生成端点还需要 Content-Type：

• Authorization: Bearer sk_… — 每次请求均为必填。
• Content-Type: multipart/form-data — 用于生成端点 /v1/text-to-music 和 /v1/video-to-music，这些端点接受表单字段和文件上传。账户端点为 GET 请求，无请求体。

Sonilo 提供两个生成端点和两个账户端点。点击以下任意路径查看完整的请求和响应参考。

账户端点返回单个 application/json 响应。生成端点返回 application/x-ndjson 流——每行一个 JSON 对象，每个对象包含 type 字段。逐行读取响应体并独立解析每一行。

生成流使用一组小而稳定的事件类型：

• title — 生成的曲目标题；每次流输出一次。
• audio_chunk — Base64 编码的音频片段。按 stream_index 分组并按顺序拼接。
• complete — 流已成功结束。
• error — 生成失败；包含 code 和 message。

请参阅 视频转音乐 参考文档以了解完整的事件 Schema。

所有错误均返回包含 code 和 message 的 JSON 响应体。HTTP 状态码表示错误类别：

您的账户有适用于所有生成端点的共享速率限制。标准套餐的默认限制如下所示。

• 每分钟请求数（RPM）：60
• 最大并发任务数：5

请在 设置 中查看您账户的实际限制。

• 超出速率限制将返回 429 Too Many Requests
• 超出文件大小限制将返回 413 Request Entity Too Large
• 超出视频时长限制将返回 422 Unprocessable Entity

如需提高限额，请联系 [email protected]。

按照 快速开始 在五分钟内完成您的第一次请求，然后深入 视频转音乐 参考文档。

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.