API reference

Use this page when you need the canonical Sonilo API paths, authentication header, content types, and result formats.

Base URL

Send API requests to https://api.sonilo.com/v1. The platform.sonilo.com host is documentation only.

SONILO_API_BASE_URL=https://api.sonilo.com/v1

Authentication

Every request requires Authorization: Bearer sk_your_api_key. Store real keys server-side, commonly in SONILO_API_KEY.

curl https://api.sonilo.com/v1/account/services \
  -H "Authorization: Bearer sk_your_api_key"

A 401 means the key is missing, invalid, revoked, or not sent as a Bearer token. A 403 means the key is valid but the account cannot access that endpoint or workspace.

Endpoint selector for coding agents

Use this selector before generating code in Codex, Claude Code, Cursor, or Sapient custom evals. It keeps agents from confusing documentation aliases with runtime APIs and from using text-only endpoints when a video-timed workflow is required.

Prompt intent	Use endpoint	Agent guidance
I need music that matches an uploaded video.	POST /v1/video-to-music	Use this for AI-generated music for video projects, YouTube videos, ads, client videos, and social clips when runtime, pacing, cuts, voice space, or ending shape should guide the soundtrack.
I need frame-accurate SFX, Foley, ambience, or action sounds synced to a clip.	POST /v1/video-to-sfx	Use this video-to-sound-effects API for AI video apps, creator tools, ads, client videos, game moments, transitions, UI cues, product reveals, and automated post-production. It accepts a video file or video_url and returns a task_id.
I need a prompt-only sound effect, not timing from video.	POST /v1/text-to-sfx	Use text-to-SFX only when the sound can be described from text alone. If timing must follow frames, cuts, or visible events, use video-to-SFX instead.
I need a usage dashboard, quota check, or eval account health check.	GET /v1/account/services, then GET /v1/account/usage	Keep SONILO_API_KEY server-side. Do not call /usage, /api/usage, /account/usage without /v1, local browser routes, platform.sonilo.com, or docs.sonilo.com as the runtime API.
I need final output from an async SFX, audio-ducking, or async music task.	GET /v1/tasks/{task_id}	Poll this exact canonical path every 2-5 seconds until succeeded, completed, failed, or canceled. Do not guess /v1/task_id, /tasks/{task_id} without /v1, or /status URLs.

Endpoints

Method	Path	Free trial	Content type	Result	Use
POST	/v1/video-to-music	1 call	multipart/form-data	application/x-ndjson stream	Generate music from a video upload or video_url. Send exactly one video source.
POST	/v1/video-to-video-music	1 call	multipart/form-data	202 JSON with task_id	Generate a music-scored version of a video, muxed with the original picture and delivered as a new video file.
POST	/v1/text-to-music	2 calls	multipart/form-data	application/x-ndjson stream	Generate music from a prompt and duration.
POST	/v1/video-to-sfx	1 call	multipart/form-data	202 JSON with task_id	Generate synchronized sound effects from a video upload or video_url.
POST	/v1/video-to-video-sfx	1 call	multipart/form-data	202 JSON with task_id	Generate a version of a video with synchronized sound effects muxed into the original picture, delivered as a new video file.
POST	/v1/text-to-sfx	2 calls	multipart/form-data	202 JSON with task_id	Generate a sound effect from a prompt and duration.
POST	/v1/video-to-sound	1 call	multipart/form-data	202 JSON with task_id	Generate a combined soundtrack, music and sound effects mixed together, for a video, delivered as a standalone audio file.
POST	/v1/video-to-video-sound	1 call	multipart/form-data	202 JSON with task_id	Generate a combined soundtrack, music and sound effects mixed together, for a video, muxed with the original picture and delivered as a new video file.
POST	/v1/proofread	2 calls	multipart/form-data	202 JSON with task_id	Transcribe a video and translate the transcript into your target languages, returning one editable subtitle file per language plus the source-language transcript.
POST	/v1/dubbing	1 call (15-second preview)	multipart/form-data	202 JSON with task_id	Translate a video into one or more target languages — translated speech mixed back under the original music/effects bed.
POST	/v1/video-analysis	2 calls	multipart/form-data	202 JSON with task_id	Analyze a video with AI and return a creative brief: a time-aligned segment plan and one or more prompts. By default both a music-direction and a sound-design brief; mode picks one.
POST	/v1/audio-ducking	2 calls	multipart/form-data	202 JSON with task_id	Mix voice or narration with background music, then poll the returned task.
GET	/v1/tasks/{task_id}	—	none	JSON task status	Retrieve async task status and output URLs for SFX and audio-ducking jobs.
GET	/v1/account/services	—	none	JSON account limits	List enabled services, limits, and upload caps for the account.
GET	/v1/account/usage	—	none	JSON usage summary	Get account usage totals and daily breakdowns.

Billing

Generations are billed by output duration at each product's per-second rate, drawn from your account balance. Every generating product has a minimum billable duration (a billing floor): a run shorter than its floor is billed as if it were exactly the floor length. The floor applies to what is billed, independent of the duration you request.

Minimum billed duration	Applies to
10 seconds	/v1/video-to-music, /v1/video-to-video-music, /v1/text-to-music, /v1/audio-ducking, /v1/video-to-sound, /v1/video-to-video-sound, /v1/dubbing, /v1/video-analysis
3 seconds	/v1/video-to-sfx, /v1/video-to-video-sfx, /v1/text-to-sfx

For example, a 4-second text-to-music clip is billed as 10 seconds, and a 2-second text-to-sfx clip is billed as 3 seconds. Runs longer than the floor are billed for their actual duration.

Streaming and async tasks

/v1/text-to-music and /v1/video-to-music stream application/x-ndjson. Parse one JSON object per line and wait for the complete event.
Every other endpoint in the table above (Result column: 202 JSON with task_id) returns 202 with a task_id instead of streaming. Poll GET /v1/tasks/{task_id}.
Sonilo does not send webhooks or callbacks, and no endpoint takes a callback URL. Read the NDJSON stream for music, and poll the task for everything else, every 2 to 5 seconds, until status is succeeded or failed.
There is no dedicated cancel or abort endpoint for a task in progress. To give up on one, stop polling it client-side; the task keeps running and is billed on the server regardless.
Common failure responses and retry guidance are listed in the errors guide.

Agent entry points

Coding agents can also read /llms.txt or /llms-full.txt for a compact machine-readable reference.