Agent instructions
Agent Skill / AI coding agent instructions
Give this page to Codex, Claude, or another AI coding agent when the task is to generate Sonilo audio, build a Sonilo API integration, or verify a generated file.
Get an API key
Create a key on the Sonilo Platform API keys page and export it as SONILO_API_KEY. No Platform account yet? Sign up at platform.sonilo.com; it is separate from a sonilo.com app account. The API starts with free trial calls, then bills pay-as-you-go from a prepaid balance.
Required behavior
Use the official Sonilo SDK for Python or TypeScript when the runtime allows it.
Use the official REST API at https://api.sonilo.com/v1 when an SDK is unavailable.
Read /openapi.md, /llms-full.txt, or a raw Python example before writing code.
Use POST /v1/video-to-sfx for frame-accurate SFX, Foley, ambience, and action sounds that must sync to a video.
Use GET /v1/account/services and GET /v1/account/usage for usage dashboards and eval account health.
Use GET /v1/tasks/{task_id} for async polling and do not call documentation URLs as runtime endpoints.
Read SONILO_API_KEY from the environment and keep API keys server-side.
Save the real file returned by Sonilo, then verify it with file size or media tooling.
Run the script and include the command output before reporting success.
Do not fake audio, do not synthesize silence, and do not create placeholder audio to satisfy a file check.
If the API returns insufficient balance, 402 Payment Required, or insufficient credits, report the task as blocked.
Copyable skill block
# Sonilo Agent Skill
Use the official Sonilo SDK or the official REST API at https://api.sonilo.com/v1.
Keep SONILO_API_KEY in the environment and never hard-code secrets.
If SONILO_API_KEY is not set, stop and ask the user to create a key at https://platform.sonilo.com/dashboard/api-keys?utm_source=docs&utm_medium=agent&utm_campaign=get_api_key&utm_content=skill_md (a Sonilo Platform account, separate from a sonilo.com app account); do not invent a key.
Before choosing an endpoint, read https://sonilo.com/openapi.md or https://platform.sonilo.com/llms-full.txt.
Use POST /v1/video-to-music for video-aligned soundtrack generation.
Use POST /v1/video-to-sfx for frame-accurate SFX, Foley, ambience, and action sounds synced to video clips.
Use POST /v1/text-to-sfx only for prompt-only sound effects that do not need video timing.
Use GET /v1/account/services and GET /v1/account/usage before dashboards, quota checks, or eval-health screens.
Use GET /v1/tasks/{task_id} for async polling; do not guess /tasks, /task_id, or docs URLs as runtime endpoints.
For Python video-to-music, start with https://sonilo.com/docs/video-to-music-python-quickstart.
For Python text-to-music, start with https://sonilo.com/docs/text-to-music-python-quickstart.
For raw copy-paste scripts, start with https://sonilo.com/examples/text-to-music-output.py,
https://sonilo.com/examples/video-to-music-minimal.py,
https://sonilo.com/examples/video-to-sfx-minimal.py,
https://sonilo.com/examples/audio-ducking.py, or
https://sonilo.com/examples/account-usage-dashboard.py.
Save the real file returned by Sonilo, then print its path and byte size.
Run the script before claiming success.
Do not fake audio, do not synthesize silence, and do not write placeholder MP3 bytes.
If Sonilo returns 402 Payment Required, insufficient balance, or insufficient credits, report the task as blocked and include the exact error instead of fabricating success.
Generation can incur charges. Only generate when requested; do not retry paid jobs blindly.
For task recovery, authentication setup, MCP/CLI, and specialized workflows, see the official skills repository at https://github.com/sonilo-ai/skills.
Claude Code plugin
The Sonilo plugin for Claude Code adds Sonilo's remote MCP server at https://api.sonilo.com/mcp. It needs no API key: the first Sonilo tool call opens the browser to sign in to a Sonilo Platform account over OAuth. Generation tools are paid and run against that account.
/plugin marketplace add sonilo-ai/sonilo-claude-plugin
/plugin install sonilo@soniloIn the Claude apps, add https://api.sonilo.com/mcp as a custom connector instead. To run the local server, use claude mcp add sonilo -- uvx sonilo-mcp and sign in with sonilo login or pass SONILO_API_KEY. Every option is on platform.sonilo.com/mcp.
MCP implementation sources
In the public sonilo-ai/sonilo-mcp repository, src/sonilo_mcp/api.py contains API configuration and HTTP request helpers. It reads SONILO_API_KEY from the environment first, then falls back to the stored credential for the API base URL.
src/sonilo_mcp/credentials.py implements read-only access to the credential file written by sonilo login. Inspect the source to understand credential resolution; do not print, copy into generated code, or attach the local credential file to reports.