# Video Analysis API

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

## Summary

Analyze a video and return a creative brief — a time-aligned segment plan (segments) and one prompt per requested variant (variations). mode picks which brief: both (the default) returns one of each, music or sfx returns just that one. Does not generate audio or video itself.

## Use This For

- Turning an uploaded or linked video into structured music direction before calling video-to-music, video-to-video-music, or text-to-music.
- Turning the same video into shot-by-shot sound-effect direction (mode=sfx) before calling video-to-sfx, video-to-video-sfx, or text-to-sfx.
- Getting scene-level segment timing (start, end, label, prompt) without hand-authoring a segments JSON string.
- Getting several distinct creative directions (variations) to choose from before spending credits on generation.

## 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.
- prompt: optional string, max 2000 characters.
- variants_num: optional integer, 1-5, default 1. Cost scales linearly with the count.
- mode: optional string, both, music or sfx, default both. both writes a music-direction brief (segments/variations, song sections) and a sound-design brief (sfx_segments/sfx_prompt, shot-sized spans) in one call; music or sfx writes just that one. All three cost the same.

## Response And Errors

- 202 returns task_id and status=processing.
- Poll GET /v1/tasks/{task_id} every 2-3 seconds.
- On success, read mode (echoed from the request), segments and variations (one prompt per requested variant), plus sfx_segments and sfx_prompt in both mode (sfx_prompt is one string, authored once regardless of variants_num). There is no audio.url, video.url, or output_url — this endpoint returns a written brief, not generated media. negative_prompt is not part of the response.
- A failed task's error.code is typically ANALYSIS_FAILED, though SOURCE_DOWNLOAD_FAILED (the source video could not be fetched at all — transient, so retry), SOURCE_PROCESSING_FAILED (the source video was fetched but could not be prepared for analysis — typically an extreme resolution or bitrate; re-encode to a lighter file), TRANSFER_FAILED, INVALID_PAYLOAD, or GENERATION_FAILED are also possible depending on where the failure occurred.
- 401 auth_invalid, 402 payment_required or insufficient_balance, 403 forbidden, 404 not_found, 422 unprocessable_entity (over-limit duration or no video track), and 429 Retry-After should be handled explicitly.

## Example

```bash
curl -X POST "https://api.sonilo.com/v1/video-analysis" \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "video_url=https://example.com/clip.mp4" \
  -F "prompt=upbeat, driving energy for an action montage"
```

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