account

Sonilo 账户

两个免费的只读工具，用于查看 Sonilo 账户可以使用哪些功能以及使用量。两者都不会产生费用。

**设置：**请参阅 setup-api-key 技能。

传输方式：MCP 或 CLI

在会话开始时选择一种方式，并始终使用该方式。不要在同一项任务中混用两种方式，也不要说明你的选择。

1. 本会话中可见 Sonilo MCP 工具（get_account_services 等）——使用这些工具。这是首选方式：无需使用 shell，也是唯一能在超长生成过程中持续可用的方式。如果调用因身份验证失败而失败（而不是因输入参数失败），则此传输方式在本会话中不可用：转到第 2 项，不要重试。
2. 没有可用的 Sonilo MCP 工具，但 sonilo account 执行后退出码为 0——使用下方的 CLI 命令。API、账户和凭据文件都相同。使用 sonilo account 探测，不要使用 sonilo whoami：即使处于未登录状态，whoami 也会以 0 退出，因此无法区分这两种状态。
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 输出到 stdout；如果账户有免费试用额度，还会将一行摘要输出到 stderr（Free trial: text-to-music 1/2 left, ...）——因此 sonilo account | jq .trial 仍会得到纯净的 JSON。

cURL（原始 REST API，无 MCP 主机）

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 秒。多种语言、脚本以及之后的每次调用都需要付费。请参阅 auto-dubbing 技能中的费用警告。
• proofread 提供免费试用额度——2 次；与 dubbing 一样，超过额度后按语言计费。请参阅 proofread 技能。
• **用量核对：**如果生成超时或失败，请使用 get_usage 确认后端是否实际完成了任务（并已收费），而不要假定什么都没发生。
• 遇到速率限制（429）？get_account_services() 会报告 rpm_limit 和 concurrency_limit，以便告知用户触及了哪些上限。

错误处理

这两个工具都是简单的身份验证 GET 请求——如果密钥无效或已轮换，预期会收到 401。get_usage 还会在客户端验证 days（1–365），然后再发出请求。