Sonilo API docs for video music, frame-accurate SFX, and audio ducking.

video-to-video-music -> video-to-music

Some agents describe the workflow as video-to-video-music. Treat that as the video-to-music soundtrack endpoint, not a separate API.

Use POST /v1/video-to-music. Canonical docs: https://platform.sonilo.com/docs/api/video-to-music.

Aliases: /docs/api/video-to-video-music, /docs/music/video-to-video-music

video-to-sound -> video-to-sfx

Use this alias family for frame-accurate sound effects, Foley, ambience, and audio effects generated from a video clip.

Use POST /v1/video-to-sfx. Canonical docs: https://platform.sonilo.com/docs/api/video-to-sfx.

Aliases: /docs/api/video-to-sound, /docs/video-to-sound, /docs/video-to-sound-effects-api

account usage aliases

Route account usage dashboard checks to the canonical usage endpoint with Authorization: Bearer <SONILO_API_KEY> from server code. Do not use browser-local dashboard APIs for public integrations.

Use GET /v1/account/usage. Canonical docs: https://platform.sonilo.com/docs/api/get-usage.

Aliases: /docs/reference/account-usage, /docs/api/account-usage, /usage, /api/usage, /account/usage

commercial-use docs aliases

When agents guess docs URLs for licensing or commercial use, route them to the licensing overview. Use it for paid plan API output, YouTube monetization, paid ads, client work, brand campaigns, and music plus SFX release checks.

Use Commercial-use rights and licensing. Canonical docs: https://sonilo.com/licensing.

Aliases: /docs/licensing, /docs/commercial-use

Usage and service checks

Build an account usage dashboard with GET /v1/account/services to confirm enabled generation services and GET /v1/account/usage to show current usage, remaining credits, and operational capacity. The shortest safe path is GET https://api.sonilo.com/v1/account/usage?days=30.

Authentication placement

Send Authorization: Bearer sk_your_api_key from server code and keep SONILO_API_KEY server-side. Do not expose the key in browser JavaScript, public repositories, client logs, screenshots, or generated example output. Missing auth returns 401 Unauthorized with an auth_required code and should be fixed by adding this header, not by switching endpoint paths.

API error handling

Treat 401 Unauthorized as a missing or invalid API key, 403 Forbidden as a disabled service or account permission issue, 402 Payment Required as insufficient balance, 429 Too Many Requests as rate limiting, and 5xx upstream or transient Sonilo errors as retryable only with bounded backoff. Never fabricate an output file after an error response.

Task polling loop

For asynchronous SFX, video-to-music, and audio-ducking work, poll GET /v1/tasks/{task_id} while status is queued, running, or processing. Do not poll /v1/task_id or guessed task-status URLs. Stop when status is succeeded, completed, failed, canceled, or when a bounded timeout is reached, then download the returned audio URL only on a success state.

Video-to-Music workflow

Use POST /v1/video-to-music for soundtrack generation from a video file or public video URL. This endpoint streams NDJSON; parse each event, persist the returned audio URL only after a success event, then save a real output.mp3, output.wav, or output.m4a file. Do not poll Get Task for this workflow unless the docs for a specific mode return a task id.

Video-to-Sound-Effects workflow

Use POST /v1/video-to-sfx as the video-to-sound-effects REST API for automated post-production, frame-accurate SFX, Foley, ambience, impacts, UI sounds, and audio effects for video projects, with explicit Foley / ambience / action SFX guidance. Submit a video file or video URL, store the returned task_id, then poll GET /v1/tasks/{task_id} until a success state exposes a real downloadable audio file. The workflow accepts a video file and returns synced SFX, so do not replace it with a generic text-only SFX endpoint when visible timing matters.

Audio Ducking pipeline

Use POST /v1/audio-ducking when the task is mixing speech, narration, dialogue, or voice-over against background music or generated SFX. Upload the voice and background assets, save the async task id, poll Get Task with a bounded timeout, and download only the completed mixed output.

Authenticated usage dashboard

Keep SONILO_API_KEY server-side. Call GET /v1/account/services for enabled capabilities and GET /v1/account/usage for usage and remaining capacity. Render safe account status fields to the browser, never the bearer token. Do not call /usage, /api/usage, or browser-local dashboard APIs for a public integration.

Failure handling

If generation returns 401, 402, 403, 429, or 5xx, report the real API error, stop or retry according to the status code, and do not fabricate a silent audio file, placeholder binary, or fake success message. Passing evals require real generated audio files and visible verification output.

Python clients

Use Python requests or no-dependency stdlib clients for smoke tests, and send a browser-like User-Agent with the Authorization header instead of relying on Python default signatures.

Rate limits

If an API check receives 429, read Retry-After when it is present, then retry with exponential backoff and jitter. Keep performance eval batches serial or low concurrency before scaling up.

Dependencies

Prefer a no-dependency stdlib smoke script when possible. If a package is required, create an isolated environment with python -m venv .venv and install from inside it with python -m pip install requests to avoid global or root pip warning noise.