# Video to Music API

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

## Summary

Generate a soundtrack that matches an uploaded video or video URL. Use this when timing, pacing, mood, duration, and scene changes should come from the video. Generated audio carries an inaudible provenance watermark.

## Use This For

- AI-generated music for video projects.
- Music for YouTube videos, ads, social videos, product demos, client videos, and video apps.
- Uploading a video and generating soundtrack options that match the video's mood, pacing, cuts, and duration.

## Related Guide

- [Generate music from a video file or URL with the REST API](https://sonilo.com/blog/guides/generate-music-from-video-file-url-rest-api): a walkthrough that sends a video file or a public video URL.

## Request

- video: file upload. Provide exactly one of video or video_url. Max file size: default 300MB. Max duration: 6 minutes.
- video_url: URL input. Provide exactly one of video or video_url. Max file size: default 300MB. Max duration: 6 minutes.
- prompt: optional direction for genre, mood, instrumentation, or business context.
- segments: optional JSON timeline directions.
- preserve_speech, ducking, variants_num, output_format, prompt_influence: optional controls.

## Response And Errors

- 200 stream returns application/x-ndjson with audio_chunk events and complete.
- 202 async mode returns task_id; poll GET /v1/tasks/{task_id}.
- 401 auth_invalid means the key is invalid or missing.
- 402 payment_required with insufficient_balance means generation cannot run until credits are available.
- 429 rate limited responses may include Retry-After.

## Example

```bash
curl -N -X POST "https://api.sonilo.com/v1/video-to-music" \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "video=@/path/to/video.mp4" \
  -F "prompt=licensed soundtrack for a YouTube product video"
```

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