Video to Sound Effect

Generate synchronized sound effects for a video, delivered as a standalone audio file. Returns 202 Accepted with a task_id; poll GET /v1/tasks/:task_id until the task reaches a terminal status.

POST/v1/video-to-sfxmultipart/form-data

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=match the on-screen action"
# => {"task_id": "9f5f2f7e-...", "status": "processing"}

curl https://api.sonilo.com/v1/tasks/9f5f2f7e-... \
  -H "Authorization: Bearer sk_your_api_key"
# poll until "status" is "succeeded" or "failed"

import time
import requests

headers = {"Authorization": "Bearer sk_your_api_key"}

submit = requests.post(
    "https://api.sonilo.com/v1/video-to-sfx",
    headers=headers,
    files={
        "video_url": (None, "https://example.com/clip.mp4"),
        "prompt": (None, "match the on-screen action"),
    },
    timeout=30,
)
submit.raise_for_status()
task_id = submit.json()["task_id"]

while True:
    task = requests.get(
        f"https://api.sonilo.com/v1/tasks/{task_id}",
        headers=headers,
        timeout=30,
    ).json()
    if task["status"] != "processing":
        break
    time.sleep(3)

if task["status"] == "succeeded":
    print(task["audio"]["url"])
else:
    print(task["error"])

const headers = { Authorization: "Bearer sk_your_api_key" };

const form = new FormData();
form.append("video_url", "https://example.com/clip.mp4");
form.append("prompt", "match the on-screen action");

const submit = await fetch("https://api.sonilo.com/v1/video-to-sfx", {
  method: "POST",
  headers,
  body: form,
});
const { task_id } = await submit.json();

let task;
do {
  await new Promise((r) => setTimeout(r, 3000));
  task = await (
    await fetch(`https://api.sonilo.com/v1/tasks/${task_id}`, { headers })
  ).json();
} while (task.status === "processing");

if (task.status === "succeeded") {
  console.log(task.audio.url);
} else {
  console.log(task.error);
}

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 'segments=[{"start": 0, "end": 4, "prompt": "footsteps on gravel"}, {"start": 4, "end": 10, "prompt": "car door slam then engine starts"}]'

import json
import time
import requests

headers = {"Authorization": "Bearer sk_your_api_key"}

segments = [
    {"start": 0, "end": 4, "prompt": "footsteps on gravel"},
    {"start": 4, "end": 10, "prompt": "car door slam then engine starts"},
]

submit = requests.post(
    "https://api.sonilo.com/v1/video-to-sfx",
    headers=headers,
    files={
        "video_url": (None, "https://example.com/clip.mp4"),
        "segments": (None, json.dumps(segments)),
    },
    timeout=30,
)
submit.raise_for_status()
task_id = submit.json()["task_id"]

while True:
    task = requests.get(
        f"https://api.sonilo.com/v1/tasks/{task_id}",
        headers=headers,
        timeout=30,
    ).json()
    if task["status"] != "processing":
        break
    time.sleep(3)

const segments = [
  { start: 0, end: 4, prompt: "footsteps on gravel" },
  { start: 4, end: 10, prompt: "car door slam then engine starts" },
];

const form = new FormData();
form.append("video_url", "https://example.com/clip.mp4");
form.append("segments", JSON.stringify(segments));

const submit = await fetch("https://api.sonilo.com/v1/video-to-sfx", {
  method: "POST",
  headers: { Authorization: "Bearer sk_your_api_key" },
  body: form,
});
const { task_id } = await submit.json();

{
  "task_id": "9f5f2f7e-…",
  "status": "processing"
}

Authorization

Authenticate via Bearer token. Generate keys at the API Keys page and pass them in the Authorization header on every request.

Authorization: Bearer sk_your_api_key

Body Parameters

videofilerequired

Video file upload. Provide either video or video_url, not both. Accepted formats: mp4, mov, webm, m4v, gif (animated). Max file size: default 300MB. Max duration: 180 sec.

