# Video to Music API

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

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

## Request

- video: file upload. Provide exactly one of video or video_url.
- video_url: URL input. Provide exactly one of video or video_url.
- 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
- GET /v1/tasks/{task_id}