Video Analysis

For AI agents →2 calls free, no credit card required.

Analyze a video with AI and get a creative brief: a time-aligned segment plan and one or more prompts — derived from the footage itself. By default you get both a music-direction brief and a sound-design brief in one call; set mode to ask for just one. Returns 202 Accepted with a task_id; poll GET /v1/tasks/:task_id until the task reaches a terminal status.

POST/v1/video-analysismultipart/form-data

API URLhttps://api.sonilo.com/v1/video-analysis

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-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" \
  -F "variants_num=2"
# => {"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-analysis",
    headers=headers,
    files={
        "video_url": (None, "https://example.com/clip.mp4"),
        "prompt": (None, "upbeat, driving energy for an action montage"),
        "variants_num": (None, "2"),
    },
    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["variations"])
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", "upbeat, driving energy for an action montage");
form.append("variants_num", "2");

const submit = await fetch("https://api.sonilo.com/v1/video-analysis", {
  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.variations);
} else {
  console.log(task.error);
}

{
  "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. 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 URL — private/internal addresses are rejected. Max file size: default 300MB. Max duration: 480 sec.

promptstring

Optional. Guidance for the analysis, up to 2000 characters.

variants_numinteger

Optional integer, 1-5 (default 1). How many briefs to author for the same footage. Billed per brief — variants_num=3 costs three times a single-brief request.

modestring

Optional. Which brief to return. both (default) returns a music brief and a sound-effects brief in one call. music returns only the music brief. sfx returns only the sound-effects brief. Same price for all three.

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 — analysis runs asynchronously.

Next steps

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" \
  -F "variants_num=2"
# => {"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-analysis",
    headers=headers,
    files={
        "video_url": (None, "https://example.com/clip.mp4"),
        "prompt": (None, "upbeat, driving energy for an action montage"),
        "variants_num": (None, "2"),
    },
    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["variations"])
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", "upbeat, driving energy for an action montage");
form.append("variants_num", "2");

const submit = await fetch("https://api.sonilo.com/v1/video-analysis", {
  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.variations);
} else {
  console.log(task.error);
}

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