Video to Video (Sound)

For AI agents →1 call free, no credit card required.

Generate a combined soundtrack — music and sound effects mixed together — for a video, muxed with the original picture and delivered as a new video file. Returns 202 Accepted with a task_id; poll GET /v1/tasks/:task_id until the task reaches a terminal status. Generated audio carries an inaudible provenance watermark.

Default: the returned video's audio is the generated music and sound effects alone; the source audio is removed entirely, and the result carries no music_processed stem (there is no voice source to process).
Pass keep_original_sound=true to keep the whole source track instead — mixed statically by default, or ducked under the mix with ducking=true.

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

API URLhttps://api.sonilo.com/v1/video-to-video-sound

Send API requests to https://api.sonilo.com. The platform.sonilo.com/docs pages are documentation only and are not API endpoints.

curl -X POST https://api.sonilo.com/v1/video-to-video-sound \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "video_url=https://example.com/clip.mp4" \
  -F "music_prompt=uplifting orchestral score" \
  -F "sfx_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-video-sound",
    headers=headers,
    files={
        "video_url": (None, "https://example.com/clip.mp4"),
        "music_prompt": (None, "uplifting orchestral score"),
        "sfx_prompt": (None, "match the on-screen action"),
    },
    timeout=30,
)
submit.raise_for_status()
task_id = submit.json()["task_id"]

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

if task["status"] == "succeeded":
    print(task["output_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("music_prompt", "uplifting orchestral score");
form.append("sfx_prompt", "match the on-screen action");

const submit = await fetch("https://api.sonilo.com/v1/video-to-video-sound", {
  method: "POST",
  headers,
  body: form,
});
if (!submit.ok) {
  throw new Error(`HTTP ${submit.status}: ${await submit.text()}`);
}
const { task_id } = await submit.json();

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

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

curl -X POST https://api.sonilo.com/v1/video-to-video-sound \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "video_url=https://example.com/clip.mp4" \
  -F "preserve_speech=true" \
  -F "ducking=true" \
  -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-video-sound",
    headers=headers,
    files={
        "video_url": (None, "https://example.com/clip.mp4"),
        "preserve_speech": (None, "true"),
        "ducking": (None, "true"),
        "segments": (None, json.dumps(segments)),
    },
    timeout=30,
)
submit.raise_for_status()
task_id = submit.json()["task_id"]

while True:
    poll = requests.get(
        f"https://api.sonilo.com/v1/tasks/{task_id}",
        headers=headers,
        timeout=30,
    )
    poll.raise_for_status()
    task = poll.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("preserve_speech", "true");
form.append("ducking", "true");
form.append("segments", JSON.stringify(segments));

const submit = await fetch("https://api.sonilo.com/v1/video-to-video-sound", {
  method: "POST",
  headers: { Authorization: "Bearer sk_your_api_key" },
  body: form,
});
if (!submit.ok) {
  throw new Error(`HTTP ${submit.status}: ${await submit.text()}`);
}
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. Keep keys server-side, for example in SONILO_API_KEY.

Authorization: Bearer sk_your_api_key

Store the key server-side, commonly as SONILO_API_KEY. A 401 means the key is missing, invalid, or revoked. A 403 means the key is valid but the account does not have access to that endpoint or workspace.

Body Parameters

videofile

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: 480 sec.

video_urlstring

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. Max file size: default 300MB. Max duration: 480 sec.

music_promptstring

Optional text prompt describing the music to generate, up to 2000 characters, independent of sfx_prompt. For best results, omit this and let the model infer a soundtrack from the on-screen action and visuals.

sfx_promptstring

Optional text prompt describing the sound effects to generate, up to 2000 characters, independent of music_prompt. 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, applied to the sound-effects side of the mix only. 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.

preserve_speechboolean

Optional boolean, default false. When true, the model isolates the original speech (dialogue, narration, or voice-over) from the source audio and keeps it as the voice source for the music side of the mix — mixed statically by default, or ducked under the mix with ducking=true. Superseded by keep_original_sound: when that is also true, the whole original track is kept as the voice source instead of just the isolated speech. No additional charge.

keep_original_soundboolean

Optional boolean, default false. When true, keeps the whole source video's audio track as the voice source for the music side of the mix, instead of the isolated vocals (preserve_speech) or no voice source at all. By default (false), the returned video's audio is the generated music and sound effects alone, with the source's own audio removed, and the result carries no music_processed stem. Supersedes preserve_speech when both are set. No additional charge.

duckingboolean

Optional boolean, default false. Selects how the voice source combines with the generated music, before the music is combined with the sound effects: by default it is a static vocal-forward mix; pass ducking=true to duck it dynamically instead, so dialogue stays intelligible — free either way. The voice source is the whole original track when keep_original_sound is set, the isolated vocals when only preserve_speech is set, or nothing at all when neither is set, in which case ducking has no effect. Best-effort: if voice isolation or the duck/mix pass fails, this silently degrades rather than failing the request.

variants_numinteger

Optional. How many distinct variants to generate in one request, 1-10 (default 1). Each variant pairs its own generated music with its own generated sound effects, returned as its own entry in outputs. Cost scales linearly — variants_num=3 costs three times a single-variant request. Values above 1 are never covered by the free trial and are always billed.

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-video-sound \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "video_url=https://example.com/clip.mp4" \
  -F "music_prompt=uplifting orchestral score" \
  -F "sfx_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-video-sound",
    headers=headers,
    files={
        "video_url": (None, "https://example.com/clip.mp4"),
        "music_prompt": (None, "uplifting orchestral score"),
        "sfx_prompt": (None, "match the on-screen action"),
    },
    timeout=30,
)
submit.raise_for_status()
task_id = submit.json()["task_id"]

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

if task["status"] == "succeeded":
    print(task["output_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("music_prompt", "uplifting orchestral score");
form.append("sfx_prompt", "match the on-screen action");

const submit = await fetch("https://api.sonilo.com/v1/video-to-video-sound", {
  method: "POST",
  headers,
  body: form,
});
if (!submit.ok) {
  throw new Error(`HTTP ${submit.status}: ${await submit.text()}`);
}
const { task_id } = await submit.json();

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

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

curl -X POST https://api.sonilo.com/v1/video-to-video-sound \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "video_url=https://example.com/clip.mp4" \
  -F "preserve_speech=true" \
  -F "ducking=true" \
  -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-video-sound",
    headers=headers,
    files={
        "video_url": (None, "https://example.com/clip.mp4"),
        "preserve_speech": (None, "true"),
        "ducking": (None, "true"),
        "segments": (None, json.dumps(segments)),
    },
    timeout=30,
)
submit.raise_for_status()
task_id = submit.json()["task_id"]

while True:
    poll = requests.get(
        f"https://api.sonilo.com/v1/tasks/{task_id}",
        headers=headers,
        timeout=30,
    )
    poll.raise_for_status()
    task = poll.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("preserve_speech", "true");
form.append("ducking", "true");
form.append("segments", JSON.stringify(segments));

const submit = await fetch("https://api.sonilo.com/v1/video-to-video-sound", {
  method: "POST",
  headers: { Authorization: "Bearer sk_your_api_key" },
  body: form,
});
if (!submit.ok) {
  throw new Error(`HTTP ${submit.status}: ${await submit.text()}`);
}
const { task_id } = await submit.json();

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