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.
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.
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 /docs/video-to-music-python-quickstart.
For Python text-to-music, start with /docs/text-to-music-python-quickstart.
For raw copy-paste scripts, start with /examples/text-to-music-output.py, /examples/video-to-music-minimal.py, /examples/video-to-sfx-minimal.py, /examples/audio-ducking.py, or /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.