video_urlstringrequired

URL to a video file. Provide either video or video_url, not both. Must be a public http:// or https:// URL; private/internal addresses are rejected.

promptstring

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.

segmentsstring

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 180 sec.

audio_formatstring

Output audio format. One of wav, mp3, aac, flac. Defaults to aac.

Response

task_idstring

The task identifier. Poll the Get Task endpoint (GET /v1/tasks/:task_id) until the task reaches a terminal status.

statusstring

Always processing on submission — generation runs asynchronously.

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=match the on-screen action"
# => {"task_id": "9f5f2f7e-...", "status": "processing"}

curl https://api.sonilo.com/v1/tasks/9f5f2f7e-... \
  -H "Authorization: Bearer sk_your_api_key"
# poll until "status" is "succeeded" or "failed"

import time
import requests

headers = {"Authorization": "Bearer sk_your_api_key"}

submit = requests.post(
    "https://api.sonilo.com/v1/video-to-sfx",
    headers=headers,
    files={
        "video_url": (None, "https://example.com/clip.mp4"),
        "prompt": (None, "match the on-screen action"),
    },
    timeout=30,
)
submit.raise_for_status()
task_id = submit.json()["task_id"]

while True:
    task = requests.get(
        f"https://api.sonilo.com/v1/tasks/{task_id}",
        headers=headers,
        timeout=30,
    ).json()
    if task["status"] != "processing":
        break
    time.sleep(3)

if task["status"] == "succeeded":
    print(task["audio"]["url"])
else:
    print(task["error"])

const headers = { Authorization: "Bearer sk_your_api_key" };

const form = new FormData();
form.append("video_url", "https://example.com/clip.mp4");
form.append("prompt", "match the on-screen action");

const submit = await fetch("https://api.sonilo.com/v1/video-to-sfx", {
  method: "POST",
  headers,
  body: form,
});
const { task_id } = await submit.json();

let task;
do {
  await new Promise((r) => setTimeout(r, 3000));
  task = await (
    await fetch(`https://api.sonilo.com/v1/tasks/${task_id}`, { headers })
  ).json();
} while (task.status === "processing");

if (task.status === "succeeded") {
  console.log(task.audio.url);
} else {
  console.log(task.error);
}

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 'segments=[{"start": 0, "end": 4, "prompt": "footsteps on gravel"}, {"start": 4, "end": 10, "prompt": "car door slam then engine starts"}]'

import json
import time
import requests

headers = {"Authorization": "Bearer sk_your_api_key"}

segments = [
    {"start": 0, "end": 4, "prompt": "footsteps on gravel"},
    {"start": 4, "end": 10, "prompt": "car door slam then engine starts"},
]

submit = requests.post(
    "https://api.sonilo.com/v1/video-to-sfx",
    headers=headers,
    files={
        "video_url": (None, "https://example.com/clip.mp4"),
        "segments": (None, json.dumps(segments)),
    },
    timeout=30,
)
submit.raise_for_status()
task_id = submit.json()["task_id"]

while True:
    task = requests.get(
        f"https://api.sonilo.com/v1/tasks/{task_id}",
        headers=headers,
        timeout=30,
    ).json()
    if task["status"] != "processing":
        break
    time.sleep(3)

const segments = [
  { start: 0, end: 4, prompt: "footsteps on gravel" },
  { start: 4, end: 10, prompt: "car door slam then engine starts" },
];

const form = new FormData();
form.append("video_url", "https://example.com/clip.mp4");
form.append("segments", JSON.stringify(segments));

const submit = await fetch("https://api.sonilo.com/v1/video-to-sfx", {
  method: "POST",
  headers: { Authorization: "Bearer sk_your_api_key" },
  body: form,
});
const { task_id } = await submit.json();

{
  "task_id": "9f5f2f7e-…",
  "status": "processing"
}