# Video to Video (Sound) API

Canonical docs: https://platform.sonilo.com/docs/api/video-to-video-sound
Source path: /fr/docs/api/video-to-video-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-video-sound

## Summary

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. Generated audio carries an inaudible provenance watermark.

## Use This For

- Delivering a finished, fully scored clip (music bed plus scene-synced SFX) as one mp4.
- Trailers, ads, social clips, and game captures where the result should be ready to publish.
- Keeping the original dialogue or the whole original track under the generated mix (keep_original_sound, ducking).

## 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 only that as the voice source. Superseded by keep_original_sound when both are set.
- keep_original_sound: optional boolean, default false. Keeps the whole source audio track as the voice source instead of isolated vocals or no voice source at all.
- ducking: optional boolean, default false, free. With a voice source, selects a dynamically ducked mix instead of the default static vocal-forward mix. No effect without a voice source. Best-effort.
- No output_format field: the result is always the mixed track muxed into an mp4, so no content_type is reported.

## 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 video.url: the source video with the mixed track muxed in. By default the source audio is removed entirely and no music_processed stem is produced. videos 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-video-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 "keep_original_sound=true" \
  -F "ducking=true"
```

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