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

このリファレンスのエンドポイントパスはこのベースからの相対パスです。API は HTTPS のみで提供されます — プレーン HTTP リクエストは拒否されます。

すべてのリクエストに Authorization ヘッダーを含める必要があります。生成エンドポイントにはさらに Content-Type が必要です：

• Authorization: Bearer sk_… — すべてのリクエストで必須。
• Content-Type: multipart/form-data — フォームフィールドとファイルアップロードを受け取る生成エンドポイント /v1/text-to-music および /v1/video-to-music で必要。アカウントエンドポイントはボディなしの GET リクエストです。

Sonilo は 2 つの生成エンドポイントと 2 つのアカウントエンドポイントを提供しています。完全なリクエスト・レスポンスリファレンスは以下の各パスをご覧ください。

アカウントエンドポイントは単一の application/json レスポンスを返します。生成エンドポイントは application/x-ndjson ストリームを返します — 1 行につき 1 つの JSON オブジェクトで、各オブジェクトに type フィールドが含まれます。ボディを 1 行ずつ読み取り、各行を個別に解析してください。

生成ストリームは少数の安定したイベントタイプを使用します：

• title — 生成されたトラックのタイトル。ストリームごとに 1 回送出されます。
• audio_chunk — Base64 エンコードされた音声フラグメント。stream_index でチャンクをグループ化し、順番に連結してください。
• complete — ストリームが正常に完了しました。
• error — 生成が失敗しました。code と message が含まれます。

完全なイベントスキーマについては動画から音楽リファレンスをご覧ください。

すべてのエラーは code と message を含む JSON ボディを返します。HTTP ステータスが失敗の種類を示します：

アカウントには、すべての生成エンドポイントに適用される共有レート制限があります。標準ティアのデフォルト制限は以下のとおりです。

• 1 分あたりのリクエスト数 (RPM): 60
• 最大同時実行タスク数: 5

アカウントの実際の制限については設定をご覧ください。

• レート制限を超えると 429 Too Many Requests が返されます
• ファイルサイズ制限を超えると 413 Request Entity Too Large が返されます
• 動画の長さ制限を超えると 422 Unprocessable Entity が返されます

上限の引き上げをご希望の場合は、[email protected] までご連絡ください。

クイックスタートに従って 5 分で最初のリクエストを実行し、次に動画から音楽リファレンスに進んでください。

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.