Sonilo API

Sonilo API 使用 API 金鑰驗證請求。從 API 金鑰頁面生成及管理金鑰。金鑰以 sk_ 開頭，建立時僅顯示一次 — 請立即複製。在每次請求時以 Bearer Token 形式傳遞金鑰：

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。

完整事件結構請參閱 影片轉音樂參考文件。

所有錯誤均回傳包含 code 和 message 的 JSON 主體。HTTP 狀態碼表示失敗類別：

您的帳戶有適用於所有生成端點的共用速率限制。標準方案的預設限制如下所示。

• 每分鐘請求數（RPM）：60
• 最大並行任務數：5

請參閱 設定查看您帳戶的實際限制。

• 超過速率限制將回傳 429 Too Many Requests
• 超過檔案大小將回傳 413 Request Entity Too Large
• 超過影片時長將回傳 422 Unprocessable Entity

如需提高限額，請聯絡 [email protected]。

Audio generated through the Sonilo API can be used commercially — in your own product and by your end users, including ads, client work and monetized channels.

The API is billed pay-as-you-go from a prepaid balance on platform.sonilo.com, not through a sonilo.com subscription plan, so no Pro or Premium plan is needed; Enterprise API customers follow their enterprise agreement.

For film, TV or broadcast use, or for releasing tracks to Spotify, Apple Music or other streaming services, contact sales first. Contact sales. The full answer is in the Sonilo licensing help centre.

按照 快速入門在五分鐘內完成您的首次請求，然後深入了解 影片轉音樂參考文件。

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.