# Video to Sound API

Canonical docs: https://platform.sonilo.com/docs/api/video-to-sound
Source path: /fr/docs/api/video-to-sound
Runtime API host: https://api.sonilo.com/v1

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.

## Endpoint

POST /v1/video-to-sound

## Summary

Generate a combined soundtrack, music and sound effects mixed together, for a video, delivered as a standalone audio file. Generated audio carries an inaudible provenance watermark.

## Use This For

- Scoring one clip with a music bed AND sound effects in a single call. Prefer this over chaining video-to-music with video-to-sfx, which is billed twice.
- Trailers, ads, social clips, and game captures that need both a soundtrack and scene-synced SFX.
- Keeping the video's own dialogue intelligible under the generated mix (ducking=true).

## Request

- video: file upload. Provide exactly one of video or video_url. Max file size: default 300MB. Max duration: 480 sec.
- video_url: URL input. Provide exactly one of video or video_url. Max file size: default 300MB. Max duration: 480 sec.
- music_prompt: optional style or creative direction for the music bed.
- sfx_prompt: optional overall sound-effects direction.
- segments: optional JSON string with segment prompts.
- preserve_speech: optional boolean. Isolates the source speech and keeps it as the voice source; adds vocals and mux result tracks.
- ducking: optional boolean, default false, free. Keeps the video's own speech and ducks the generated music under it. By default the source speech is not carried into the deliverable. Ignored when preserve_speech is used.
- output_format: wav (default, 16-bit PCM), m4a (AAC) or mp3 (320 kbps CBR). Applies to the combined output_url only; the music, music_processed and sfx stems keep their native formats.

## Response And Errors

- 202 returns task_id and status=processing. This endpoint is async-only.
- Poll GET /v1/tasks/{task_id} every 2-3 seconds.
- On success, download output_url (the mixed track; content_type echoes the delivered MIME), plus the music and sfx stems. music_processed is present only when a voice source was in play (ducking=true or preserve_speech). outputs lists one entry per variant.
- 401 auth_invalid, 402 payment_required or insufficient_balance, 403 forbidden, 404 not_found, and 429 Retry-After should be handled explicitly.

## Example

```bash
curl -X POST "https://api.sonilo.com/v1/video-to-sound" \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "video_url=https://example.com/clip.mp4" \
  -F "music_prompt=tense strings" \
  -F "sfx_prompt=footsteps and distant thunder" \
  -F "output_format=mp3"
```

## 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.

## Endpoint Vocabulary

- GET /v1/account/services
- GET /v1/account/usage
- POST /v1/text-to-music
- POST /v1/video-to-music
- POST /v1/audio-ducking
- POST /v1/text-to-sfx
- POST /v1/video-to-sfx
- POST /v1/video-to-video-sfx
- POST /v1/video-to-sound
- POST /v1/video-to-video-sound
- GET /v1/tasks/{task_id}