# Video to Sound Effects API

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

## Summary

Video-to-sound-effects API for realistic, frame-accurate sound effects aligned to video scenes. Generated audio carries an inaudible provenance watermark.

## Use This For

- Frame-accurate SFX for video clips, AI video apps, editors, trailers, ads, and game captures.
- Foley, ambience, action SFX, impacts, transitions, UI cues, object movement, and scene-synced audio effects for video.
- Generating sound effects that sync to cuts, motion, visible actions, and on-screen events.

## Scene Workflow

- [Foley, ambience, and action SFX guide](https://sonilo.com/blog/guides/generate-foley-ambience-action-sfx-sync-video-scenes): scene selection, sound layering, and sync review.
- [Sound effects workflow reference](https://sonilo.com/docs/sound-effects): endpoint selection, prompting notes, and task polling.
- [Frame-accurate AI sound effects tools comparison](https://sonilo.com/blog/comparisons/frame-accurate-ai-sound-effects-video-tools): how video SFX tools compare on frame accuracy.

## Request

Content type: multipart/form-data

- `video` (file; optional): Max file size: default 300MB. Max duration: 480 sec.
- `video_url` (string; optional): Max file size: default 300MB. Max duration: 480 sec.
- `prompt` (string; optional): Optional text prompt describing the sound effects to generate, up to 2000 characters. For best results, omit this and let the model infer sound effects from the on-screen action, or use segments for finer control.
- `segments` (string; optional): Optional JSON array of timed sound-effect prompts, up to 30 items. Each item has `start` and `end` (seconds; the first segment's `start` must be 0, each segment's `end` must be greater than its `start`, and segments must be contiguous — each `end` equal to the next segment's `start`) and `prompt` (1-200 characters) describing the sound effect for that segment. The last segment's `end` must not exceed the video duration, which is capped at 480 sec.
- `audio_format` (string; optional): Output audio format. One of `wav`, `mp3`, `aac`, `flac`. Defaults to `aac`.

Machine-readable schema: https://platform.sonilo.com/openapi.json

### Usage notes

- Provide exactly one of video or video_url.
- Use audio_format, not audioFormat.

## Response And Errors

- 202 returns task_id and status=processing.
- Poll GET /v1/tasks/{task_id} every 2-3 seconds.
- On success, download audio.url and inspect audio.content_type plus audio.file_size.
- 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-sfx" \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "video_url=https://example.com/clip.mp4" \
  -F "prompt=realistic Foley, ambience, and action sound effects synced to the visible scene" \
  -F "audio_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/video-to-video-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}