account

Sonilo アカウント

Sonilo アカウントで利用できる機能と使用量を確認する、無料の読み取り専用ツールが 2 つあります。どちらも課金は発生しません。

セットアップ： setup-api-key スキルを参照してください。

トランスポート：MCP または CLI

セッション開始時にどちらかを選び、途中で切り替えないでください。1 つのジョブ内で 2 つを混在させないでください。また、選択した方法を告げる必要はありません。

1. このセッションで Sonilo MCP ツール（get_account_services など）が表示されている場合 — それらを使用してください。これが推奨される方法です。シェルは不要で、非常に長い生成でも機能する唯一の方法です。入力値ではなく認証に失敗した場合、このセッションではこのトランスポートを使用できません。再試行せず、2 に進んでください。
2. 使用可能な Sonilo MCP ツールがなく、sonilo account が終了コード 0 を返す場合 — 以下の CLI コマンドを使用してください。同じ API、同じアカウント、同じ認証情報ファイルを使用します。sonilo whoami ではなく、sonilo account で確認してください。サインアウト中でも whoami は終了コード 0 を返すため、2 つの状態を区別できません。
3. どちらも使用できない場合 — 処理を停止し、setup-api-key スキルを実行してください。回避策として curl で api.sonilo.com を呼び出さないでください。どちらのトランスポートも、単純なリクエストでは対応できないアップロード、ポーリング、再試行を処理します。

クイックスタート

MCP ツール呼び出し（推奨）

get_account_services()

get_usage(days=7)

Python（pip install sonilo）

from sonilo import Sonilo

client = Sonilo()  # reads SONILO_API_KEY

services = client.account.services()
usage = client.account.usage(days=7)

JavaScript / TypeScript（npm install sonilo）

import { SoniloClient } from "sonilo";

const client = new SoniloClient(); // reads SONILO_API_KEY

const services = await client.account.services();
const usage = await client.account.usage({ days: 7 });

CLI（npm install -g sonilo-cli または pip install sonilo-cli）

sonilo account
sonilo usage --days 7

sonilo account はアカウントの JSON を標準出力に出力します。また、アカウントに無料トライアルの利用枠がある場合は、概要を 1 行、標準エラー出力に表示します（Free trial: text-to-music 1/2 left, ...）。そのため、sonilo account | jq .trial では引き続きクリーンな JSON を取得できます。

cURL（MCP ホストを使わない REST API の直接呼び出し）

curl "https://api.sonilo.com/v1/account/services" -H "Authorization: Bearer $SONILO_API_KEY"
curl "https://api.sonilo.com/v1/account/usage?days=7" -H "Authorization: Bearer $SONILO_API_KEY"

ツール

ツール	説明
get_account_services()	利用可能なサービス、レート制限／同時実行数の上限、割引率、動画の最大アップロードサイズ、および（アカウントに付与されている場合）サービスごとの無料トライアル利用枠。
get_usage(days=30)	使用量の概要と日ごとの内訳。days は 1～365 です。

get_account_services のレスポンス形式

{
  "available_services": [...],
  "rpm_limit": 60,
  "concurrency_limit": 4,
  "discount_factor": 1.0,
  "max_upload_size_mb": 300,
  "trial": {
    "text_to_music": {"granted": 2, "used": 0, "remaining": 2},
    "video_to_music": {"granted": 1, "used": 1, "remaining": 0}
  }
}

• 無料トライアルの利用枠がないアカウントでは、trial キーは完全に存在しません。これはエラーではなく、「通常どおり課金される」と解釈してください。
• trial オブジェクトが存在していても、特定のサービスのエントリーがない場合、そのサービスには無料トライアルの利用枠がなく、最初の呼び出しから課金されます。dubbing には granted: 1 と表示されますが、これは最初の単一言語の呼び出しの15 秒間のプレビューであり、完全な翻訳ではありません。auto-dubbing スキルを参照してください。
• trial[service].remaining が 0 の場合、そのサービスを呼び出すと 402 trial_exhausted エラーになります。このエラーは再試行しても解決しません。

ワークフローのヒント

• 生成する前に確認してください。 有料ツール（text_to_music、video_to_music、text_to_sfx、video_to_sfx、video_to_video_music、video_to_video_sfx、video_to_sound、video_to_video_sound、dubbing、proofread、audio_ducking）を呼び出す前に、アカウントに無料利用枠が残っているか不明な場合は、get_account_services() を呼び出してください。trial[service].remaining が 0 の場合は、そのサービスの無料トライアルを使い切っており、続けるには支払い方法が必要であることをユーザーに伝えてください。呼び出しを試みて、生の 402 エラーをそのまま表示するだけにしないでください。
• dubbing の無料利用は15秒のプレビューであり、動画全体ではありません。 スクリプトなしの最初の単一言語の呼び出しのみ無料で、最初の15秒だけが翻訳されます。複数の言語、スクリプト、およびそれ以降の呼び出しはすべて課金対象です。自動吹き替えスキルの料金に関する警告を参照してください。
• proofread にも無料トライアル枠があります — 2回です — dubbing と同様、その後は言語ごとに課金されます。proofreadスキルを参照してください。
• 利用状況の照合： 生成がタイムアウトしたり失敗したりした場合、何も起きなかったと思い込まず、get_usage を使ってバックエンドで実際に処理が完了し、課金されたかどうかを確認してください。
• レート制限（429）に達しましたか？ get_account_services() は rpm_limit と concurrency_limit を返すため、ユーザーにどの上限に達したかを伝えられます。

エラー処理

どちらのツールも、認証が必要なシンプルな GET リクエストです。無効またはローテーション済みのキーでは 401 が返されます。get_usage はリクエストを送信する前に、クライアント側で days（1～365）も検証します。