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.

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/dubbing	0 calls	multipart/form-data	202 JSON with task_id	Dub a video into one or more target languages, translated speech mixed back under the original music/effects bed.
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
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.
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.