Video to Video (Sound)

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.

1 call free, no credit card required.

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=false" \
  -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, "false"),
        "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", "false");
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: 180 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.

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

preserve_speechboolean

Optional boolean, default false. When true, the original speech (dialogue, narration, or voice-over) is preserved while composing the music — the model isolates the speech from the source audio and composes the new music around it. Applies to the music side of the mix only. No additional charge.

duckingboolean

Optional boolean, default true. Ducks the generated music under the video's original speech, before the music is combined with the sound effects, so dialogue stays intelligible. Pass ducking=false to opt out. Ignored when preserve_speech is used. Free of charge.

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=false" \
  -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, "false"),
        "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", "false");
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"
}