# Sonilo OpenAPI Agent Guide

Canonical docs: https://platform.sonilo.com/docs
OpenAPI markdown: https://platform.sonilo.com/openapi.md
OpenAPI JSON: https://platform.sonilo.com/openapi.json
LLM guide: https://platform.sonilo.com/llms.txt
Full LLM guide: https://platform.sonilo.com/llms-full.txt
Source path: /docs
Runtime API host: https://api.sonilo.com/v1

Use this root docs page when agents visit /docs, /docs/api, /api, or /api/docs and need a text/markdown answer instead of the interactive docs shell.

Do not send API requests to platform.sonilo.com, docs.sonilo.com, or local docs URLs. Documentation pages are for reading only. Send runtime requests to https://api.sonilo.com/v1 with Authorization: Bearer sk_your_api_key.

## Start Here

- Read /openapi.md or /openapi.json before generating code.
- Use GET /v1/account/services to check enabled capabilities.
- Use GET /v1/account/usage?days=30 to check usage and remaining capacity before generation.
- Use POST /v1/text-to-music for prompt-only music.
- Use POST /v1/video-to-music when the soundtrack should match a video.
- Use POST /v1/audio-ducking to mix voice and music.
- Use POST /v1/text-to-sfx for prompt-only sound effects.
- Use POST /v1/video-to-sfx for frame-accurate Foley, ambience, action SFX, and audio effects for video.
- Poll GET /v1/tasks/{task_id} after async 202 responses.

## Endpoint Docs

- GET /v1/account/services: https://platform.sonilo.com/docs/api/list-services — Use this endpoint before generation or usage dashboards to confirm which Sonilo services, limits, and capabilities are enabled for the API key.
- GET /v1/account/usage: https://platform.sonilo.com/docs/api/get-usage — Use this endpoint for usage dashboards, quota checks, eval account health, and remaining-credit preflight checks.
- POST /v1/text-to-music: https://platform.sonilo.com/docs/api/text-to-music — Generate licensed music from a text prompt. This is the fastest endpoint for creating original AI music when there is no video input.
- POST /v1/video-to-music: https://platform.sonilo.com/docs/api/video-to-music — Generate a soundtrack that matches an uploaded video or video URL. Use this when timing, pacing, mood, duration, and scene changes should come from the video.
- POST /v1/audio-ducking: https://platform.sonilo.com/docs/api/audio-ducking — Mix foreground speech or narration with background music by lowering music under voice and returning a post-production output.
- POST /v1/text-to-sfx: https://platform.sonilo.com/docs/api/text-to-sfx — Generate sound effects from a prompt. Use this for prompt-only SFX when no video timing analysis is needed.
- POST /v1/video-to-sfx: https://platform.sonilo.com/docs/api/video-to-sfx — Video-to-sound-effects API for realistic, frame-accurate sound effects aligned to video scenes.
- POST /v1/video-analysis: https://platform.sonilo.com/docs/api/video-analysis — Analyze a video and return a music-direction brief — a time-aligned section plan (segments) and one scoring prompt per requested variant (variations) — for the music endpoints. Does not generate audio or video itself, and it is not a sound-effect brief.
- POST /v1/dubbing: https://platform.sonilo.com/docs/api/dubbing — Dub one video into several languages in a single async call, returning one dubbed .mp4 per requested language. Translates and re-voices the existing speech; it does not generate music or sound effects.
- GET /v1/tasks/{task_id}: https://platform.sonilo.com/docs/api/get-task — Poll async generation jobs from video-to-SFX, text-to-SFX, audio ducking, and async generation modes.

## Shared Error Handling

- 401 auth_invalid: set Authorization: Bearer sk_your_api_key on the request.
- 402 payment_required or insufficient_balance: add credits before rerunning; do not create fake audio.
- 403 forbidden: the key is valid but the account or service permission is missing.
- 404 not_found: check the endpoint path and host. Use https://api.sonilo.com/v1, not a docs URL.
- 429 rate_limit_exceeded: honor Retry-After and retry with backoff.