Sign up and get free credits

Developers

Make summary videos from your own code.

The Vidonto API turns a YouTube link, a web page or pasted text into a narrated, captioned MP4. Start a video with one request, follow its progress or get a webhook when it is done, and pay with the credits you already have.

Base URL
https://www.vidonto.com/api/v1
Authentication
Authorization: Bearer qsv_…

Start here

Getting started

The Vidonto API lets your own code do what Quick Render does in the web app: start a summary video from a YouTube link, a web page, pasted text or your own script, follow its progress, download the finished MP4 and check your credits. Videos started through the API use your credits and saved settings, and appear in your Quick Render list in the app next to the ones you started by hand.

1. Create an API key

  • Create an account and confirm your email address. Starting videos needs a verified email.
  • Open the API keys page in the app, give the key a name (for example the program that will use it) and select Create key.
  • Copy the key straight away. It looks like qsv_ followed by 48 letters and digits, and it is shown only once. You can have up to 10 active keys.

Keep your key secret

A key acts as your account and spends your credits. Keep it on your server, in an environment variable or a secrets manager. Never put it in browser or mobile app code, and never commit it to a repository. If a key leaks, revoke it on the API keys page; it stops working immediately. Resetting your password also revokes all your keys.

2. Use the base URL

All endpoints live under one base URL. Requests and responses are JSON, apart from the MP4 download.

Base URL
https://www.vidonto.com/api/v1

3. Make your first request

Checking your credit balance is free and a good way to confirm the key works. Every sample on this page reads the key from a VIDONTO_API_KEY environment variable.

export VIDONTO_API_KEY="qsv_..."   # from the API keys page

curl https://www.vidonto.com/api/v1/credits \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
// Node.js 18 or later. Run with VIDONTO_API_KEY set in the environment.
const response = await fetch("https://www.vidonto.com/api/v1/credits", {
  headers: { Authorization: `Bearer ${process.env.VIDONTO_API_KEY}` },
});
console.log(response.status, await response.json()); // 200 { balance: 412.5, exempt: false }
# pip install requests. Run with VIDONTO_API_KEY set in the environment.
import os
import requests

response = requests.get(
    "https://www.vidonto.com/api/v1/credits",
    headers={"Authorization": f"Bearer {os.environ['VIDONTO_API_KEY']}"},
)
print(response.status_code, response.json())  # 200 {'balance': 412.5, 'exempt': False}

Basics

Authentication

Send your key as a bearer token in the Authorization header of every request. The API only accepts keys: signing in to the web app does not give access, and keys never work on the app's own pages.

Header
Authorization: Bearer qsv_YOUR_API_KEY

When the key is missing or not accepted, the API answers with status 401:

SituationStatuserror.code
No Authorization header, or not a Bearer token401missing_api_key
The key is mistyped, was revoked, or belongs to a disabled account401invalid_api_key
401 response
{
  "error": {
    "code": "invalid_api_key",
    "message": "This API key is invalid or has been revoked."
  }
}

Revoking a key on the API keys page takes effect on the next request. Programs that still use it get invalid_api_key, so create the replacement key and deploy it before you revoke the old one.

Ten minutes

Quickstart: from link to MP4

A video is made by a run. You start a run, check on it until it finishes, then download the MP4. The steps below make one script: paste the setup, then step 1 (or its pasted-text version), then steps 2 and 3, in the same shell session or file. Pick a language once and every sample on the page switches to it.

0. Set up

Put your key in the VIDONTO_API_KEY environment variable and set the base URL. The other steps use these names.

# Needs curl and jq.
export VIDONTO_API_KEY="qsv_..."   # from the API keys page
API="https://www.vidonto.com/api/v1"
// Node.js 18 or later, as an ES module (for example quickstart.mjs).
// Run with VIDONTO_API_KEY set in the environment.
import { randomUUID } from "node:crypto";
import { readFile, writeFile } from "node:fs/promises";

const API = "https://www.vidonto.com/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.VIDONTO_API_KEY}`,
  "Content-Type": "application/json",
};
# pip install requests. Run with VIDONTO_API_KEY set in the environment.
import os
import time
import uuid

import requests

API = "https://www.vidonto.com/api/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['VIDONTO_API_KEY']}"

Send a YouTube video or web page link as url. Every other field is optional; anything you leave out comes from your saved settings (see Options). The Idempotency-Key header makes it safe to repeat the request if the network drops.

RUN=$(curl -s -X POST "$API/runs" \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "targetDuration": 60,
    "videoFormat": "vertical"
  }')
echo "$RUN"

# Keep the new run's id for the next steps (empty if the request was refused).
RUN_ID=$(echo "$RUN" | jq -r '.id // empty')
const response = await fetch(`${API}/runs`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": randomUUID() },
  body: JSON.stringify({
    url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    targetDuration: 60,
    videoFormat: "vertical",
  }),
});
let run = await response.json();
if (!response.ok) throw new Error(`${run.error.code}: ${run.error.message}`);
console.log(run.id, run.status); // "3f0c6b6e-…" "running"
response = session.post(
    f"{API}/runs",
    headers={"Idempotency-Key": str(uuid.uuid4())},
    json={
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "targetDuration": 60,
        "videoFormat": "vertical",
    },
)
run = response.json()
if not response.ok:
    raise RuntimeError(f"{run['error']['code']}: {run['error']['message']}")
print(run["id"], run["status"])  # 3f0c6b6e-… running

The API answers 202 Accepted with the new run, and the sample keeps it (or its RUN_ID in the shell) for the next steps. Its estimated credits are now held from your balance (see Credits).

202 response
{
  "id": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
  "status": "running",
  "stage": "transcript",
  "progress": 0,
  "error": null,
  "retryable": false,
  "title": null,
  "name": null,
  "tags": [
    "Client A"
  ],
  "source": {
    "kind": "youtube",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  },
  "options": {
    "targetDuration": 90,
    "summaryModel": "gpt-6-luna",
    "videoFormat": "landscape",
    "textMode": "narration",
    "captionLength": "short",
    "aiImages": false,
    "voiceId": "21m00Tcm4TlvDq8ikWAM",
    "voiceModel": "eleven_v4",
    "transcriptLanguage": "en",
    "videoLanguage": "en",
    "openingStyle": "coming_up",
    "endingStyle": "none",
    "customSignOff": null,
    "creditSource": false,
    "instructions": null,
    "presenter": null,
    "look": "auto",
    "showLogo": false,
    "brandId": null,
    "videoQuality": "720p",
    "review": false,
    "animatedScenes": "off",
    "writingMethod": null
  },
  "stages": [
    {
      "id": "transcript",
      "label": "Fetching transcript",
      "status": "running",
      "progress": 0
    },
    {
      "id": "summary",
      "label": "Script",
      "status": "pending",
      "progress": 0
    },
    {
      "id": "storyboard",
      "label": "Storyboard",
      "status": "pending",
      "progress": 0
    },
    {
      "id": "render",
      "label": "Voiceover & render",
      "status": "pending",
      "progress": 0
    }
  ],
  "reviewStep": null,
  "chargedCredits": 0,
  "video": null,
  "createdAt": "2026-10-01T12:00:00.000Z",
  "updatedAt": "2026-10-01T12:00:00.000Z"
}

…or from pasted text

Use this instead of step 1 to summarize your own text from a file, here article.txt. Send text instead of url, with an optional title; send one or the other, never both. Use textMode "key_points" to show the main points on screen instead of the default spoken "narration".

RUN=$(jq -n --rawfile text article.txt \
    '{text: $text, title: "Quarterly update", textMode: "key_points"}' |
  curl -s -X POST "$API/runs" \
    -H "Authorization: Bearer $VIDONTO_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" \
    --data-binary @-)
echo "$RUN"
RUN_ID=$(echo "$RUN" | jq -r '.id // empty')
const text = await readFile("article.txt", "utf8");
const response = await fetch(`${API}/runs`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": randomUUID() },
  body: JSON.stringify({ text, title: "Quarterly update", textMode: "key_points" }),
});
let run = await response.json();
if (!response.ok) throw new Error(`${run.error.code}: ${run.error.message}`);
console.log(run.id, run.status);
with open("article.txt", encoding="utf-8") as file:
    text = file.read()

response = session.post(
    f"{API}/runs",
    headers={"Idempotency-Key": str(uuid.uuid4())},
    json={"text": text, "title": "Quarterly update", "textMode": "key_points"},
)
run = response.json()
if not response.ok:
    raise RuntimeError(f"{run['error']['code']}: {run['error']['message']}")
print(run["id"], run["status"])

…or from your own script

Already have the exact words? Send script instead, here from script.txt. It is spoken word for word, with no AI script step and no script charge. Leave out the options that only steer the AI script, such as targetDuration and openingStyle (see Your own script).

RUN=$(jq -n --rawfile script script.txt \
    '{script: $script, title: "Monthly update"}' |
  curl -s -X POST "$API/runs" \
    -H "Authorization: Bearer $VIDONTO_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" \
    --data-binary @-)
echo "$RUN"
RUN_ID=$(echo "$RUN" | jq -r '.id // empty')
const script = await readFile("script.txt", "utf8");
const response = await fetch(`${API}/runs`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": randomUUID() },
  body: JSON.stringify({ script, title: "Monthly update" }),
});
let run = await response.json();
if (!response.ok) throw new Error(`${run.error.code}: ${run.error.message}`);
console.log(run.id, run.status);
with open("script.txt", encoding="utf-8") as file:
    script = file.read()

response = session.post(
    f"{API}/runs",
    headers={"Idempotency-Key": str(uuid.uuid4())},
    json={"script": script, "title": "Monthly update"},
)
run = response.json()
if not response.ok:
    raise RuntimeError(f"{run['error']['code']}: {run['error']['message']}")
print(run["id"], run["status"])

2. Wait for it to finish

Fetch the run with GET /runs/{runId} until status is no longer running. A video usually takes a few minutes. Checking every 10 seconds stays well inside the rate limits. To skip polling altogether, set up a webhook and get told when the run finishes.

# Uses RUN_ID from the previous step. Checks every 10 seconds.
while true; do
  RUN=$(curl -s "$API/runs/$RUN_ID" -H "Authorization: Bearer $VIDONTO_API_KEY")
  STATUS=$(echo "$RUN" | jq -r .status)
  echo "$STATUS $(echo "$RUN" | jq -r .stage) $(echo "$RUN" | jq -r .progress)%"
  [ "$STATUS" != "running" ] && break
  sleep 10
done
echo "$RUN" | jq '{status, error, video}'
while (run.status === "running") {
  await new Promise((resolve) => setTimeout(resolve, 10_000));
  const response = await fetch(`${API}/runs/${run.id}`, { headers });
  run = await response.json();
  if (!response.ok) throw new Error(`${run.error.code}: ${run.error.message}`);
  console.log(run.status, run.stage, `${Math.round(run.progress)}%`);
}

if (run.status !== "succeeded") {
  throw new Error(run.error ?? `Run ${run.status}`);
}
while run["status"] == "running":
    time.sleep(10)
    response = session.get(f"{API}/runs/{run['id']}")
    response.raise_for_status()
    run = response.json()
    print(run["status"], run["stage"], f"{round(run['progress'])}%")

if run["status"] != "succeeded":
    raise RuntimeError(run["error"] or f"Run {run['status']}")
statusMeaningWhat to do
runningStill working. stage and progress (0–100) show how far it got.Check again later.
succeededFinished. video holds the download path and the length in seconds.Download the MP4.
failederror says why.If retryable is true, retry it from the step that failed.
cancelledStopped by you, in the API or the web app.Nothing; unused credits were returned.

A run passes through four stages in order:

  • transcript: reads the captions of the video, the text of the web page, or your pasted text.
  • summary: writes the script, or keeps your own script exactly as written.
  • storyboard: plans the frames, captions and narration.
  • render: records the voice-over and renders the MP4. When the run succeeds, stage is done.

3. Download the MP4

Once video is set, download the file from GET /runs/{runId}/video. The response is the MP4 itself, sent as an attachment.

curl -fL -o summary.mp4 "$API/runs/$RUN_ID/video" \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
// run.video.downloadUrl is a path on this host, e.g. /api/v1/runs/{id}/video
const video = await fetch(new URL(run.video.downloadUrl, API), { headers });
if (!video.ok) throw new Error(`Download failed with status ${video.status}`);
await writeFile("summary.mp4", Buffer.from(await video.arrayBuffer()));
console.log("Saved summary.mp4");
with session.get(f"{API}/runs/{run['id']}/video", stream=True) as video:
    video.raise_for_status()
    with open("summary.mp4", "wb") as file:
        for chunk in video.iter_content(chunk_size=1024 * 1024):
            file.write(chunk)
print("Saved summary.mp4")
The finished run
{
  "id": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
  "status": "succeeded",
  "stage": "done",
  "progress": 100,
  "error": null,
  "retryable": false,
  "title": "How transformers work",
  "name": null,
  "tags": [
    "Client A"
  ],
  "source": {
    "kind": "youtube",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  },
  "options": {
    "targetDuration": 90,
    "summaryModel": "gpt-6-luna",
    "videoFormat": "landscape",
    "textMode": "narration",
    "captionLength": "short",
    "aiImages": false,
    "voiceId": "21m00Tcm4TlvDq8ikWAM",
    "voiceModel": "eleven_v4",
    "transcriptLanguage": "en",
    "videoLanguage": "en",
    "openingStyle": "coming_up",
    "endingStyle": "none",
    "customSignOff": null,
    "creditSource": false,
    "instructions": null,
    "presenter": null,
    "look": "auto",
    "showLogo": false,
    "brandId": null,
    "videoQuality": "720p",
    "review": false,
    "animatedScenes": "off",
    "writingMethod": null
  },
  "stages": [
    {
      "id": "transcript",
      "label": "Fetching transcript",
      "status": "done",
      "progress": 100
    },
    {
      "id": "summary",
      "label": "Script",
      "status": "done",
      "progress": 100
    },
    {
      "id": "storyboard",
      "label": "Storyboard",
      "status": "done",
      "progress": 100
    },
    {
      "id": "render",
      "label": "Voiceover & render",
      "status": "done",
      "progress": 100
    }
  ],
  "reviewStep": null,
  "chargedCredits": 48.2,
  "video": {
    "downloadUrl": "/api/v1/runs/3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11/video",
    "durationSeconds": 92.4
  },
  "createdAt": "2026-10-01T12:00:00.000Z",
  "updatedAt": "2026-10-01T12:06:40.000Z"
}

Everything also shows up in the app

Runs started with a key appear in your Quick Render list in the web app, and runs started in the app appear in GET /runs. You can watch, cancel or download them in either place.

Customize

Video options

Every option is optional, on both POST /runs and POST /runs/batch. For each one you leave out, the API uses the first of:

  1. the value in your request,
  2. your saved setting from the Settings page in the app, for the options marked Saved settings below,
  3. the server default.

GET /options returns the allowed values and, under defaults, exactly what a run gets when you send nothing. Every run also reports the options it actually used in its options field. Unknown fields are rejected with validation_error, so a typo never silently falls back to a default.

OptionValuesWhen omitted
targetDurationSeconds, 10 or more.90. A target, not a limit: the narration always plays in full.
lengthRangeTopic runs only: {"minSeconds": 60, "maxSeconds": 240}, minSeconds at least 10 and maxSeconds at most 1,200 and at least minSeconds, instead of targetDuration (sending both is refused with validation_error). After reading the sources, the AI lists the distinct points they support and picks where they land inside the range (about 30–45 seconds each): longer for rich sources, the shortest only when there’s little to say, and never padded. Credits are held for the longest. The run’s topic.length shows the length chosen and why (chosenBy fallback means no usable answer came back, so the middle of the range was used). With review, you can choose the length yourself when approving the sources (lengthSeconds).One set length (targetDuration).
videoFormatlandscape (16:9), vertical (9:16), square (1:1), portrait (4:5)landscape
videoQuality720p, 1080p or 2160p (4K). Landscape at 1080p is 1920×1080 and at 4K 3840×2160; square and portrait are already 1080 on the short side, so only 4K makes them larger. Higher qualities cost more credits and take longer to render.720p
textModenarration (a spoken script) or key_points (the main points on screen)narration
captionLengthshort (a few words at a time), medium (about one line), sentence (a whole sentence when it fits)The text mode’s default: short for narration, medium for key points.
summaryModelA script model id from GET /options.Saved settings then the recommended model.
voiceIdA voice id from GET /options.Saved settings then the first available voice.
transcriptLanguagePreferred YouTube caption language, such as en or pt-BR.Saved settings then en.
videoLanguageThe language the video is written and narrated in, such as es or de: one of videoLanguages in GET /options. See Video language.Saved settings then en.
openingStyleSee the table below.Saved settings then coming_up.
endingStyleSee the table below.Saved settings then none.
customSignOffYour closing line, up to 200 characters and 20 words.Saved settings
aiImagestrue or false. Generates images for the frames and costs more credits.false
creditSourcetrue or false. Credits the original source in the video.false
instructionsFree text, up to 2,000 characters (instructionsMaxCharacters in GET /options). Steers how the script and storyboard are written. See Instructions.None.
presenterAn object with avatarId and layout, plus optional side, size and stage. An AI presenter speaks the narration on camera and costs more credits. See AI presenter.No presenter.
characterIdsTwo character ids from GET /characters, first speaker first. The video becomes a conversation between them, each line in its character’s voice. See Conversations.One narrator.
lookauto (the AI picks a built-in look for each video), a built-in look such as midnight or paper (that look every time), or brand (your saved brand colours). See A fixed look and Your brand.Your default look in Settings, else auto.
showLogotrue or false. With look brand, shows the brand’s logo.false
brandIdWith look brand, which of your brands to use: an id from brands in GET /options.Your default brand.
animatedScenesoff, standard (about one custom animated scene every 20 seconds, at least 4) or whole_video (every suitable frame, up to about one every 7 seconds). Each scene costs extra credits (animatedScenes.creditsPerScene in GET /options); estimates and the credits held at start include the most scenes the run may make. A scene that fails its checks shows the frame’s usual layout instead.off
reviewtrue or false. Waits for your approval after the script and after the storyboard. See Review before render.false: the run approves both steps itself.

Openings and endings

A short opening and ending can frame the summary. Pick them with openingStyle and endingStyle:

openingStyleWhat it does
noneStarts straight into the first point.
coming_upA quick preview that lists the points the video covers.
cliffhangerTeases the most surprising point without giving it away.
questionOpens with the central question the video answers.
bottom_lineStates the biggest takeaway up front, then explains it.
endingStyleWhat it does
noneEnds on the last point.
recapA quick recap of the main points in order.
takeawayA one-sentence bottom line to remember.
reflectionCloses with a question for the viewer to think about.
originalSends the viewer to the full video or article.
customEnds with your own line from customSignOff, spoken exactly as written.

With endingStyle custom, the run needs a sign-off: send customSignOff or save one in Settings. A missing or too-long sign-off is rejected with invalid_sign_off.

Request body
{
  "url": "https://example.com/article",
  "openingStyle": "question",
  "endingStyle": "custom",
  "customSignOff": "Follow for a new summary every Monday."
}

Instructions

Use instructions to steer how the video is written: what to focus on, the tone, who it is for, or what to emphasise. For example “focus on the pricing section”, “casual tone for beginners” or “emphasise the risks”. The script follows them, and the storyboard uses them for emphasis and headline wording.

Instructions are guidance, not a new prompt. They can’t change the video’s length, its format, or the rule that the script only says what the source supports, so asks like “ignore the word limit” or “make up statistics” are ignored. Instructions are trimmed, and longer than 2,000 characters is rejected with validation_error. They cost nothing extra, and every run echoes them back in options.instructions (null when none were given), including in webhooks.

Request body
{
  "url": "https://example.com/article",
  "targetDuration": 90,
  "instructions": "Focus on the pricing section. Casual tone for beginners."
}

Video language

Send videoLanguage to make the video in another language. The script, headlines, list points, chart labels, voice-over and captions are all in that language, whatever language the source is in. GET /options lists the 26 languages under videoLanguages; anything else is rejected with validation_error. The price is the same in every language, and every run reports its language in options.videoLanguage.

transcriptLanguage is different: it picks which YouTube captions are read. With script, write the script in the video language, because your words are spoken exactly as written and never translated.

Request body
{
  "url": "https://example.com/article",
  "targetDuration": 90,
  "videoLanguage": "de"
}

AI presenter

Add presenter to have a realistic presenter speak the narration on camera, lip-synced to the same voice-over. Pick an avatarId from presenter.avatars in GET /options, and a layout: corner (beside the scenes throughout), bookends (full screen for the opening and ending, in the corner between) or full (full screen throughout, with the scenes softened behind).

presenter.avatars lists hundreds of looks. Each has an id, a name and a previewImageUrl, plus gender and person (several looks share a person) when known. Every look costs the same. Read the list from GET /options rather than storing it, because looks can be added or removed.

The presenter costs extra credits per minute of narration (presenter.creditsPerMinute). It is included in the estimate (send presenter=true to GET /estimate) and in the credits held when the run starts. It works for narration up to 10 minutes: a longer targetDuration is refused with presenter_too_long, and a run whose script turns out longer fails before the voice-over is made. An unknown avatar is refused with presenter_unknown. It adds several minutes to the run, and every run echoes it back in options.presenter (null when there is none).

Request body
{
  "url": "https://example.com/article",
  "targetDuration": 90,
  "presenter": {
    "avatarId": "Daphne_public_1",
    "layout": "corner"
  }
}

Two more layouts and three placement fields shape where the presenter stands:

  • layout director places the presenter scene by scene, as the app’s Quick Render does: the storyboard picks full screen, beside the scene or inside it for each frame. You can change those picks when you review the storyboard.
  • side (left or right, default right) and size (small, standard or large, default standard) place the corner presenter. presenter.sides and presenter.sizes in GET /options list them.
  • stage (beside or scene) is for corner and bookends only. Fields that don’t apply are refused with presenter_placement_unused: side, size or stage with full, and stage with director.
Request body
{
  "url": "https://example.com/article",
  "targetDuration": 90,
  "presenter": {
    "avatarId": "Daphne_public_1",
    "layout": "director",
    "side": "left",
    "size": "large"
  }
}

Conversations

Save characters under Settings → Characters in the app: a name, a voice and a short role line such as “curious host, asks the questions”. Send two of their ids as characterIds (first speaker first) and the script is written as a natural back-and-forth between them that follows their roles and stays grounded in the source. Each line is voiced in its character’s voice, joined into one soundtrack with short pauses between speakers, and the captions show who is speaking. It costs the same as one narrator: the voice-over is priced by its text, not by the number of voices.

  • GET /characters lists your characters (id, name, voiceId, role), and conversation.defaultCast in GET /options gives the default pair saved in Settings. Runs never use characters unless you send characterIds.
  • The characters’ names, voices and roles are copied when the run starts, so editing or deleting a character later never changes it. Every run echoes them in options.characters (null with one narrator).
  • A character that isn’t yours (or was deleted) is refused with character_not_found, and one whose voice is no longer offered with voice_unavailable, before anything is charged. Conversations don’t work with presenter (presenter_conversation) or recordingId (cast_not_supported).
  • With your own script, start each line with who says it, like Maya: …. A script that doesn’t say who speaks is refused with script_speakers. With review, the waiting script marks each speaker with a [SPEAKER: Name] label (never spoken), and each storyboard frame has turns saying where each speaker starts; you can change either.
Request body
{
  "url": "https://example.com/article",
  "targetDuration": 90,
  "characterIds": [
    "5b2a8c1e-7d4f-4e9a-b3c6-1f0e2d3c4b5a",
    "9c4e1a7b-2f3d-4b8e-a6c5-0d1e2f3a4b5c"
  ]
}
Request body (own script)
{
  "script": "Maya: So what actually changed this year?\nLeo: Three things, and the first one surprised everyone.",
  "characterIds": [
    "5b2a8c1e-7d4f-4e9a-b3c6-1f0e2d3c4b5a",
    "9c4e1a7b-2f3d-4b8e-a6c5-0d1e2f3a4b5c"
  ]
}

A fixed look

With look left out or set to auto, the AI picks one of the built-in looks while it writes each storyboard, so the look can change from one video to the next. To keep every video the same, send a built-in look: midnight, aurora, geometric, bold, paper or daylight.

  • builtInLooks in GET /options lists them with a name, a short description of the colours and a tone (dark or light background).
  • Save a default under Settings → Summary video look in the app and every run that leaves look out uses it, so a daily job keeps its look without changing your request. defaults.look in GET /options shows it. Send auto to let the AI pick for one run anyway.
  • The look is captured when the run starts: changing the default later doesn’t change runs already started, and a retry keeps the same look. Every run echoes it in options.look, including in webhooks. It costs nothing extra.
Request body
{
  "url": "https://example.com/article",
  "targetDuration": 90,
  "look": "midnight"
}

Your brand

Send look brand to use the background, text and accent colours (and fonts) of one of your brands under Settings → Brands in the app, instead of the built-in look picked for each video. Without brandId the run uses your default brand; send brandId to pick another one, for example a client’s. Add showLogo true to put the brand’s logo in the top corner, away from the captions. Leave look out for your default look (or send auto to let the AI pick). A brand is never a saved default: each run uses a brand only when it asks.

  • brands in GET /options lists your brands, oldest first: id, name, isDefault, and whether each has coloursSaved, logoSaved and fontsSaved. brand says the same for your default brand. Manage brands in Settings or with the brand endpoints.
  • A brandId that isn’t one of your brands (for example one you deleted), a brand without saved colours, or one without a logo when showLogo is true, is refused with brand_missing (409) before anything is charged. In a batch, nothing starts.
  • showLogo true or a brandId without look brand is refused with show_logo_needs_brand_look or brand_id_needs_brand_look.
  • POST /runs/batch takes the same fields; every run in the batch uses the same brand.
  • The brand is captured when the run starts. Changing its colours, fonts or logo in Settings later doesn’t change runs already started, and a retry keeps the same brand.
  • It costs nothing extra. Every run echoes its look in options.look, options.showLogo and options.brandId (null when it used your default brand), including in webhooks.
Request body
{
  "url": "https://example.com/article",
  "targetDuration": 90,
  "look": "brand",
  "brandId": "5b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "showLogo": true
}

Sources

SourceSendNotes
YouTube videourlUses the video’s captions, in transcriptLanguage when available. Videos without captions fail at the first step.
Web pageurlUses the main text of the page. Pages behind a sign-in or paywall can’t be read.
Pasted texttext, optional titleEmpty text is rejected with empty_text. With creditSource, pasted text needs a title (source_credit_incomplete).
Your own scriptscript, optional titleSpoken exactly as written; see below. Without a title, the first sentence becomes the title.
PDF, Word file or deckdocumentUrl, optional titleRead as pasted text; see Documents. Without a title, the file’s own title is used.
Several sourcessources, optional writingMethod2 to 5 links or texts written into one video; see Several sources.
One of your recordingsrecordingId, optional highlightsStyleA highlights video of its best moments; see Highlights videos.

Your own script

Send script when you already have the exact words. There is no AI script step and no script charge: the storyboard splits your script into scenes without rewording it, and the narration and captions say exactly those words. The run’s summary stage finishes at once.

  • Up to 20,000 characters (ownScript.maxCharacters in GET /options). Empty scripts are refused with empty_script, longer ones with script_too_long.
  • Options that only steer the AI script are refused with own_script_option: openingStyle, endingStyle, customSignOff, creditSource, summaryModel and targetDuration (the video is as long as your script). They are listed in ownScript.unsupportedOptions.
  • instructions still work: they steer the storyboard’s visuals.
  • Single runs only; POST /runs/batch takes links.

Several sources

Send sources, a list of 2 to 5 sources in order, instead of url, text, script, documentUrl and title. Each source is {"url": …} (a YouTube video or web page), {"text": …} or {"documentUrl": …} (a PDF, Word file or deck, read like a single document). Text and document sources take an optional title and attribution (author or site) for the source list; a document without a title uses the file’s own. One script is written from all of them, as in the app’s Several sources.

  • writingMethod: new_piece (the default) writes an original video that uses the sources as research; summary retells what they say, organised by idea. creditSource defaults to true with summary and false with new_piece: the narration says it’s based on the sources in one short line, and the list goes on the closing card.
  • Links are read when the run starts. Each YouTube video’s captions are a paid read; pages, text and documents are free. A page that can’t be read fails the run with a retryable error; retry it, or start again with that page’s text.
  • Each documentUrl is downloaded and read when you send the request, then kept as that source’s text; the file is never stored. A file that can’t be read refuses the whole request before anything is charged, with the same codes as a single documentUrl and the source’s number in the message.
  • Fewer than 2 or more than 5 sources are refused with multi_source_count; a bad source is refused with its number in the message. All text together counts toward sourceMaxCharacters.
  • Estimate with sourceKind=multi, sourceCount and youtubeSources. The run’s source.kind is multi and options.writingMethod shows the method (null on other runs). severalSources in GET /options lists the limits.
  • Single runs only; POST /runs/batch takes links. Find sources for me is in the app only.
Request body
{
  "sources": [
    {
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    },
    {
      "url": "https://example.com/article"
    },
    {
      "text": "Notes from our customer calls…",
      "title": "Customer call notes"
    },
    {
      "documentUrl": "https://example.com/reports/q3.pdf",
      "title": "Q3 report"
    }
  ],
  "writingMethod": "summary",
  "targetDuration": 120
}

Highlights videos

Send recordingId, one of your recordings, instead of the other sources. As with Make highlights in the app, the AI picks the strongest moments of what is said, and they play as clips with the speaker’s own sound, joined by short bridges. The recording must be kept in the cloud and transcribed (see GET /recordings); otherwise the request is refused with highlights_recording before anything is charged.

  • highlightsStyle: narrated (the default) joins the clips with short spoken bridges, and the voice is charged for the bridges only; cards joins them with short text cards and has no voice.
  • A sound bite always says what the recording says. Its words are read again from the recording when the storyboard is approved, so cuts you make in the Video Editor before then are followed. If a bite’s words change after approval, the run fails before the render with retryable false; open the project in the app to approve the storyboard again. With review, frames with soundBite true can’t have their narration edited (sound_bite_words); edit the bridges around them instead.
  • Every sound bite must play. If one can’t (its words were cut, or the recording is no longer kept in the cloud), the render stops before anything is paid for it, with a retryable error.
  • There is no opening, ending, source credit or AI presenter: openingStyle, endingStyle, customSignOff, creditSource and presenter are refused with highlights_option(listed in highlights.unsupportedOptions in GET /options).
  • Estimate with sourceKind=recording and highlightsStyle. The run’s source.kind is recording, source.recordingId names the recording, and options.highlightsStyle shows the style (both null on other runs). Single runs only.
Request body
{
  "recordingId": "7d9f6c1e-2b3a-4c5d-8e9f-0a1b2c3d4e5f",
  "highlightsStyle": "narrated",
  "targetDuration": 90,
  "videoFormat": "vertical"
}

Documents

Send documentUrl, a public link to a PDF, Word (.docx) or PowerPoint (.pptx) file up to 50 MB, instead of url, text or script. The run starts from the document’s text, read with the same reader and limits as the app. The file is read in memory and never stored, and the run’s source shows it as pasted text.

  • For a file on your own computer, send its bytes to POST /documents/extract (free) and start the run with the returned text as text. Its notice says what was left out, such as image-only pages or hidden slides.
  • Files that can’t be read are refused before anything starts or is charged, with codes such as document_too_large, document_unsupported, document_old_format (.doc or .ppt), document_password and document_no_text_layer (scanned pages). Links to private addresses are refused with document_url_blocked.
  • documents.kinds and documents.maxMegabytes in GET /options list the file types and size limit.
Request body
{
  "documentUrl": "https://example.com/reports/q3.pdf",
  "title": "Q3 report",
  "targetDuration": 90
}

Review before render

Send review: true to read and change the script and the storyboard before the video is made. The run waits twice: once its script is written (its reviewStep is script) and again once its storyboard is ready (reviewStep storyboard). While it waits, its status stays running.

  1. Read what is waiting with GET /runs/{runId}/review.
  2. Change it if you like: the title and script with PATCH …/review/script, or frames by id with PATCH …/review/storyboard (their words, headline, supporting text, image prompt and director picks). Changes are saved on the run until you approve.
  3. Approve with POST …/review/approve. The run continues on its own within a few seconds; the voice-over reads exactly the approved storyboard’s words.
  • Credits are held when the run starts, as for any run. Reading, editing and approving cost nothing extra. Edits can’t add paid work beyond what the held credits cover: a script or spoken words longer than the run’s targetDuration allows (or than what was written for you), or more AI images, are refused with review_over_budget.
  • A run started from your own script only waits for the storyboard, because the script is spoken as written.
  • A run waits as long as you need. Cancel it with POST /runs/{runId}/cancel to return the held credits. To hear about a pause without polling, subscribe a webhook to run.review_waiting: it is sent once when the script is waiting and once when the storyboard is waiting, with data.run.reviewStep saying which. See Webhook events.
Request body
{
  "url": "https://example.com/article",
  "targetDuration": 90,
  "review": true
}

Long sources

Sources have a maximum length in characters: sourceMaxCharacters in GET /options (currently 200,000 by default; null means no limit). It can change, so read it rather than hard-coding it. Pasted text over the limit is refused when you start the run, with source_too_long, before anything is charged. A link whose transcript or page turns out to be too long fails before the script is written, and the run’s error says so.

Try your defaults now: curl https://www.vidonto.com/api/v1/options -H "Authorization: Bearer $VIDONTO_API_KEY", or see the GET /options reference.

Billing

Credits

Videos are paid for with credits from your account balance, the same balance the web app uses. Reading endpoints (runs, options, estimates, credits, webhooks) are free. Buy more on the Credits page in the app.

Held when a run starts, settled when it finishes

  • Start. The run’s estimated credits are held: they leave your spendable balance straight away, so two runs can’t both count on the same credits.
  • Each step. As each paid step finishes, it is charged for what it actually used. The charge comes out of the hold first. chargedCredits on the run shows the total so far.
  • Finish. When the run succeeds, fails or is cancelled, whatever is left of the hold is returned to your balance. Steps that never ran are never charged.
  • Retry. Retrying a failed run holds credits again for the steps still to run. Steps that already finished are not repeated or charged twice.

Estimate before you start

GET /estimate uses the same options and saved settings as a real run and tells you whether your balance covers it. Set count for a batch.

Estimate a batch of five vertical videos
curl "https://www.vidonto.com/api/v1/estimate?sourceKind=mixed&count=5&targetDuration=60" \
  -H "Authorization: Bearer $VIDONTO_API_KEY"

The estimate for links assumes a typical source length (assumedSourceMinutes). Longer sources and AI images cost more; the run is always charged for what it really used. See the GET /estimate reference.

Not enough credits: 402

If your balance does not cover the hold, the run does not start and nothing is charged. A batch starts all of its runs or none of them. The response says how many credits you have and how many were needed:

402 response
{
  "error": {
    "code": "insufficient_credits",
    "message": "This needs about 48 credits and your balance is 12.5. Get more credits to continue.",
    "balance": 12.5,
    "required": 48
  }
}

Balance and history

GET /credits returns your spendable balance. GET /credits/history lists every change, newest first, in pages (pass nextBefore back as before). Each entry’s credits is the change to your balance and balanceAfter the balance after it.

kindMeaning
reserveCredits held when a run started (negative).
chargeA finished step. charged is the step’s full price and step names it; credits is only the part the hold did not cover.
releaseThe unused part of a hold, returned when the run finished (positive).
grantCredits added to your account, such as starter credits.
purchaseCredits you bought.
refundCredits removed because a purchase was refunded.
adjustmentA manual correction.

Accounts that are not charged

Some accounts are not charged for videos. For them exempt is true on the balance, the estimate and the history entries, and holds and charges deduct nothing.

Reliability

Idempotency

Network errors happen. If a request to start a video times out, you can’t tell whether the run started. Send an Idempotency-Key header on POST /runs, POST /runs/batch and POST /recordings and repeat the request with the same key: the API starts the run, or adds the recording, at most once.

Header
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7
  • Use a new random value, such as a UUID, for each video you mean to start. Up to 255 printable characters, no spaces.
  • Keys are remembered for 24 hours per account. Repeating the same request returns the run that was already started, as it is now, with 202 (201 for a recording) and the header Idempotent-Replayed: true. No new credits are held.
  • The same key with a different body or endpoint returns 422 idempotency_key_reused. While the first request is still being handled, a repeat returns 409 idempotency_in_progress; wait a moment and send it again.
  • If the first request was refused (for example with 402 or a validation error), no run exists and the key is freed, so you can fix the problem and retry with the same key.

Reliability

Errors

Errors use standard HTTP status codes and always have the same JSON shape. Branch on error.code, which never changes; error.message is written for people and may change. Some errors add details next to the code.

422 response
{
  "error": {
    "code": "validation_error",
    "message": "targetDuration: Number must be greater than or equal to 10",
    "issues": [
      {
        "path": "targetDuration",
        "message": "Number must be greater than or equal to 10"
      }
    ]
  }
}
Statuserror.codeMeaning
400invalid_jsonThe request body is not valid JSON.
401missing_api_keyNo Authorization header, or it is not a Bearer token.
401invalid_api_keyThe key is wrong, was revoked, or its account is disabled.
402insufficient_creditsYour balance doesn’t cover the run. Includes balance and required.
403email_unverifiedConfirm your email address in the app before starting videos or adding webhooks.
404not_foundNo such run, recording, webhook, delivery or endpoint, or it belongs to another account.
404thumbnail_prompt_not_foundThe promptId isn’t one of your saved thumbnail prompts (see GET /thumbnail-prompts). Nothing was charged.
409video_not_readyThe run has no finished video yet. Includes the run’s status and stage.
409retry_not_safeThe run is not a failed run with retryable set, so it can’t be retried.
409conflictThe run or recording is in the wrong state for this action, such as cancelling a finished run or deleting a recording while it is being transcribed.
409transcript_not_readyThe recording is still being added or transcribed. Includes its status.
409recording_failedThe recording failed, so it has no transcript. The message says why.
409audio_in_appThe recording was made in the Vidonto app and its sound hasn’t been sent from the computer that has the video yet. Open it in the app there.
409not_uploadingThe recording isn’t waiting for file parts: it was added from a link, or every part has already arrived.
409upload_goneThe upload was given up (7 days after it started) or failed. Add the recording again.
409brand_missingThe brandId isn’t one of your brands (for example it was deleted), or the brand has no colours (or, with showLogo, no logo) saved in Settings. Nothing was charged.
409idempotency_in_progressA request with the same Idempotency-Key is still being handled. Try again shortly.
409webhook_limitThe account already has 10 webhook endpoints.
409webhook_busyAnother endpoint is being added at the same moment. Try again.
409delivery_busyThat delivery is being sent right now. Try again.
413payload_too_largeThe request body is too large.
422validation_errorA field is missing, has the wrong type or value, or is unknown. issues lists each problem with its path.
422invalid_sourceMore than one of url, text and script was sent.
422invalid_source_urlThe link is missing or is not a YouTube video or web page link.
422empty_textThe pasted text is empty.
422empty_scriptYour own script is empty.
422script_too_longYour own script is longer than ownScript.maxCharacters in GET /options.
422own_script_optionAn option that only steers the AI script was sent with script. The message names the fields.
422unknown_voiceThe voiceId is not in GET /options.
422invalid_sign_offThe custom ending’s sign-off is missing or too long.
422source_credit_incompleteCrediting pasted text needs a title.
422source_too_longThe pasted text is longer than sourceMaxCharacters in GET /options.
422presenter_unknownThe presenter’s avatarId is not in GET /options.
422presenter_too_longA presenter was asked for with a targetDuration over 10 minutes.
422presenter_rendererAdmin keys only: a presenter needs a Remotion renderProvider.
422show_logo_needs_brand_lookshowLogo true was sent without look brand.
422brand_id_needs_brand_lookbrandId was sent without look brand.
422brand_rendererAdmin keys only: the brand look needs a Remotion renderProvider.
422invalid_idempotency_keyThe Idempotency-Key is empty, too long or contains spaces.
422idempotency_key_reusedThe Idempotency-Key was already used with a different request.
422file_too_largeThe recording’s file is bigger than 16 GiB.
422invalid_urlThe recording link is not a public HTTPS address.
422link_refusedThe recording link answered with an error, needs a login or has expired.
422link_unreachableThe recording link couldn’t be reached, or redirected too many times.
422not_a_videoThe recording link opens a web page, not a video file. Use a direct download link.
422link_size_unknownThe recording link doesn’t say how big the file is.
422rights_not_confirmedA YouTube, TikTok, X or Facebook video page link needs rightsConfirmed: true (you own the video or have permission to use it).
422site_not_supportedVideos can’t be read from this site (Instagram, Vimeo). Download the video and upload the file instead.
422private_videoThe video page link is private. Age-restricted, members-only, live and sign-in-only videos are refused the same way, as age_restricted, members_only, live_video and login_required.
422site_failedThe video page couldn’t be read (site_blocked, site_timeout, region_blocked, video_not_found and no_video say why when known). Download the video and upload the file instead.
422invalid_webhook_urlThe webhook URL is not a public HTTPS address.
429rate_limitedToo many requests. Wait retryAfterSeconds (also in the Retry-After header).
500internal_errorSomething went wrong on our side. Try again.
503…_unavailableA service the run needs is temporarily unavailable, for example rendering_unavailable or narration_unavailable. Try again later.

A run that fails after it started is not an HTTP error: the run’s status becomes failed and its error explains why. See Wait for it to finish.

Reliability

Rate limits

Limits are counted per key and per account (all your keys together) in fixed one-minute windows. Going over returns 429 rate_limited with a Retry-After header and retryAfterSeconds in the body.

GroupEndpointsPer keyPer account
ReadingGetting and listing runs, cancelling, downloading videos, /options, /estimate, /credits, listing webhooks and deliveries120 / minute240 / minute
Starting videosPOST /runs, POST /runs/batch (one request however many links), POST /runs/{runId}/retry10 / minute20 / minute
Webhook changesAdding, changing, deleting, rotating, test events and resends30 / minute60 / minute
  • When you get a 429, wait the number of seconds given before trying again.
  • Poll a run every 5–10 seconds at most, or use webhooks instead of polling.
  • To start many videos, use POST /runs/batch with up to 100 links.
  • The OpenAPI document is not rate limited and needs no key.

Notifications

Webhooks

Instead of polling, give the API an HTTPS address and it will send a signed POST request there whenever one of your runs finishes, including runs started in the web app, and whenever a Video Editor recording is transcribed or fails. Add endpoints on the API keys page or with POST /webhooks; you can have up to 10.

Add an endpoint

Add an endpoint
curl -X POST https://www.vidonto.com/api/v1/webhooks \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/vidonto", "events": ["run.succeeded", "run.failed"]}'

The response includes the endpoint’s signing secret (it starts with whsec_). It is shown only once: store it with your other secrets. Then send a test event with POST /webhooks/{webhookId}/test to check your handler.

  • The URL must be a public HTTPS address. Private and local network addresses are refused.
  • Your endpoint must answer with a 2xx status within 10 seconds. Redirects are not followed and count as failures.
  • Answer first and do slow work afterwards, for example by putting the event on a queue.

Events

EventSent when
run.succeededA run finished and its video is ready to download.
run.failedA run failed. data.run.error says why and data.run.retryable whether it can be retried.
run.cancelledA run was cancelled, in the API or the web app.
run.review_waitingA run started with review: true is waiting for your approval. data.run.reviewStep is script or storyboard. Sent once per step, never twice for the same step, even after a retry.
recording.readyA recording was transcribed and is ready to edit, read or download its transcript. Includes recordings made in the app.
recording.failedAdding or transcribing a recording failed. data.recording.error says why; a recording added through the API or an assistant also has errorCode.
export.readyA cloud render, polished video or clip finished and its files are ready to download. Includes exports started in the app.
export.failedAn export failed. data.export.error says why; any formats that did finish are listed as ready (only those are charged).
webhook.testYou asked for a test event. Its run, recording and export are samples, not yours.

A run that fails and is then retried can finish again, so it can send run.failed and later run.succeeded, each as a separate event with its own ID. Events are only recorded for endpoints that are turned on and subscribed at the moment the run, recording or export finishes (or, for run.review_waiting, the moment the run starts waiting). Each export sends one event, when it is charged. A new endpoint receives every event type unless you pick some with events. An endpoint you made before an event type existed keeps its own list, so add the new type with PATCH /webhooks/{webhookId} or in the app.

Payload

The body is a JSON event. For run events, data.run is the same run object that GET /runs/{runId} returns. For recording events, data.recording is the same recording object that GET /recordings/{recordingId} returns, with the status the event is about. For export events, data.export is the same export object that GET /recordings/{recordingId}/exports/{exportId} returns, and data.recording names its recording (ID, title, file name, length and when it was added). A webhook.test event carries a sample of each.

Request headers
POST /hooks/vidonto HTTP/1.1
Content-Type: application/json
User-Agent: QuickSum-Webhooks/1.0
QuickSum-Event-Id: evt_6c1f0e9a2b7d4c3e8f5a1b2c3d4e5f60
QuickSum-Event-Type: run.succeeded
QuickSum-Timestamp: 1790856400
QuickSum-Signature: v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

The header names start with QuickSum-, the product’s former name. They stay the same so existing integrations keep working.

Request body
{
  "id": "evt_6c1f0e9a2b7d4c3e8f5a1b2c3d4e5f60",
  "type": "run.succeeded",
  "createdAt": "2026-10-01T12:06:40.000Z",
  "data": {
    "run": {
      "id": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
      "status": "succeeded",
      "stage": "done",
      "progress": 100,
      "error": null,
      "retryable": false,
      "title": "How transformers work",
      "name": null,
      "tags": [
        "Client A"
      ],
      "source": {
        "kind": "youtube",
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
      },
      "options": {
        "targetDuration": 90,
        "summaryModel": "gpt-6-luna",
        "videoFormat": "landscape",
        "textMode": "narration",
        "captionLength": "short",
        "aiImages": false,
        "voiceId": "21m00Tcm4TlvDq8ikWAM",
        "voiceModel": "eleven_v4",
        "transcriptLanguage": "en",
        "videoLanguage": "en",
        "openingStyle": "coming_up",
        "endingStyle": "none",
        "customSignOff": null,
        "creditSource": false,
        "instructions": null,
        "presenter": null,
        "look": "auto",
        "showLogo": false,
        "brandId": null,
        "videoQuality": "720p",
        "review": false,
        "animatedScenes": "off",
        "writingMethod": null
      },
      "stages": [
        {
          "id": "transcript",
          "label": "Fetching transcript",
          "status": "done",
          "progress": 100
        },
        {
          "id": "summary",
          "label": "Script",
          "status": "done",
          "progress": 100
        },
        {
          "id": "storyboard",
          "label": "Storyboard",
          "status": "done",
          "progress": 100
        },
        {
          "id": "render",
          "label": "Voiceover & render",
          "status": "done",
          "progress": 100
        }
      ],
      "reviewStep": null,
      "chargedCredits": 48.2,
      "video": {
        "downloadUrl": "/api/v1/runs/3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11/video",
        "durationSeconds": 92.4
      },
      "createdAt": "2026-10-01T12:00:00.000Z",
      "updatedAt": "2026-10-01T12:06:40.000Z"
    }
  }
}
Request body (recording event)
{
  "id": "evt_9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a",
  "type": "recording.ready",
  "createdAt": "2026-10-01T12:09:30.000Z",
  "data": {
    "recording": {
      "id": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
      "title": "Product demo",
      "fileName": "demo.mp4",
      "status": "ready",
      "error": null,
      "errorCode": null,
      "addedFrom": "api",
      "tags": [
        "Client A"
      ],
      "durationSeconds": 1265.4,
      "width": 1920,
      "height": 1080,
      "fileBytes": 734003200,
      "wordCount": 3120,
      "chapters": [
        {
          "title": "Introduction",
          "seconds": 0
        },
        {
          "title": "Setting up a project",
          "seconds": 142.6
        },
        {
          "title": "Sharing the result",
          "seconds": 811.2
        }
      ],
      "cloud": {
        "kept": true,
        "status": "kept",
        "paidThrough": "2026-10-31T12:04:10.000Z",
        "monthlyCredits": 14.6,
        "note": "Kept in the cloud until 2026-10-31, then renewed every 30 days for 14.6 credits."
      },
      "upload": null,
      "chargedCredits": 41.2,
      "createdAt": "2026-10-01T12:00:00.000Z",
      "updatedAt": "2026-10-01T12:09:30.000Z"
    }
  }
}
Request body (export event)
{
  "id": "evt_2a4c6e8f0b1d3f5a7c9e1b3d5f7a9c0e",
  "type": "export.ready",
  "createdAt": "2026-10-01T13:21:41.000Z",
  "data": {
    "export": {
      "id": "5e2b8d14-6c3a-4f7e-9b1d-0a2c4e6f8b3d",
      "recordingId": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
      "kind": "polished",
      "status": "ready",
      "resolution": null,
      "clipId": null,
      "clipTitle": null,
      "dubLanguage": null,
      "revision": 4,
      "editedSeconds": 1187.3,
      "estimatedCredits": 412.5,
      "progress": 1,
      "etaSeconds": null,
      "error": null,
      "files": [
        {
          "format": "landscape",
          "width": 1920,
          "height": 1080,
          "bytes": 412880311,
          "ready": true,
          "downloadUrl": "/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/exports/5e2b8d14-6c3a-4f7e-9b1d-0a2c4e6f8b3d/video?format=landscape"
        },
        {
          "format": "vertical",
          "width": 1080,
          "height": 1920,
          "bytes": 398120774,
          "ready": true,
          "downloadUrl": "/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/exports/5e2b8d14-6c3a-4f7e-9b1d-0a2c4e6f8b3d/video?format=vertical"
        }
      ],
      "createdAt": "2026-10-01T13:00:00.000Z",
      "finishedAt": "2026-10-01T13:21:40.000Z"
    },
    "recording": {
      "id": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
      "title": "Product demo",
      "fileName": "demo.mp4",
      "durationSeconds": 1265.4,
      "createdAt": "2026-10-01T12:00:00.000Z"
    }
  }
}

Verify the signature

Every request is signed with your endpoint’s secret, so you can be sure it came from Vidonto and was not changed. To check it:

  1. Read the QuickSum-Timestamp header (Unix seconds) and reject the request if it is more than 300 seconds from your clock. This stops old requests from being replayed.
  2. Compute an HMAC-SHA256 of <timestamp>.<raw request body>, using the whole secret, including whsec_, as the key. Hex-encode the result.
  3. Compare it, in constant time, with each v1= value in the QuickSum-Signature header. The header can hold several values separated by spaces; accept the request if any one matches.

Use the raw body

Compute the signature over the exact bytes you received. Parsing the JSON and serializing it again changes spacing and key order, and the signature will not match.
// Express example. Verify against the raw body, before any JSON parsing.
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const SECRET = process.env.VIDONTO_WEBHOOK_SECRET; // whsec_...
const TOLERANCE_SECONDS = 300;

function isValidSignature(rawBody, timestamp, signatureHeader) {
  if (!timestamp || !signatureHeader) return false;
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(age) || age > TOLERANCE_SECONDS) return false;
  const expected = createHmac("sha256", SECRET)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest();
  // The header can hold several space-separated "v1=" values.
  return signatureHeader.split(" ").some((part) => {
    if (!part.startsWith("v1=")) return false;
    const given = Buffer.from(part.slice(3), "hex");
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}

const handled = new Set(); // use a database table in production

const app = express();
app.post("/hooks/vidonto", express.raw({ type: "application/json" }), (req, res) => {
  if (!isValidSignature(req.body, req.get("QuickSum-Timestamp"), req.get("QuickSum-Signature"))) {
    return res.status(400).send("Invalid signature");
  }
  const event = JSON.parse(req.body.toString("utf8"));
  res.sendStatus(200); // answer within 10 seconds, then do the work

  if (handled.has(event.id)) return; // a retry of an event you already handled
  handled.add(event.id);
  if (event.type === "run.succeeded") {
    console.log("Video ready:", event.data.run.id, event.data.run.video.downloadUrl);
  }
});
app.listen(3000);
# Flask example. Verify against the raw body, before any JSON parsing.
import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request

SECRET = os.environ["VIDONTO_WEBHOOK_SECRET"].encode()  # whsec_...
TOLERANCE_SECONDS = 300
handled = set()  # use a database table in production


def is_valid_signature(raw_body, timestamp, signature_header):
    if not timestamp or not signature_header:
        return False
    try:
        if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
            return False
    except ValueError:
        return False
    expected = hmac.new(SECRET, timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    # The header can hold several space-separated "v1=" values.
    return any(
        part.startswith("v1=") and hmac.compare_digest(part[3:], expected)
        for part in signature_header.split(" ")
    )


app = Flask(__name__)


@app.post("/hooks/vidonto")
def vidonto_webhook():
    raw_body = request.get_data()
    if not is_valid_signature(
        raw_body,
        request.headers.get("QuickSum-Timestamp"),
        request.headers.get("QuickSum-Signature"),
    ):
        abort(400)
    event = json.loads(raw_body)
    if event["id"] not in handled:  # skip retries of events you already handled
        handled.add(event["id"])
        if event["type"] == "run.succeeded":
            print("Video ready:", event["data"]["run"]["id"])
    return "", 200

Retries

If your endpoint doesn’t answer with a 2xx status in time, the delivery is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours, 4 hours, 8 hours and 10 hours: 8 attempts over about a day. Every attempt has a fresh timestamp and signature but the same event ID and body. After the last attempt the delivery is marked failed.

  • When 5 events in a row run out of attempts, the endpoint is turned off and its disabledReason becomes failing. Events that happen while it is off are not sent later. Turn it back on in the app or with PATCH /webhooks/{webhookId} and {"enabled": true}.
  • See each endpoint’s recent deliveries, with status codes and errors, with GET /webhooks/{webhookId}/deliveries, and send one again with resend.
  • If you lose the secret or think it leaked, rotate it. The old secret stops working at once.

Handle each event once

Because of retries and resends, the same event can arrive more than once, and events can arrive out of order. Store the event id (also sent as the QuickSum-Event-Id header) when you handle an event, and skip any event whose ID you have already seen. If order matters, fetch the run with GET /runs/{runId} (or the recording with GET /recordings/{recordingId}) for its current state.

No code needed

Use Vidonto from an AI assistant

You can also connect Vidonto to an AI assistant such as Claude or ChatGPT, or to an AI coding tool such as Claude Code, Cursor or VS Code. Then you can ask it in plain words, for example “turn this article into a one-minute vertical video”, and it uses the same options, credits and run list as the API and the web app. There is no key to copy: you sign in to Vidonto and approve the assistant once.

Vidonto works as an MCP connector. MCP (Model Context Protocol) is the open standard these assistants use to call outside services. The connector address is the same for everyone:

Connector address
https://www.vidonto.com/api/mcp

Connect an assistant

  • In your assistant’s settings, add a custom connector (it may be called a connector, an app or an MCP server) and paste the address above. Which plans allow custom connectors is up to each assistant.
  • Your assistant opens a Vidonto page. Sign in if you are asked to, check what the assistant will be able to do and select Allow.
  • You are sent back to the assistant, which can now use Vidonto for you.

Coding tools are set up from a command or a settings file instead:

Claude Code
claude mcp add --transport http vidonto https://www.vidonto.com/api/mcp
Cursor (mcp.json)
{
  "mcpServers": {
    "vidonto": {
      "url": "https://www.vidonto.com/api/mcp"
    }
  }
}
VS Code (.vscode/mcp.json)
{
  "servers": {
    "vidonto": {
      "type": "http",
      "url": "https://www.vidonto.com/api/mcp"
    }
  }
}

The tool then opens the same Vidonto sign-in page in your browser. Sign-in uses OAuth 2.1 with PKCE and lets assistants register themselves, so nothing else needs setting up.

What the assistant can do

ToolWhat it does
get_optionsLists formats, voices, languages, opening and ending styles, AI presenters, looks, your brands and your saved defaults.
estimate_creditsEstimates the credits a video, or several, would use.
start_videoStarts a video from a YouTube link, a web page, pasted text, your own script, a PDF, Word file or deck at a link, or a highlights video of one of your recordings, in your default brand or another one picked with brandId, optionally with tags, an AI presenter placed where you like, and a pause for your review. Spends credits.
start_batchStarts one video per link, up to 100, with the same options. Spends credits.
get_runChecks a video’s progress and, when it is done, gives a link to it in the Vidonto app.
list_runsLists your videos, newest first, with the names you gave them, optionally only those with certain tags or matching a search.
rename_runNames a video, or clears its name. Only the name it is shown under changes.
cancel_runCancels a video that is still being made.
retry_runRetries a failed video from the step that failed. Spends credits.
get_creditsGets your credit balance.
get_run_reviewReads the script or storyboard a video started with review is waiting on.
edit_run_scriptChanges the waiting script or title before the storyboard is written.
edit_run_storyboardChanges frames of the waiting storyboard: their words, on-screen text, image prompt and where the presenter stands.
approve_run_reviewApproves the waiting script or storyboard so the video continues. Costs nothing extra.
list_brandsLists your brands with their colours, fonts and logos.
create_brandAdds a brand, empty or copied from another one.
update_brandChanges a brand’s name, colours, fonts or whether it is your default.
delete_brandDeletes a brand after you confirm. Videos already made keep it.
set_brand_logoSaves a brand’s logo, or its version for dark or light backgrounds, from a public picture link.
remove_brand_logoRemoves a brand’s logo after you confirm.
list_saved_introsLists your saved intros.
save_introSaves text and logo items as an intro to reuse at the start of recordings.
rename_introRenames a saved intro.
delete_introDeletes a saved intro after you confirm.
list_saved_stylesLists your saved polished-video styles.
save_styleSaves a polished-video look as a style, optionally as your default.
update_styleChanges a saved style’s name, look or whether it is your default.
delete_styleDeletes a saved style after you confirm.
list_recordingsLists your Video Editor recordings, optionally only those with certain tags or matching a search, with a link to open each one in the app.
get_recordingChecks a recording: its progress, length, chapters, tags and whether the video is kept in the cloud.
get_recording_transcriptReads a recording’s transcript, with your fixes to misheard words, optionally with each word’s timing.
set_recording_tagsReplaces a recording’s tags.
rename_recordingRenames a recording. Its edits stay as they are.
delete_recordingDeletes a recording after you confirm. A recording kept in the cloud stops being stored and charged.
estimate_recording_creditsEstimates the credits adding a video from a link would use, and what keeping it in the cloud costs every 30 days.
add_recording_from_linkAdds a video to your Video Editor from a YouTube, TikTok, X or Facebook link (after you confirm you own it or may use it) or a direct download link: it is kept in the cloud and transcribed, ready to edit in the app. Spends credits.
get_recording_editsReads a recording’s edits: cuts, word fixes, camera views, zooms, scenes, text and logo items, its look settings and your saved intros.
get_recording_suggestionsReads what the AI tools suggested for a recording, and which suggestions are waiting, accepted or dismissed.
estimate_recording_aiEstimates the credits an AI tool would use on a recording.
run_recording_aiRuns one of the editor’s AI tools on a recording: find mistakes, Direct my video, suggest scenes, make chapters or find short clips. Spends credits.
review_recording_suggestionsAccepts all, some or none of a tool’s suggestions, with the same rules as Accept all in the Video Editor.
edit_recordingEdits a recording: cuts and restores by words or exact times, word fixes, camera views, zooms, scenes, text and logo items, and saved intros. All or nothing.
set_recording_settingsChanges a recording’s AI model, background, AI avatar, camera shape, cleaned-up sound or polished-video options.
get_recording_dubsReads a recording’s dubs and the languages it can be dubbed into.
estimate_recording_dubsEstimates the credits dubbing a recording into some languages would use.
start_recording_dubsDubs a recording into up to five languages at a time. Spends credits.
estimate_recording_exportEstimates the credits a cloud render, polished video or clip would use, and says if anything stops it.
start_recording_exportRenders a recording in the cloud, as a polished video or as one short clip, with its sound or a dub. Spends credits.
list_recording_exportsReads a recording’s exports and how far along each one is.
get_recording_captionsGets an SRT or WebVTT caption file for the edited video or for one of its dubs.
get_recording_writingReads a recording’s description and posting text, article and chapters.
estimate_recording_writingEstimates the credits writing a description or an article would use.
write_recordingWrites a recording’s YouTube description and social posts, or a blog post or how-to article. Spends credits.
list_thumbnail_promptsLists your saved thumbnail prompts, so a thumbnail can use one.
save_thumbnail_promptSaves picture instructions as a named thumbnail prompt, optionally with one of your brands.
update_thumbnail_promptRenames a saved thumbnail prompt or changes its picture instructions. Its brand stays the same.
delete_thumbnail_promptDeletes a saved thumbnail prompt after you confirm.
estimate_recording_thumbnailEstimates the credits a recording thumbnail would use.
make_recording_thumbnailMakes a recording’s thumbnail with your headline, optionally in one of your brands with its logo and your picture instructions, or with one of your saved thumbnail prompts. Spends credits.
list_share_linksLists a recording’s viewer links and how often each was watched.
create_share_linkMakes a viewer link to a finished export or to the recording kept in the cloud. Each viewer uses credits.
end_share_linkEnds a viewer link for good.
estimate_run_thumbnailEstimates the credits a thumbnail for a finished summary video would use.
make_run_thumbnailMakes a thumbnail for a finished summary video, optionally in one of your brands with its logo and your picture instructions, or with one of your saved thumbnail prompts. Spends credits.

Finished videos are watched and downloaded in the Vidonto app, and the assistant gives you the link to each recording in the Video Editor. Its edits are the same as edits made in the app and show up there straight away; if the recording changed in the app since the assistant last read it, its change is refused and it reads the recording again. A background effect is only used in exports after the recording has been opened in the Video Editor, which checks that someone is on camera. A recording made in the app whose video is only on your computer can still be edited, but exports need the video kept in the cloud, and dubbing needs the recording opened once in the Video Editor (recordings added from a link are ready for both). Exports, dubs, written pieces and thumbnails are charged once, like in the app, and the assistant asks you before spending. It never gets download links: you watch and download exports in the Video Editor. The assistant can manage your brands, saved intros, saved styles and saved thumbnail prompts, but cannot buy credits, change your other account settings or password, or create API keys or webhooks.

Spending stays in your hands

Every tool that spends credits needs a credit limit you agreed to. The assistant is told to estimate first, tell you the figure and wait for your yes. If a video, or a recording once its length is known, would reserve more than the limit, nothing is started or charged. A repeated request is recognised and never starts or charges twice. Starting videos needs a verified email, as in the app.

See and disconnect assistants

Your Account page lists the assistants you connected and when each one last used Vidonto. Disconnect stops an assistant straight away; to use it again, connect it again. Resetting your password disconnects every assistant. An assistant stays signed in until you disconnect it or it goes unused for 30 days.

Assistants follow the API’s rate limits: each connected assistant counts like one key, and it shares the per-account limit with your keys.

Reference

Endpoint reference

Every path below is relative to https://www.vidonto.com/api/v1. The machine-readable version of this reference is the OpenAPI document, at openapi.json and openapi.yaml. Responses shorten long nested objects to { … }; the full run object is shown in the quickstart.

Runs

Start, follow, cancel and retry videos, and download the finished MP4.

Start a video from a link, pasted text, your own script or a document

POST/runs

Send exactly one of url, text, script or documentUrl, or a list of 2 to 5 sources for one video (see Several sources). A script is spoken exactly as written, with no AI script step and no script charge (see Your own script). The run’s estimated credits are held when it starts; you are charged for what each step actually uses and the rest is returned. With review true the run waits for your approval after its script and its storyboard (see Review before render). Needs a verified email address.

ParameterInTypeDescription
Idempotency-KeyheaderstringUp to 255 printable characters without spaces, such as a UUID. See Idempotency.
urlbodystringA YouTube video or web page link, up to 2,000 characters.
textbodystringPasted text to summarize, instead of url. Up to sourceMaxCharacters from GET /options (currently 200,000 by default).
scriptbodystringYour own script, spoken word for word, instead of url or text. Up to 20,000 characters.
documentUrlbodystringA public link to a PDF, Word (.docx) or PowerPoint (.pptx) file up to 50 MB, read as pasted text and never stored. See Documents.
sourcesbodyobject[]2 to 5 sources for one video, each {"url": …}, {"text": …, "title": …, "attribution": …} or {"documentUrl": …, "title": …, "attribution": …}, instead of the fields above. See Several sources.
writingMethodbodynew_piece | summaryWith sources only. Default new_piece.
lengthRangebodyobjectWith topic only: {"minSeconds": …, "maxSeconds": …} to let the AI choose the length inside the range, instead of targetDuration. Credits are held for the longest. See Options.
recordingIdbodystringOne of your recordings, kept in the cloud and transcribed, for a highlights video of it, instead of the fields above. See Highlights videos.
highlightsStylebodynarrated | cardsWith recordingId only. Default narrated.
titlebodystringA title for pasted text, your own script or a document, up to 300 characters. A script without one uses its first sentence; a document uses its own title.
tagsbodystring[]Labels for the run, such as a client’s name. Up to 10, each up to 30 characters, without commas. Letter case is ignored and a tag already used on your account keeps that spelling. Filter GET /runs by them.
targetDuration, videoFormat, …bodyoptionsAny of the video options. All are optional; omitted ones use your saved settings. See Options.
Example request
curl -X POST https://www.vidonto.com/api/v1/runs \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "targetDuration": 60, "videoFormat": "vertical"}'
Response · 202 Accepted
{
  "id": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
  "status": "running",
  "stage": "transcript",
  "progress": 0,
  "error": null,
  "retryable": false,
  "title": null,
  "name": null,
  "tags": [
    "Client A"
  ],
  "source": {
    "kind": "youtube",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  },
  "options": {
    "targetDuration": 90,
    "summaryModel": "gpt-6-luna",
    "videoFormat": "landscape",
    "textMode": "narration",
    "captionLength": "short",
    "aiImages": false,
    "voiceId": "21m00Tcm4TlvDq8ikWAM",
    "voiceModel": "eleven_v4",
    "transcriptLanguage": "en",
    "videoLanguage": "en",
    "openingStyle": "coming_up",
    "endingStyle": "none",
    "customSignOff": null,
    "creditSource": false,
    "instructions": null,
    "presenter": null,
    "look": "auto",
    "showLogo": false,
    "brandId": null,
    "videoQuality": "720p",
    "review": false,
    "animatedScenes": "off",
    "writingMethod": null
  },
  "stages": [
    {
      "id": "transcript",
      "label": "Fetching transcript",
      "status": "running",
      "progress": 0
    },
    {
      "id": "summary",
      "label": "Script",
      "status": "pending",
      "progress": 0
    },
    {
      "id": "storyboard",
      "label": "Storyboard",
      "status": "pending",
      "progress": 0
    },
    {
      "id": "render",
      "label": "Voiceover & render",
      "status": "pending",
      "progress": 0
    }
  ],
  "reviewStep": null,
  "chargedCredits": 0,
  "video": null,
  "createdAt": "2026-10-01T12:00:00.000Z",
  "updatedAt": "2026-10-01T12:00:00.000Z"
}

Errors: insufficient_credits, email_unverified, validation_error, invalid_source, invalid_source_url, multi_source_count, empty_text, empty_script, script_too_long, own_script_option, unknown_voice, source_too_long, presenter_placement_unused, document_too_large, document_unsupported, document_url_blocked, document_unreachable, idempotency_key_reused, idempotency_in_progress and the common errors.

Start one video per link

POST/runs/batch

Up to 100 links, all with the same options. Every link is checked before anything starts, and credits for all runs are held up front: if one link is invalid or your balance does not cover them all, nothing starts. Counts as one request for rate limits. Needs a verified email address.

ParameterInTypeDescription
Idempotency-KeyheaderstringUp to 255 printable characters without spaces, such as a UUID. See Idempotency.
urlsrequiredbodystring[]1 to 100 YouTube or web page links.
lengthRangebodyobjectWith topics only: the same range for every run; each run’s AI picks its own length inside it.
tagsbodystring[]Labels given to every run, with the same rules as a single run.
targetDuration, videoFormat, …bodyoptionsAny of the video options. All are optional; omitted ones use your saved settings. See Options.
Example request
curl -X POST https://www.vidonto.com/api/v1/runs/batch \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ", "https://example.com/article"], "targetDuration": 90}'
Response · 202 Accepted
{
  "runs": [
    {
      "id": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
      "status": "running",
      "stage": "transcript",
      "progress": 0,
      "error": null,
      "retryable": false,
      "title": null,
      "name": null,
      "tags": [
        "Client A"
      ],
      "source": { … },
      "options": { … },
      "stages": [ … ],
      "reviewStep": null,
      "chargedCredits": 0,
      "video": null,
      "createdAt": "2026-10-01T12:00:00.000Z",
      "updatedAt": "2026-10-01T12:00:00.000Z"
    },
    {
      "id": "5d2a8f14-3c7b-4e1a-9f60-8b2c4d6e0a13",
      "status": "running",
      "stage": "transcript",
      "progress": 0,
      "error": null,
      "retryable": false,
      "title": null,
      "name": null,
      "tags": [
        "Client A"
      ],
      "source": { … },
      "options": { … },
      "stages": [ … ],
      "reviewStep": null,
      "chargedCredits": 0,
      "video": null,
      "createdAt": "2026-10-01T12:00:00.000Z",
      "updatedAt": "2026-10-01T12:00:00.000Z"
    }
  ]
}

Errors: insufficient_credits, email_unverified, validation_error, invalid_source_url, idempotency_key_reused, idempotency_in_progress and the common errors.

List your runs, newest first

GET/runs

Includes runs started in the web app. Results come in pages; ask for the next one with page while hasMore is true.

ParameterInTypeDescription
tagsquerystringComma-separated tags, such as Client A,Q3. Only runs carrying every one of them are listed. Letter case is ignored.
qquerystringOnly runs whose name, title or link contains this text.
limitqueryintegerRuns per page, 1 to 100. Default 20.
pagequeryintegerWhich page, starting at 1. Default 1.
Example request
curl "https://www.vidonto.com/api/v1/runs?tags=Client%20A&limit=20" \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "runs": [
    {
      "id": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
      "status": "running",
      "stage": "render",
      "progress": 78,
      "error": null,
      "retryable": false,
      "title": "How transformers work",
      "name": null,
      "tags": [
        "Client A"
      ],
      "source": { … },
      "options": { … },
      "stages": [ … ],
      "reviewStep": null,
      "chargedCredits": 21.3,
      "video": null,
      "createdAt": "2026-10-01T12:00:00.000Z",
      "updatedAt": "2026-10-01T12:03:10.000Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1,
  "hasMore": false
}

Get one run’s status and progress

GET/runs/{runId}

Poll this until status is no longer running, or use a webhook.

ParameterInTypeDescription
runIdrequiredpathuuidThe run’s id.
Example request
curl https://www.vidonto.com/api/v1/runs/3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11 \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "id": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
  "status": "running",
  "stage": "render",
  "progress": 78,
  "error": null,
  "retryable": false,
  "title": "How transformers work",
  "name": null,
  "tags": [
    "Client A"
  ],
  "source": {
    "kind": "youtube",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  },
  "options": {
    "targetDuration": 90,
    "summaryModel": "gpt-6-luna",
    "videoFormat": "landscape",
    "textMode": "narration",
    "captionLength": "short",
    "aiImages": false,
    "voiceId": "21m00Tcm4TlvDq8ikWAM",
    "voiceModel": "eleven_v4",
    "transcriptLanguage": "en",
    "videoLanguage": "en",
    "openingStyle": "coming_up",
    "endingStyle": "none",
    "customSignOff": null,
    "creditSource": false,
    "instructions": null,
    "presenter": null,
    "look": "auto",
    "showLogo": false,
    "brandId": null,
    "videoQuality": "720p",
    "review": false,
    "animatedScenes": "off",
    "writingMethod": null
  },
  "stages": [
    {
      "id": "transcript",
      "label": "Fetching transcript",
      "status": "done",
      "progress": 100
    },
    {
      "id": "summary",
      "label": "Script",
      "status": "done",
      "progress": 100
    },
    {
      "id": "storyboard",
      "label": "Storyboard",
      "status": "done",
      "progress": 100
    },
    {
      "id": "render",
      "label": "Voiceover & render",
      "status": "running",
      "progress": 12
    }
  ],
  "reviewStep": null,
  "chargedCredits": 21.3,
  "video": null,
  "createdAt": "2026-10-01T12:00:00.000Z",
  "updatedAt": "2026-10-01T12:03:10.000Z"
}

Errors: not_found and the common errors.

Name a run, or clear its name

PUT/runs/{runId}/name

Sets the name the run is shown under, here (name) and in the web app. Only the name changes: the run’s title, its video, status and updatedAt stay as they are. Free.

ParameterInTypeDescription
runIdrequiredpathuuidThe run’s id.
namerequiredbodystring | nullUp to 200 characters; spaces at either end are removed. An empty name or null clears it.
Example request
curl -X PUT https://www.vidonto.com/api/v1/runs/3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11/name \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Client A launch video"}'
Response · 200 OK
{
  "id": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
  "status": "running",
  "stage": "render",
  "progress": 78,
  "error": null,
  "retryable": false,
  "title": "How transformers work",
  "name": "Client A launch video",
  "tags": [
    "Client A"
  ],
  "source": { … },
  "options": { … },
  "stages": [ … ],
  "reviewStep": null,
  "chargedCredits": 21.3,
  "video": null,
  "createdAt": "2026-10-01T12:00:00.000Z",
  "updatedAt": "2026-10-01T12:03:10.000Z"
}

Errors: not_found, validation_error and the common errors.

Cancel a run

POST/runs/{runId}/cancel

Works on running runs, and on failed runs you no longer want to retry. Credits held for steps that have not run yet are returned. Cancelling a run that already succeeded or was cancelled returns 409.

ParameterInTypeDescription
runIdrequiredpathuuidThe run’s id.
Example request
curl -X POST https://www.vidonto.com/api/v1/runs/3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11/cancel \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "id": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
  "status": "cancelled",
  "stage": "render",
  "progress": 78,
  "error": "Cancelled by user.",
  "retryable": false,
  "title": "How transformers work",
  "name": null,
  "tags": [
    "Client A"
  ],
  "source": { … },
  "options": { … },
  "stages": [ … ],
  "reviewStep": null,
  "chargedCredits": 21.3,
  "video": null,
  "createdAt": "2026-10-01T12:00:00.000Z",
  "updatedAt": "2026-10-01T12:03:10.000Z"
}

Errors: not_found, conflict and the common errors.

Retry a failed run from the step that failed

POST/runs/{runId}/retry

Only runs with retryable set to true. Steps that already finished are not repeated or charged again; credits are held again for the steps still to run. Needs a verified email address.

ParameterInTypeDescription
runIdrequiredpathuuidThe run’s id.
Example request
curl -X POST https://www.vidonto.com/api/v1/runs/3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11/retry \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 202 Accepted
{
  "id": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
  "status": "running",
  "stage": "render",
  "progress": 78,
  "error": null,
  "retryable": false,
  "title": "How transformers work",
  "name": null,
  "tags": [
    "Client A"
  ],
  "source": { … },
  "options": { … },
  "stages": [ … ],
  "reviewStep": null,
  "chargedCredits": 21.3,
  "video": null,
  "createdAt": "2026-10-01T12:00:00.000Z",
  "updatedAt": "2026-10-01T12:03:10.000Z"
}

Errors: not_found, retry_not_safe, conflict, insufficient_credits, email_unverified and the common errors.

Download the finished MP4

GET/runs/{runId}/video

Available once the run’s video field is set. The response is the MP4 itself (video/mp4), sent as an attachment unless inline=true. Supports HEAD and single Range requests such as Range: bytes=0-1048575, which answer 206 Partial Content; a range past the end of the file answers 416.

ParameterInTypeDescription
runIdrequiredpathuuidThe run’s id.
inlinequery"true" | "false"Send true to play the video in a browser instead of downloading it.
RangeheaderstringA single byte range, to resume or stream the download.
Example request
curl -fL -o summary.mp4 https://www.vidonto.com/api/v1/runs/3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11/video \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
(the MP4 file, with Content-Type: video/mp4, Content-Length and Accept-Ranges: bytes)

Errors: not_found, video_not_ready and the common errors.

Credits a thumbnail would use

GET/runs/{runId}/thumbnail/estimate

One picture. The brand, logo and instructions don’t change the price.

ParameterInTypeDescription
runIdrequiredpathuuidThe run’s id.
Example request
curl https://www.vidonto.com/api/v1/runs/3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11/thumbnail/estimate \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "runId": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
  "credits": 6,
  "balance": 1520,
  "exempt": false,
  "enoughCredits": true
}

Errors: not_found, video_not_ready and the common errors.

Make a thumbnail

POST/runs/{runId}/thumbnail

For a run with a finished video: an AI picture from the video’s title and frames, with your headline written into it by the AI as part of the design (the only text in it), sized to the video’s format, as the app’s posting kit makes. thumbnail_running (409) means another thumbnail or posting text is being made for the video. Waits for the picture (up to about a minute); only the latest is kept. Charged one picture, once, only when it is stored; thumbnail_failed and logo_unreadable (502) charge nothing. Leaving outbrandId means no brand (not your default brand), so a request with only a headline makes the plain thumbnail. A brand that isn’t yours or was deleted is refused with brand_missing, and a headline that’s empty or too long with headline_too_long, before anything is held. promptId uses one of your saved thumbnail prompts: its instructions and brand, unless you send instructions or brandId too. A prompt that isn’t yours is refused with thumbnail_prompt_not_found, and one whose brand was deleted with brand_missing, before anything is held; the price doesn’t change. Needs a verified email address.

ParameterInTypeDescription
runIdrequiredpathuuidThe run’s id.
Idempotency-KeyheaderstringUp to 255 printable characters without spaces, such as a UUID. See Idempotency.
headlinerequiredbodystring1 to 80 characters, written into the picture by the AI as its only text.
brandIdbodystringOne of your brands (from GET /brands): its colours guide the picture and the headline lettering, and its heading font’s style guides the lettering.
logobodybooleanThe brand’s logo in the top-right corner. Needs brandId, or a promptId whose prompt has a brand.
instructionsbodystringWhat the picture should show and how the headline lettering looks, up to 500 characters. It can’t add other words.
promptIdbodystringOne of your saved thumbnail prompts (from GET /thumbnail-prompts): its instructions and brand are used unless you send instructions or brandId too.
Example request
curl -X POST https://www.vidonto.com/api/v1/runs/3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11/thumbnail \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3c5e7a9b-1d2f-4b6c-8e0a-2c4e6a8c0e1f" \
  -d '{"headline": "Heat pumps in 90 seconds"}'
Response · 200 OK
{
  "runId": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
  "thumbnail": {
    "headline": "Heat pumps in 90 seconds",
    "size": "vertical",
    "width": 1080,
    "height": 1920,
    "createdAt": "2026-11-07T10:00:00.000Z",
    "brandId": null,
    "logo": false,
    "instructions": null,
    "downloadUrl": "/api/v1/runs/3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11/thumbnail"
  }
}

Errors: insufficient_credits, email_unverified, validation_error, not_found, video_not_ready, thumbnail_running, brand_missing, thumbnail_prompt_not_found, headline_too_long, thumbnail_failed, logo_unreadable, idempotency_key_reused, idempotency_in_progress and the common errors.

Download the latest thumbnail

GET/runs/{runId}/thumbnail

The JPEG itself (image/jpeg), sent as an attachment unless inline=true.thumbnail_not_found (404) until one is made.

ParameterInTypeDescription
runIdrequiredpathuuidThe run’s id.
inlinequery"true" | "false"Send true to show the picture in a browser instead of downloading it.
Example request
curl -fL -o thumbnail.jpg https://www.vidonto.com/api/v1/runs/3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11/thumbnail \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
(the JPEG file, with Content-Type: image/jpeg)

Errors: not_found, video_not_ready, thumbnail_not_found and the common errors.

Run review

Read, edit and approve a run’s script and storyboard before it renders, for runs started with review true.

Read the script or storyboard waiting for review

GET/runs/{runId}/review

For a run whose reviewStep is script, returns the title and script; for storyboard, the frames with their words, on-screen text, image prompt and director picks. edited is true once you saved a change. Refused with not_in_review while the run is still writing, after approval or once it finished, and with review_not_enabled for runs started without review.

ParameterInTypeDescription
runIdrequiredpathuuidThe run’s id.
Example request
curl https://www.vidonto.com/api/v1/runs/3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11/review \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "runId": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
  "reviewStep": "script",
  "edited": false,
  "script": {
    "title": "How transformers work",
    "text": "Transformers read a whole sentence at once. Attention lets every word look at every other word, so meaning comes from context."
  },
  "storyboard": null
}

Errors: not_found, not_in_review, review_not_enabled, storyboard_invalid and the common errors.

Edit the waiting script

PATCH/runs/{runId}/review/script

Changes the title, the script or both, saved on the run until you approve. Free. Refused with wrong_review_step while the storyboard is waiting, and with review_changed if another change or an approval happened at the same moment (read the review again and retry).

ParameterInTypeDescription
runIdrequiredpathuuidThe run’s id.
titlebodystringThe video’s title, up to 200 characters.
scriptbodystringThe whole script, up to 100,000 characters. The storyboard is written from it.
Example request
curl -X PATCH https://www.vidonto.com/api/v1/runs/3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11/review/script \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Transformers in two minutes"}'
Response · 200 OK
{
  "runId": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
  "reviewStep": "script",
  "edited": true,
  "script": {
    "title": "Transformers in two minutes",
    "text": "Transformers read a whole sentence at once. Attention lets every word look at every other word, so meaning comes from context."
  },
  "storyboard": null
}

Errors: not_found, validation_error, review_over_budget, not_in_review, review_not_enabled, wrong_review_step, review_changed and the common errors.

Edit frames of the waiting storyboard

PATCH/runs/{runId}/review/storyboard

Changes frames by id: the words spoken (narration), headline, supportingText, imagePrompt (null removes it), and the director picks presenter (full, beside or scene) and visual (layout, image or custom). Frames you don’t send are kept. The whole storyboard is checked with the app’s approval rules; an invalid result is refused with storyboard_invalid and nothing is saved. On-screen points follow the narration and can’t be edited. Free; edits needing more spoken words or AI images than the held credits cover are refused with review_over_budget.

ParameterInTypeDescription
runIdrequiredpathuuidThe run’s id.
framesrequiredbodyobject[]1 to 200 changes, each with the frame’s id and only the fields to change.
Example request
curl -X PATCH https://www.vidonto.com/api/v1/runs/3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11/review/storyboard \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"frames": [{"id": "b2", "headline": "Attention", "presenter": "beside"}]}'
Response · 200 OK
{
  "runId": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
  "reviewStep": "storyboard",
  "edited": true,
  "script": null,
  "storyboard": {
    "title": "How transformers work",
    "frames": [
      {
        "id": "b1",
        "role": "intro",
        "layout": "title",
        "narration": "Transformers read a whole sentence at once.",
        "headline": "Reading all at once",
        "supportingText": "",
        "imagePrompt": null,
        "points": [],
        "presenter": "full",
        "visual": "layout",
        "reason": "Opening line, spoken to camera."
      },
      {
        "id": "b2",
        "role": null,
        "layout": "bullets",
        "narration": "Attention lets every word look at every other word.",
        "headline": "Attention",
        "supportingText": "Meaning comes from context",
        "imagePrompt": null,
        "points": [
          "Every word",
          "Every other word"
        ],
        "presenter": "beside",
        "visual": "layout",
        "reason": "Chosen in review."
      }
    ]
  }
}

Errors: not_found, validation_error, unknown_frame, storyboard_invalid, review_over_budget, not_in_review, review_not_enabled, wrong_review_step, review_changed and the common errors.

Approve the waiting script or storyboard

POST/runs/{runId}/review/approve

Approves the step named in step, with any saved changes, and returns the run. It continues on its own within a few seconds: approving the script starts the storyboard (the run waits again once it’s ready), and approving the storyboard starts the render, which reads exactly the approved words. Charges nothing extra; credits were held when the run started. Needs a verified email address.

ParameterInTypeDescription
runIdrequiredpathuuidThe run’s id.
steprequiredbody"script" | "storyboard"The step you are approving: the run’s reviewStep.
lengthSecondsbodyintegerWith step sources of a topic run started with lengthRange: the length to write the script to, inside the range, instead of letting the AI pick. Refused with length_not_ranged, length_outside_range or length_after_sources.
Example request
curl -X POST https://www.vidonto.com/api/v1/runs/3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11/review/approve \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"step": "script"}'
Response · 200 OK
{
  "id": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
  "status": "running",
  "stage": "summary",
  "progress": 35,
  "error": null,
  "retryable": false,
  "title": "How transformers work",
  "name": null,
  "tags": [
    "Client A"
  ],
  "source": { … },
  "options": { … },
  "stages": [ … ],
  "reviewStep": null,
  "chargedCredits": 1.2,
  "video": null,
  "createdAt": "2026-10-01T12:00:00.000Z",
  "updatedAt": "2026-10-01T12:03:10.000Z"
}

Errors: not_found, email_unverified, validation_error, not_in_review, review_not_enabled, wrong_review_step, review_changed, storyboard_invalid and the common errors.

Documents

Read the text of a PDF, Word file or deck you have locally, to start a run with it.

Read the text of a PDF, Word or PowerPoint file

POST/documents/extract

Send the file’s bytes as the request body (any content type except JSON, for example application/octet-stream) and its name in fileName. Returns the text in reading order, ready to send as text to POST /runs. The type is read from the bytes. Free; the file is read in memory and never stored. notice mentions anything left out and warns when the text is longer than your source limit.

ParameterInTypeDescription
fileNamerequiredquerystringThe file’s name with its extension, such as report.pdf.
Example request
curl -X POST "https://www.vidonto.com/api/v1/documents/extract?fileName=q3.pdf" \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @q3.pdf
Response · 200 OK
{
  "kind": "pdf",
  "title": "Q3 report",
  "text": "Q3 report\n\nRevenue grew 18% on the quarter, led by the new subscription plans…",
  "pageCount": 12,
  "notice": null
}

Errors: validation_error, document_too_large, document_empty, document_unsupported, document_old_format, document_password, document_no_text_layer, document_too_long, document_too_complex, document_unreadable, document_busy and the common errors.

Options and estimates

The values each option accepts, your effective defaults, and credit estimates.

Allowed video options and your effective defaults

GET/options

defaults is exactly what a run gets when you send no options: your saved settings, filled in with the server defaults. Lists of voices and script models can change, so read them from here rather than hard-coding them. availability is false while script writing or narration is temporarily unavailable.

Example request
curl https://www.vidonto.com/api/v1/options \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "summaryModels": [
    { "id": "gpt-6.1-sol", "name": "…", "relativeCost": "moderate", "typicalCredits": 5.4 },
    …
  ],
  "videoFormats": [
    { "id": "landscape", "label": "YouTube", "purpose": "Regular videos", "aspectRatio": "16:9", "width": 1280, "height": 720 },
    { "id": "vertical", "label": "Shorts & TikTok", "purpose": "Vertical social video", "aspectRatio": "9:16", "width": 720, "height": 1280 },
    { "id": "square", "label": "Square", "purpose": "Social feeds", "aspectRatio": "1:1", "width": 1080, "height": 1080 },
    { "id": "portrait", "label": "Portrait", "purpose": "Instagram & social", "aspectRatio": "4:5", "width": 1080, "height": 1350 }
  ],
  "targetDuration": { "minSeconds": 10, "defaultSeconds": 90 },
  "textModes": ["narration", "key_points"],
  "captionLengths": [
    { "id": "short", "label": "Short", "description": "A few words at a time" },
    { "id": "medium", "label": "Medium", "description": "About one line at a time" },
    { "id": "sentence", "label": "Full sentence", "description": "A whole sentence at a time when it fits" }
  ],
  "voices": [{ "id": "21m00Tcm4TlvDq8ikWAM", "name": "Rachel" }, …],
  "voiceModels": [{ "id": "eleven_v4", "name": "Eleven v4" }],
  "transcriptLanguages": [{ "code": "en", "name": "English" }, …],
  "videoLanguages": [{ "id": "en", "name": "English", "nativeName": "English" }, { "id": "es", "name": "Spanish", "nativeName": "Español" }, …],
  "openingStyles": ["none", "coming_up", "cliffhanger", "question", "bottom_line"],
  "endingStyles": ["none", "recap", "takeaway", "reflection", "original", "custom"],
  "customSignOffMaxCharacters": 200,
  "sourceMaxCharacters": 200000,
  "instructionsMaxCharacters": 2000,
  "ownScript": {
    "maxCharacters": 20000,
    "unsupportedOptions": ["openingStyle", "endingStyle", "customSignOff", "creditSource", "summaryModel", "targetDuration"]
  },
  "aiImagesAvailable": true,
  "animatedScenes": { "available": true, "choices": ["off", "standard", "whole_video"], "creditsPerScene": 2.5, "minScenes": 4, "scenesPerMinute": 3, "wholeVideoScenesPerMinute": 8.57 },
  "looks": ["auto", "brand"],
  "brand": { "coloursSaved": true, "logoSaved": true },
  "brands": [
    { "id": "0d9e8f7a-6b5c-4d3e-9f2a-1b0c9d8e7f6a", "name": "Acme", "isDefault": true, "coloursSaved": true, "logoSaved": true, "fontsSaved": true },
    { "id": "5b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "name": "Client: Northwind", "isDefault": false, "coloursSaved": true, "logoSaved": true, "fontsSaved": false }
  ],
  "defaults": {
    "targetDuration": 90,
    "summaryModel": "gpt-6-luna",
    "videoFormat": "landscape",
    "textMode": "narration",
    "captionLength": "short",
    "aiImages": false,
    "voiceId": "21m00Tcm4TlvDq8ikWAM",
    "voiceModel": "eleven_v4",
    "transcriptLanguage": "en",
    "videoLanguage": "en",
    "openingStyle": "coming_up",
    "endingStyle": "none",
    "customSignOff": null,
    "creditSource": false,
    "instructions": null,
    "presenter": null,
    "look": "auto",
    "showLogo": false,
    "brandId": null,
    "videoQuality": "720p",
    "review": false,
    "animatedScenes": "off",
    "writingMethod": null
  },
  "availability": { "summary": true, "narration": true }
}

Estimate the credits for a video

GET/estimate

Omitted options use your saved settings, as when starting a run. Links are estimated for a typical source length (assumedSourceMinutes); the real charge depends on the source and what each step uses. enoughCredits tells you whether your balance covers totalCredits.

ParameterInTypeDescription
sourceKindqueryyoutube | webpage | text | script | mixed | multiDefault youtube. Use mixed for a batch of YouTube and web page links, script for your own script (set targetDuration to its spoken length; no script charge is included), and multi for one video from several sources.
sourceCountqueryintegerWith multi: how many sources, 2 to 5. Default 2.
youtubeSourcesqueryintegerWith multi: how many of them are YouTube videos. Default 0.
countqueryintegerNumber of videos, 1 to 100. Default 1.
targetDurationqueryintegerTarget length in seconds, at least 10.
summaryModelquerystringA script model id from GET /options.
aiImagesquery"true" | "false"Include AI images.
Example request
curl "https://www.vidonto.com/api/v1/estimate?sourceKind=youtube&count=1&targetDuration=90" \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "perRunCredits": 38.4,
  "count": 1,
  "totalCredits": 38.4,
  "assumedSourceMinutes": 10,
  "disclosure": "Estimated credits per video…",
  "balance": 412.5,
  "exempt": false,
  "enoughCredits": true,
  "options": {
    "sourceKind": "youtube",
    "targetDuration": 90,
    "summaryModel": "gpt-6-luna",
    "aiImages": false,
    "voiceModel": "eleven_v4",
    "presenter": false,
    "animatedScenes": "off",
    "videoFormat": "landscape",
    "videoQuality": "720p"
  }
}

Errors: validation_error and the common errors.

Credits

Your balance and every change to it.

Your credit balance

GET/credits

balance is what you can spend now; credits held by running videos are already taken out. It can be below zero after a refund or when a run cost more than its estimate.

Example request
curl https://www.vidonto.com/api/v1/credits \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "balance": 412.5,
  "exempt": false
}

Your credit history, newest first

GET/credits/history

One entry per change to your balance. To page back, pass the previous response’s nextBefore as before; it is null on the last page. See Credits for the entry kinds.

ParameterInTypeDescription
limitqueryinteger1 to 500. Default 100.
beforequeryISO 8601 timeOnly entries older than this.
Example request
curl "https://www.vidonto.com/api/v1/credits/history?limit=50" \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "entries": [
    {
      "id": "b71c2f0e-4d3a-4f8e-9a1b-6c5d4e3f2a10",
      "kind": "charge",
      "credits": 0,
      "charged": 9.8,
      "balanceAfter": 374.1,
      "exempt": false,
      "step": "summary",
      "note": null,
      "runId": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
      "jobId": null,
      "jobType": null,
      "title": "How transformers work",
      "createdAt": "2026-10-01T12:01:05.000Z"
    },
    {
      "id": "0a9e8d7c-6b5a-4f3e-8d2c-1b0a9f8e7d6c",
      "kind": "reserve",
      "credits": -38.4,
      "charged": 0,
      "balanceAfter": 374.1,
      "exempt": false,
      "step": null,
      "note": null,
      "runId": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
      "jobId": null,
      "jobType": null,
      "title": "How transformers work",
      "createdAt": "2026-10-01T12:00:00.000Z"
    }
  ],
  "nextBefore": "2026-10-01T12:00:00.000Z"
}

Errors: validation_error and the common errors.

Brands and saved items

The brands, characters, saved intros, saved styles and saved thumbnail prompts from Settings, with the same rules and limits as the app. Nothing here uses credits.

List your brands

GET/brands

Oldest first, with limit, the most you can keep. Logos are described by type, size and dimensions; download one with GET /brands/{brandId}/logo/{slot}.

Example request
curl https://www.vidonto.com/api/v1/brands \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "brands": [
    {
      "id": "5b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "name": "Northwind",
      "isDefault": true,
      "logo": {
        "contentType": "image/png",
        "bytes": 48213,
        "width": 800,
        "height": 240,
        "version": "b81c2f"
      },
      "logoAlt": null,
      "colours": {
        "background": "#0b1d3a",
        "text": "#ffffff",
        "accent": "#f5a524"
      },
      "fonts": {
        "heading": "montserrat",
        "body": "inter"
      },
      "createdAt": "2026-09-12T09:30:00.000Z",
      "updatedAt": "2026-10-01T11:02:00.000Z"
    }
  ],
  "limit": 20
}

Add a brand

POST/brands

An empty brand, or a copy of another brand’s colours, fonts and logos with copyFrom. Your first brand is the default. Up to 20 brands; more is refused with validation_error.

ParameterInTypeDescription
namerequiredbodystringUp to 60 characters.
copyFrombodyuuidA brand whose colours, fonts and logos the new one starts with.
Example request
curl -X POST https://www.vidonto.com/api/v1/brands \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Northwind"}'
Response · 201 Created
{
  "id": "5b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "name": "Northwind",
  "isDefault": true,
  "logo": null,
  "logoAlt": null,
  "colours": null,
  "fonts": null,
  "createdAt": "2026-09-12T09:30:00.000Z",
  "updatedAt": "2026-10-01T11:02:00.000Z"
}

Errors: validation_error and the common errors.

Change a brand

PATCH/brands/{brandId}

Send only what changes: name, colours (background, text and accent as #rrggbb), fonts (heading and body; null for the standard fonts), logoAltFor or isDefault. Videos already made keep their look.

ParameterInTypeDescription
brandIdrequiredpathuuidThe brand’s id.
name, colours, fonts, …bodyfieldsAny of the brand’s fields.
Example request
curl -X PATCH https://www.vidonto.com/api/v1/brands/5b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"colours": {"background": "#0b1d3a", "text": "#ffffff", "accent": "#f5a524"}}'
Response · 200 OK
{
  "id": "5b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "name": "Northwind",
  "isDefault": true,
  "logo": {
    "contentType": "image/png",
    "bytes": 48213,
    "width": 800,
    "height": 240,
    "version": "b81c2f"
  },
  "logoAlt": null,
  "colours": {
    "background": "#0b1d3a",
    "text": "#ffffff",
    "accent": "#f5a524"
  },
  "fonts": {
    "heading": "montserrat",
    "body": "inter"
  },
  "createdAt": "2026-09-12T09:30:00.000Z",
  "updatedAt": "2026-10-01T11:02:00.000Z"
}

Errors: not_found, validation_error and the common errors.

Delete a brand

DELETE/brands/{brandId}

Videos already made keep their brand. Runs started with this brandId afterwards are refused with brand_missing.

ParameterInTypeDescription
brandIdrequiredpathuuidThe brand’s id.
Example request
curl -X DELETE https://www.vidonto.com/api/v1/brands/5b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 204 No Content
(no body)

Errors: not_found and the common errors.

List your characters

GET/characters

The characters saved under Settings → Characters, oldest first, with the most you can keep. Send two ids as characterIds to make a conversation. castPosition is 0 or 1 for the default cast, else null. Characters are created and edited in the app.

Example request
curl https://www.vidonto.com/api/v1/characters \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "characters": [
    {
      "id": "5b2a8c1e-7d4f-4e9a-b3c6-1f0e2d3c4b5a",
      "name": "Maya",
      "voiceId": "21m00Tcm4TlvDq8ikWAM",
      "role": "Curious host, asks the questions",
      "castPosition": 0
    },
    {
      "id": "9c4e1a7b-2f3d-4b8e-a6c5-0d1e2f3a4b5c",
      "name": "Leo",
      "voiceId": "pNInz6obpgDQGcFmaJgB",
      "role": "Calm expert, explains with examples",
      "castPosition": 1
    }
  ],
  "limit": 20
}

List your saved intros

GET/intros

The text and logo items saved in the Video Editor to reuse at the start of recordings, with the most you can keep.

Example request
curl https://www.vidonto.com/api/v1/intros \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "intros": [
    {
      "id": "1e7d4c2b-9a8f-4b6e-a3d2-0c1b2a3f4e5d",
      "name": "Speaker name tag",
      "items": [
        {
          "start": 0,
          "end": 4,
          "kind": "text",
          "text": "Ada Lovelace",
          "style": "label",
          "position": "bottom-left",
          "size": "medium",
          "entrance": "slide",
          "opacity": 1
        }
      ],
      "createdAt": "2026-09-20T15:00:00.000Z",
      "updatedAt": "2026-09-20T15:00:00.000Z"
    }
  ],
  "limit": 20
}

Save an intro

POST/intros

A name and up to 12 text or logo items, timed in seconds from the start and ending within 5 minutes. At most 3 can show at the same time, as in the editor. Up to 20 intros.

ParameterInTypeDescription
namerequiredbodystringUp to 60 characters.
itemsrequiredbodyobject[]Each with start, end, kind (text or logo), its text and placement.
Example request
curl -X POST https://www.vidonto.com/api/v1/intros \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Speaker name tag", "items": [{"start": 0, "end": 4, "kind": "text", "text": "Ada Lovelace", "style": "label", "position": "bottom-left", "size": "medium", "entrance": "slide", "opacity": 1}]}'
Response · 201 Created
{
  "id": "1e7d4c2b-9a8f-4b6e-a3d2-0c1b2a3f4e5d",
  "name": "Speaker name tag",
  "items": [
    {
      "start": 0,
      "end": 4,
      "kind": "text",
      "text": "Ada Lovelace",
      "style": "label",
      "position": "bottom-left",
      "size": "medium",
      "entrance": "slide",
      "opacity": 1
    }
  ],
  "createdAt": "2026-09-20T15:00:00.000Z",
  "updatedAt": "2026-09-20T15:00:00.000Z"
}

Errors: validation_error and the common errors.

Rename a saved intro

PATCH/intros/{introId}

Only the name changes; save a new intro to change its items.

ParameterInTypeDescription
introIdrequiredpathuuidThe intro’s id.
namerequiredbodystringUp to 60 characters.
Example request
curl -X PATCH https://www.vidonto.com/api/v1/intros/1e7d4c2b-9a8f-4b6e-a3d2-0c1b2a3f4e5d \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Host name tag"}'
Response · 200 OK
{
  "id": "1e7d4c2b-9a8f-4b6e-a3d2-0c1b2a3f4e5d",
  "name": "Host name tag",
  "items": [
    {
      "start": 0,
      "end": 4,
      "kind": "text",
      "text": "Ada Lovelace",
      "style": "label",
      "position": "bottom-left",
      "size": "medium",
      "entrance": "slide",
      "opacity": 1
    }
  ],
  "createdAt": "2026-09-20T15:00:00.000Z",
  "updatedAt": "2026-09-20T15:00:00.000Z"
}

Errors: not_found, validation_error and the common errors.

Delete a saved intro

DELETE/intros/{introId}

Recordings that already use its items keep them.

ParameterInTypeDescription
introIdrequiredpathuuidThe intro’s id.
Example request
curl -X DELETE https://www.vidonto.com/api/v1/intros/1e7d4c2b-9a8f-4b6e-a3d2-0c1b2a3f4e5d \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 204 No Content
(no body)

Errors: not_found and the common errors.

List your saved thumbnail prompts

GET/thumbnail-prompts

The picture instructions (each optionally with a brand) saved here or in the app, oldest first, with the most you can keep. Pass one’s id as promptId when making a thumbnail. A prompt keeps its brandId if that brand is later deleted; using it then is refused with brand_missing unless you send another brandId.

Example request
curl https://www.vidonto.com/api/v1/thumbnail-prompts \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "prompts": [
    {
      "id": "8c2e4a6b-1d3f-4b5a-9e7c-2f4a6c8e0b1d",
      "name": "Desk shot",
      "instructions": "A laptop on a sunny desk, warm morning light",
      "brandId": "5b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "createdAt": "2026-10-02T08:15:00.000Z",
      "updatedAt": "2026-10-02T08:15:00.000Z"
    }
  ],
  "limit": 20
}

Save a thumbnail prompt

POST/thumbnail-prompts

A name and picture instructions, optionally with one of your brands. Up to 20 prompts; delete one to save another. A brandId that isn’t one of your brands is refused with brand_missing.

ParameterInTypeDescription
namerequiredbodystringUp to 60 characters.
instructionsrequiredbodystringWhat the picture should show. Up to 500 characters.
brandIdbodyuuid | nullOne of your brands (from GET /brands) to save with it. Leave it out for none.
Example request
curl -X POST https://www.vidonto.com/api/v1/thumbnail-prompts \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Desk shot","instructions":"A laptop on a sunny desk, warm morning light","brandId":"5b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"}'
Response · 201 Created
{
  "id": "8c2e4a6b-1d3f-4b5a-9e7c-2f4a6c8e0b1d",
  "name": "Desk shot",
  "instructions": "A laptop on a sunny desk, warm morning light",
  "brandId": "5b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "createdAt": "2026-10-02T08:15:00.000Z",
  "updatedAt": "2026-10-02T08:15:00.000Z"
}

Errors: validation_error, brand_missing and the common errors.

Rename a saved thumbnail prompt or change its instructions

PATCH/thumbnail-prompts/{promptId}

Send name, instructions or both. The saved brand never changes here: save a new prompt for another brand, or send brandId when making the thumbnail. Thumbnails already made keep their picture.

ParameterInTypeDescription
promptIdrequiredpathuuidThe prompt’s id.
namebodystringUp to 60 characters.
instructionsbodystringUp to 500 characters. They replace the saved ones.
Example request
curl -X PATCH https://www.vidonto.com/api/v1/thumbnail-prompts/8c2e4a6b-1d3f-4b5a-9e7c-2f4a6c8e0b1d \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Desk shot (evening)"}'
Response · 200 OK
{
  "id": "8c2e4a6b-1d3f-4b5a-9e7c-2f4a6c8e0b1d",
  "name": "Desk shot (evening)",
  "instructions": "A laptop on a sunny desk, warm morning light",
  "brandId": "5b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "createdAt": "2026-10-02T08:15:00.000Z",
  "updatedAt": "2026-10-02T08:15:00.000Z"
}

Errors: thumbnail_prompt_not_found, validation_error and the common errors.

Delete a saved thumbnail prompt

DELETE/thumbnail-prompts/{promptId}

Thumbnails already made keep their picture.

ParameterInTypeDescription
promptIdrequiredpathuuidThe prompt’s id.
Example request
curl -X DELETE https://www.vidonto.com/api/v1/thumbnail-prompts/8c2e4a6b-1d3f-4b5a-9e7c-2f4a6c8e0b1d \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 204 No Content
(no body)

Errors: thumbnail_prompt_not_found and the common errors.

List your saved styles

GET/styles

The polished-video looks saved in the Video Editor, with the most you can keep.

Example request
curl https://www.vidonto.com/api/v1/styles \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "styles": [
    {
      "id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
      "name": "Client look",
      "settings": {
        "formats": [
          "landscape",
          "vertical"
        ],
        "captions": true,
        "captionStyle": "highlight",
        "showTitleCard": true,
        "titleCardText": "Northwind update",
        "showEndCard": false,
        "endCardText": "",
        "showLowerThird": false,
        "lowerThirdName": "",
        "lowerThirdRole": "",
        "frameStyle": "rounded",
        "theme": "brand",
        "brandId": "5b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
      },
      "isDefault": false,
      "createdAt": "2026-09-22T10:00:00.000Z",
      "updatedAt": "2026-09-22T10:00:00.000Z"
    }
  ],
  "limit": 50
}

Save a style

POST/styles

A name and the look to keep: formats, captions, title and end cards, lower third, frame, theme and logo placement. A style with theme brand can name a brandId. isDefault makes it the style new recordings start with. Up to 50 styles.

ParameterInTypeDescription
namerequiredbodystringUp to 60 characters.
settingsrequiredbodyobjectThe look, as in the example.
isDefaultbodybooleanMake it your default style.
Example request
curl -X POST https://www.vidonto.com/api/v1/styles \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Client look","settings":{"formats":["landscape","vertical"],"captions":true,"captionStyle":"highlight","showTitleCard":true,"titleCardText":"Northwind update","showEndCard":false,"endCardText":"","showLowerThird":false,"lowerThirdName":"","lowerThirdRole":"","frameStyle":"rounded","theme":"brand","brandId":"5b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"}}'
Response · 201 Created
{
  "id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
  "name": "Client look",
  "settings": {
    "formats": [
      "landscape",
      "vertical"
    ],
    "captions": true,
    "captionStyle": "highlight",
    "showTitleCard": true,
    "titleCardText": "Northwind update",
    "showEndCard": false,
    "endCardText": "",
    "showLowerThird": false,
    "lowerThirdName": "",
    "lowerThirdRole": "",
    "frameStyle": "rounded",
    "theme": "brand",
    "brandId": "5b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
  },
  "isDefault": false,
  "createdAt": "2026-09-22T10:00:00.000Z",
  "updatedAt": "2026-09-22T10:00:00.000Z"
}

Errors: validation_error and the common errors.

Change a saved style

PATCH/styles/{styleId}

Send only what changes: name, settings (the whole look) or isDefault.

ParameterInTypeDescription
styleIdrequiredpathuuidThe style’s id.
name, settings, isDefaultbodyfieldsAny of the style’s fields.
Example request
curl -X PATCH https://www.vidonto.com/api/v1/styles/6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"isDefault": true}'
Response · 200 OK
{
  "id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
  "name": "Client look",
  "settings": {
    "formats": [
      "landscape",
      "vertical"
    ],
    "captions": true,
    "captionStyle": "highlight",
    "showTitleCard": true,
    "titleCardText": "Northwind update",
    "showEndCard": false,
    "endCardText": "",
    "showLowerThird": false,
    "lowerThirdName": "",
    "lowerThirdRole": "",
    "frameStyle": "rounded",
    "theme": "brand",
    "brandId": "5b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
  },
  "isDefault": true,
  "createdAt": "2026-09-22T10:00:00.000Z",
  "updatedAt": "2026-09-22T10:00:00.000Z"
}

Errors: not_found, validation_error and the common errors.

Delete a saved style

DELETE/styles/{styleId}

Videos already made keep their look.

ParameterInTypeDescription
styleIdrequiredpathuuidThe style’s id.
Example request
curl -X DELETE https://www.vidonto.com/api/v1/styles/6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 204 No Content
(no body)

Errors: not_found and the common errors.

Recordings

Add videos to your Video Editor, read their transcripts, tag and delete them. Recordings made in the app are listed too; their cloud field says whether the original video is kept in the cloud or only on the computer it was recorded on. Edit them with the Recording editing endpoints, and dub, export and share them with the Recording exports endpoints.

List your recordings

GET/recordings

Newest first, in pages. chapters is null in lists; get one recording for its chapters.

ParameterInTypeDescription
qquerystringOnly recordings whose title or file name contains this text.
tagsquerystringComma-separated tags. Only recordings carrying every one of them are listed.
statusquerystringprocessing (still being added or transcribed, including needs_audio), ready or failed.
limitqueryinteger1 to 100. Default 20.
pagequeryintegerStarting at 1. Ask for the next page while hasMore is true.
Example request
curl "https://www.vidonto.com/api/v1/recordings?tags=Client%20A&limit=20" \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "recordings": [
    {
      "id": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
      "title": "Product demo",
      "fileName": "demo.mp4",
      "status": "ready",
      "error": null,
      "errorCode": null,
      "addedFrom": "api",
      "tags": [
        "Client A"
      ],
      "durationSeconds": 1265.4,
      "width": 1920,
      "height": 1080,
      "fileBytes": 734003200,
      "wordCount": 3120,
      "chapters": null,
      "cloud": { … },
      "upload": null,
      "chargedCredits": 41.2,
      "createdAt": "2026-10-01T12:00:00.000Z",
      "updatedAt": "2026-10-01T12:09:30.000Z"
    },
    {
      "id": "2c4e6a8b-0d1f-4a3c-9e5b-7d9f1b3d5f70",
      "title": "Weekly update",
      "fileName": "weekly-update.webm",
      "status": "ready",
      "error": null,
      "errorCode": null,
      "addedFrom": "app",
      "tags": [],
      "durationSeconds": 1265.4,
      "width": 1920,
      "height": 1080,
      "fileBytes": 734003200,
      "wordCount": 3120,
      "chapters": null,
      "cloud": { … },
      "upload": null,
      "chargedCredits": 6.4,
      "createdAt": "2026-10-01T12:00:00.000Z",
      "updatedAt": "2026-10-01T12:09:30.000Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 2,
  "hasMore": false
}

Errors: validation_error and the common errors.

Estimate adding a recording

GET/recordings/estimate

The credits adding a video would hold: keeping the original and an editing copy in the cloud for the first 30 days, transcription and the automatic mistake check, plus monthlyCredits every 30 days after that. Send the file’s size or the link you would add. For a YouTube, TikTok, X or Facebook video page, its length and size are read from the page and site and title say which video it is. Otherwise the length is assumed from the size unless you send durationSeconds.

ParameterInTypeDescription
totalBytesqueryintegerThe file’s size, instead of url.
urlquerystringThe link you would add: a YouTube, TikTok, X or Facebook video page, or a direct download link (its size is read from it).
durationSecondsquerynumberThe video’s length, for a closer figure.
Example request
curl "https://www.vidonto.com/api/v1/recordings/estimate?totalBytes=734003200&durationSeconds=1265" \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "totalBytes": 734003200,
  "storageCredits": 30.8,
  "transcriptionCredits": 10.9,
  "totalCredits": 41.7,
  "monthlyCredits": 14.6,
  "assumedDurationSeconds": null,
  "disclosure": "Storing is held for the original plus an editing copy and charged on the actual size once it has been transcribed…",
  "site": null,
  "title": null,
  "balance": 412.5,
  "exempt": false,
  "enoughCredits": true
}

Errors: validation_error, invalid_url, link_refused, link_unreachable, not_a_video, link_size_unknown, file_too_large, site_not_supported, private_video, site_failed and the common errors.

Add a recording by upload or from a link

POST/recordings

Adds an MP4, MOV, WebM or MKV file, up to 16 GiB and 6 hours. It is kept in the cloud and transcribed on the server, the same as a recording kept in the cloud from the app. With source: "upload", send the file in parts (see upload links). With source: "link", Vidonto downloads a YouTube, TikTok, X or Facebook video page (one public video; send rightsConfirmed: true to confirm you own it or have permission to use it) or a direct HTTPS link anyone can open. Storage is held when it starts and charged on the actual size once it has been transcribed; transcription is held once the length is known and charged on the actual length. A recording that fails, while being added or transcribed, is never charged for storage and its files are deleted. Follow progress with GET /recordings/{recordingId} or the recording webhooks. Needs a verified email address.

ParameterInTypeDescription
Idempotency-KeyheaderstringUp to 255 printable characters without spaces, such as a UUID. See Idempotency.
sourcerequiredbodystringupload or link.
urlbodystringFor link: a YouTube, TikTok, X or Facebook video page, or a direct HTTPS download link.
rightsConfirmedbodybooleanFor link: true confirms you own the video or have permission to use it. Required for a video page link.
fileNamebodystringRequired for upload. For a link, defaults to the page’s title or the link’s last part.
totalBytesbodyintegerFor upload: the file’s size in bytes.
contentTypebodystringFor upload: a video type such as video/mp4.
titlebodystringUp to 200 characters. Defaults to the video page’s title, or the file name.
tagsbodystring[]Up to 10 labels, as for runs.
Example request
curl -X POST https://www.vidonto.com/api/v1/recordings \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0e5b1c2d-8f3a-4d6e-9b7c-1a2b3c4d5e6f" \
  -d '{"source": "upload", "fileName": "demo.mp4", "totalBytes": 734003200, "contentType": "video/mp4", "title": "Product demo", "tags": ["Client A"]}'
Response · 201 Created
{
  "id": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
  "title": "Product demo",
  "fileName": "demo.mp4",
  "status": "uploading",
  "error": null,
  "errorCode": null,
  "addedFrom": "api",
  "tags": [
    "Client A"
  ],
  "durationSeconds": null,
  "width": null,
  "height": null,
  "fileBytes": 734003200,
  "wordCount": 0,
  "chapters": [],
  "cloud": {
    "kept": false,
    "status": "uploading",
    "paidThrough": null,
    "monthlyCredits": null,
    "note": "The video is kept in the cloud once its file has arrived and been prepared."
  },
  "upload": {
    "partBytes": 16777216,
    "partCount": 44,
    "receivedParts": [],
    "totalBytes": 734003200,
    "expiresAt": "2026-10-08T12:00:00.000Z"
  },
  "chargedCredits": 0,
  "createdAt": "2026-10-01T12:00:00.000Z",
  "updatedAt": "2026-10-01T12:00:00.000Z"
}

Errors: insufficient_credits, email_unverified, validation_error, invalid_url, link_refused, link_unreachable, not_a_video, link_size_unknown, file_too_large, rights_not_confirmed, site_not_supported, private_video, site_failed, idempotency_key_reused, idempotency_in_progress and the common errors.

Confirm uploaded parts

POST/recordings/{recordingId}/upload/confirm

Checks each part arrived whole. Parts that didn’t are listed in rejectedParts (part_missing or part_incomplete): upload them again and confirm them. When every part is confirmed, the recording’s status becomes preparing.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
partsrequiredbodyinteger[]Part numbers, starting at 0. 1 to 50 per request.
Example request
curl -X POST https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/upload/confirm \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parts": [0, 1]}'
Response · 200 OK
{
  "recording": {
    "id": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
    "title": "Product demo",
    "fileName": "demo.mp4",
    "status": "uploading",
    "error": null,
    "errorCode": null,
    "addedFrom": "api",
    "tags": [
      "Client A"
    ],
    "durationSeconds": null,
    "width": null,
    "height": null,
    "fileBytes": 734003200,
    "wordCount": 0,
    "chapters": [],
    "cloud": { … },
    "upload": {
      "partBytes": 16777216,
      "partCount": 44,
      "receivedParts": [
        0,
        1
      ],
      "totalBytes": 734003200,
      "expiresAt": "2026-10-08T12:00:00.000Z"
    },
    "chargedCredits": 0,
    "createdAt": "2026-10-01T12:00:00.000Z",
    "updatedAt": "2026-10-01T12:00:00.000Z"
  },
  "rejectedParts": []
}

Errors: not_found, validation_error, not_uploading, upload_gone and the common errors.

Get one recording

GET/recordings/{recordingId}

status is uploading, fetching, preparing, transcribing, ready, failed (see error and errorCode) or needs_audio for a recording made in the app whose sound hasn’t been sent from that computer yet. chapters start times are in the edited video.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
Example request
curl https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "id": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
  "title": "Product demo",
  "fileName": "demo.mp4",
  "status": "ready",
  "error": null,
  "errorCode": null,
  "addedFrom": "api",
  "tags": [
    "Client A"
  ],
  "durationSeconds": 1265.4,
  "width": 1920,
  "height": 1080,
  "fileBytes": 734003200,
  "wordCount": 3120,
  "chapters": [
    {
      "title": "Introduction",
      "seconds": 0
    },
    {
      "title": "Setting up a project",
      "seconds": 142.6
    },
    {
      "title": "Sharing the result",
      "seconds": 811.2
    }
  ],
  "cloud": {
    "kept": true,
    "status": "kept",
    "paidThrough": "2026-10-31T12:04:10.000Z",
    "monthlyCredits": 14.6,
    "note": "Kept in the cloud until 2026-10-31, then renewed every 30 days for 14.6 credits."
  },
  "upload": null,
  "chargedCredits": 41.2,
  "createdAt": "2026-10-01T12:00:00.000Z",
  "updatedAt": "2026-10-01T12:09:30.000Z"
}

Errors: not_found and the common errors.

Read a recording’s transcript

GET/recordings/{recordingId}/transcript

With your fixes to misheard words applied. Words keep their position, so times line up with the original video; the second and later words of a fix covering several words come back empty. Before the transcript exists the answer is 409: transcript_not_ready, recording_failed, or audio_in_app for a recording made in the app whose sound must be sent from that computer.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
wordsquerystringfalse to leave out the word list (words is then null). Default true.
Example request
curl https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/transcript \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "recordingId": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
  "languageCode": "eng",
  "durationSeconds": 1265.4,
  "wordCount": 3120,
  "text": "Welcome to the demo. Today I will show you…",
  "words": [
    {
      "index": 0,
      "text": "Welcome",
      "start": 0.42,
      "end": 0.81,
      "type": "word"
    },
    {
      "index": 1,
      "text": "to",
      "start": 0.81,
      "end": 0.93,
      "type": "word"
    },
    {
      "index": 2,
      "text": "the",
      "start": 0.93,
      "end": 1.05,
      "type": "word"
    },
    {
      "index": 3,
      "text": "demo.",
      "start": 1.05,
      "end": 1.5,
      "type": "word"
    },
    …
  ]
}

Errors: not_found, transcript_not_ready, recording_failed, audio_in_app, validation_error and the common errors.

Rename a recording

PUT/recordings/{recordingId}/title

Only the title changes: the recording’s edits, edit revision and updatedAt stay as they are, so an editor open on it keeps working. Exports made later use the new name; finished ones don’t change. Free.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
titlerequiredbodystringUp to 300 characters, not empty; spaces at either end are removed.
Example request
curl -X PUT https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/title \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Product demo (final)"}'
Response · 200 OK
{
  "id": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
  "title": "Product demo (final)",
  "fileName": "demo.mp4",
  "status": "ready",
  "error": null,
  "errorCode": null,
  "addedFrom": "api",
  "tags": [
    "Client A"
  ],
  "durationSeconds": 1265.4,
  "width": 1920,
  "height": 1080,
  "fileBytes": 734003200,
  "wordCount": 3120,
  "chapters": [ … ],
  "cloud": { … },
  "upload": null,
  "chargedCredits": 41.2,
  "createdAt": "2026-10-01T12:00:00.000Z",
  "updatedAt": "2026-10-01T12:09:30.000Z"
}

Errors: not_found, validation_error and the common errors.

Replace a recording’s tags

PUT/recordings/{recordingId}/tags

Send an empty list to remove them all. A tag already used on your account keeps that spelling.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
tagsrequiredbodystring[]Up to 10, each up to 30 characters.
Example request
curl -X PUT https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/tags \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["Client A", "Q3"]}'
Response · 200 OK
{
  "id": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
  "title": "Product demo",
  "fileName": "demo.mp4",
  "status": "ready",
  "error": null,
  "errorCode": null,
  "addedFrom": "api",
  "tags": [
    "Client A",
    "Q3"
  ],
  "durationSeconds": 1265.4,
  "width": 1920,
  "height": 1080,
  "fileBytes": 734003200,
  "wordCount": 3120,
  "chapters": [ … ],
  "cloud": { … },
  "upload": null,
  "chargedCredits": 41.2,
  "createdAt": "2026-10-01T12:00:00.000Z",
  "updatedAt": "2026-10-01T12:09:30.000Z"
}

Errors: not_found, validation_error and the common errors.

Delete a recording

DELETE/recordings/{recordingId}

Deletes the recording and everything made from it in the editor. A recording kept in the cloud stops being stored and charged, and its stored files are deleted. This can’t be undone.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
Example request
curl -X DELETE https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "id": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
  "deleted": true,
  "cloudStorageEnded": true
}

Errors: not_found, conflict and the common errors.

Recording editing

Edit a ready recording the way the Video Editor does: run its AI tools and accept their suggestions, cut, fix misheard words, and place camera views, zooms, scenes, text and logos. Changes use the editor’s own rules and show up in the app straight away. Times are seconds on the original recording and word numbers are indexes from the transcript with words=true. Every change sends the revision it was based on; if the recording changed since (in the app or another call), nothing is saved and edit_conflict gives the current revision. Only the AI tools spend credits.

A recording’s edits and settings

GET/recordings/{recordingId}/edits

Cuts (by words and by exact times), word fixes, camera views, zooms, scenes, text and logo items, the look settings, your saved intros and the current revision.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
Example request
curl https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/edits \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "recordingId": "7a1d3f5b-9c2e-4b6a-8d0f-1e3c5a7b9d20",
  "revision": 4,
  "durationSeconds": 1265.4,
  "editedSeconds": 1198.7,
  "cuts": {
    "removedSeconds": 66.7,
    "cutRegions": 9,
    "words": [
      {
        "id": "5f2c9a1e-3b7d-4e8a-9c6f-0d1e2f3a4b5c",
        "startWord": 120,
        "endWord": 131,
        "start": 48.21,
        "end": 52.9
      }
    ],
    "times": [
      {
        "id": "8d3e1f2a-4b5c-4d6e-8f7a-9b0c1d2e3f4a",
        "start": 61.2,
        "end": 63.5
      }
    ],
    "acceptedSuggestions": 7,
    "waitingSuggestions": 3
  },
  "wordFixes": [
    {
      "startWord": 8,
      "endWord": 9,
      "text": "Vidonto",
      "original": "video toe"
    }
  ],
  "views": [
    {
      "id": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
      "start": 0,
      "end": 12,
      "layout": "bubble",
      "framing": null,
      "corner": "bottom-right",
      "bubbleSize": "medium"
    }
  ],
  "zooms": [
    {
      "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "startWord": 40,
      "endWord": 52,
      "kind": "push",
      "start": 16.4,
      "end": 21.8
    }
  ],
  "scenes": [],
  "items": [
    {
      "id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f60",
      "start": 2,
      "end": 5,
      "kind": "text",
      "text": "Welcome",
      "style": "title",
      "position": "center",
      "size": "medium",
      "entrance": "fade",
      "opacity": 1
    }
  ],
  "settings": {
    "aiModel": null,
    "background": {
      "kind": "none"
    },
    "backgroundExportProblem": null,
    "avatar": null,
    "camera": {
      "style": "circle",
      "flush": false
    },
    "cleanSound": {
      "available": true,
      "enabled": true,
      "strength": 0.8
    },
    "polish": { … }
  },
  "savedIntros": [
    {
      "id": "3e4f5a6b-7c8d-4e9f-8a0b-1c2d3e4f5a6b",
      "name": "Channel intro",
      "itemCount": 2
    }
  ]
}

Errors: not_found, not_ready and the common errors.

Apply edits, all or nothing

POST/recordings/{recordingId}/edits

Up to 50 operations, applied in order and saved together. If one is refused, nothing is saved and edit_refused says which and why. Each operation sends only the fields its type uses: cut_words / restore_words / restore_word_text (startWord, endWord), cut_time / restore_time (start, end), fix_words (plus text), set_view (start, end, layout, optional framing, corner, bubbleSize), add_zoom (word range, optional zoomKind), put_scene (word range and scene; with id to change one), add_item (kind, start, optional end, text and look), update_item, move_view / move_item (id, start), add_intro (introId, optional at on the edited video) and remove_view / remove_zoom / remove_scene / remove_item (id). A range touching a fixed phrase covers the whole phrase. Zooms and scenes can’t overlap another of their kind, and a full-screen scene can’t cover a zoom.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
revisionrequiredbodyintegerThe revision these edits are based on.
operationsrequiredbodyobject[]1 to 50 operations.
Example request
curl -X POST https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/edits \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"revision": 4, "operations": [{"type": "cut_words", "startWord": 120, "endWord": 131}, {"type": "fix_words", "startWord": 8, "endWord": 9, "text": "Vidonto"}, {"type": "add_zoom", "startWord": 40, "endWord": 52, "zoomKind": "push"}]}'
Response · 200 OK
{
  "results": [
    {
      "type": "cut_words"
    },
    {
      "type": "fix_words"
    },
    {
      "type": "add_zoom",
      "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
    }
  ],
  "edits": {
    "recordingId": "7a1d3f5b-9c2e-4b6a-8d0f-1e3c5a7b9d20",
    "revision": 5,
    "durationSeconds": 1265.4,
    "editedSeconds": 1198.7,
    "cuts": {
      "removedSeconds": 66.7,
      "cutRegions": 9,
      "words": [
        {
          "id": "5f2c9a1e-3b7d-4e8a-9c6f-0d1e2f3a4b5c",
          "startWord": 120,
          "endWord": 131,
          "start": 48.21,
          "end": 52.9
        }
      ],
      "times": [
        {
          "id": "8d3e1f2a-4b5c-4d6e-8f7a-9b0c1d2e3f4a",
          "start": 61.2,
          "end": 63.5
        }
      ],
      "acceptedSuggestions": 7,
      "waitingSuggestions": 3
    },
    "wordFixes": [
      {
        "startWord": 8,
        "endWord": 9,
        "text": "Vidonto",
        "original": "video toe"
      }
    ],
    "views": [
      {
        "id": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
        "start": 0,
        "end": 12,
        "layout": "bubble",
        "framing": null,
        "corner": "bottom-right",
        "bubbleSize": "medium"
      }
    ],
    "zooms": [
      {
        "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
        "startWord": 40,
        "endWord": 52,
        "kind": "push",
        "start": 16.4,
        "end": 21.8
      }
    ],
    "scenes": [],
    "items": [
      {
        "id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f60",
        "start": 2,
        "end": 5,
        "kind": "text",
        "text": "Welcome",
        "style": "title",
        "position": "center",
        "size": "medium",
        "entrance": "fade",
        "opacity": 1
      }
    ],
    "settings": { … },
    "savedIntros": [
      {
        "id": "3e4f5a6b-7c8d-4e9f-8a0b-1c2d3e4f5a6b",
        "name": "Channel intro",
        "itemCount": 2
      }
    ]
  }
}

Errors: validation_error, edit_refused, edit_conflict, not_found, not_ready and the common errors.

Change a recording’s look settings

PUT/recordings/{recordingId}/settings

Send revision and only what changes: aiModel, background (none, blur with blurStrength, colour with backgroundColour, or image to keep the picture chosen in the app), avatarId (from presenters in GET /options; null for none), cameraStyle, cameraFlush, cleanSound and cleanSoundStrength (0 to 1; mixes in the sound cleaned up in the Video Editor, once cleanSound.available is true) and polish (only the options sent change). A background effect is only used in exports once the recording has been opened in the Video Editor, which checks someone is on camera; backgroundExportProblem says when that is still needed. Settings don’t change the revision.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
revisionrequiredbodyintegerThe current revision.
aiModel, background, avatarId, …bodysettingsThe settings to change.
Example request
curl -X PUT https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/settings \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"revision": 4, "cameraStyle": "portrait", "polish": {"captions": true, "formats": ["landscape", "vertical"]}}'
Response · 200 OK
{
  "recordingId": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
  "revision": 4,
  "settings": {
    "aiModel": null,
    "background": {
      "kind": "none"
    },
    "backgroundExportProblem": null,
    "avatar": null,
    "camera": {
      "style": "portrait",
      "flush": false
    },
    "cleanSound": {
      "available": true,
      "enabled": true,
      "strength": 0.8
    },
    "polish": { … }
  }
}

Errors: validation_error, edit_conflict, not_found, not_ready, avatar_unknown, avatar_unavailable and the common errors.

Credits an AI tool would use

GET/recordings/{recordingId}/ai/estimate

Priced on the recording’s current edits, with the same options as running the tool.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
toolrequiredquerystringmistakes, scenes, director, chapters or clips.
summaryModelquerystringThe AI model. Defaults to the recording’s, then your saved one.
formatquerystringFor director: landscape, vertical or square.
requestquerystringFor clips: what to look for, up to 200 characters.
Example request
curl "https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/ai/estimate?tool=director&format=vertical" \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "tool": "director",
  "credits": 6.4,
  "balance": 1520,
  "exempt": false,
  "enoughCredits": true
}

Errors: validation_error, not_found, not_ready and the common errors.

Run an AI tool

POST/recordings/{recordingId}/ai

Starts mistakes (retakes, filler words and long pauses), scenes, director (Direct my video), chapters or clips in the background. Credits are held and the measured cost charged when it finishes; a failed run isn’t charged. A new run replaces that tool’s waiting suggestions. Follow it with GET /recordings/{recordingId}/suggestions. With an Idempotency-Key, a repeat returns the tool’s status and never holds or charges again. Needs a verified email address.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
Idempotency-KeyheaderstringUp to 255 printable characters without spaces, such as a UUID. See Idempotency.
toolrequiredbodystringThe tool to run.
summaryModel, format, requestbodystringAs for the estimate.
Example request
curl -X POST https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/ai \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4b8e2f1a-6c3d-4e9b-a7f5-2d1c0b9a8e7f" \
  -d '{"tool": "mistakes"}'
Response · 202 Accepted
{
  "recordingId": "7a1d3f5b-9c2e-4b6a-8d0f-1e3c5a7b9d20",
  "tool": "mistakes",
  "status": "queued",
  "error": null
}

Errors: insufficient_credits, email_unverified, validation_error, conflict, not_found, idempotency_key_reused, idempotency_in_progress, ai_unavailable and the common errors.

Each AI tool’s status and suggestions

GET/recordings/{recordingId}/suggestions

Mistakes, suggested scenes, Direct my video (camera views, scenes, text and logo items) and clips, each waiting, accepted or dismissed. Chapters are on GET /recordings/{recordingId}.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
Example request
curl https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/suggestions \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "recordingId": "7a1d3f5b-9c2e-4b6a-8d0f-1e3c5a7b9d20",
  "revision": 4,
  "mistakes": {
    "tool": "mistakes",
    "status": "ready",
    "error": null,
    "items": [
      {
        "id": "sug-14",
        "type": "retake",
        "startWord": 210,
        "endWord": 236,
        "start": 88.1,
        "end": 97.4,
        "reason": "Said again more clearly right after.",
        "confidence": 0.93,
        "status": "waiting"
      }
    ]
  },
  "scenes": {
    "tool": "scenes",
    "status": "none",
    "error": null,
    "items": []
  },
  "director": {
    "tool": "director",
    "status": "ready",
    "error": null,
    "format": "landscape",
    "views": [ … ],
    "scenes": [ … ],
    "items": [ … ]
  },
  "chapters": {
    "tool": "chapters",
    "status": "ready",
    "error": null,
    "count": 3
  },
  "clips": {
    "tool": "clips",
    "status": "none",
    "error": null,
    "items": []
  }
}

Errors: not_found, not_ready and the common errors.

Accept or dismiss suggestions

POST/recordings/{recordingId}/suggestions/review

For one tool (mistakes, scenes, director or clips): acceptAll accepts every waiting suggestion exactly as the editor’s Accept all does. Nothing already placed is replaced; what overlaps it or needs changes is returned in left, still waiting. Or list ids in accept and dismiss. For director only its own scenes are reviewed (in the app, Accept all there also takes waiting scenes from scenes, with the same rules). Accepting a clip keeps it when clips are found again; dismissing deletes it.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
revisionrequiredbodyintegerThe current revision.
toolrequiredbodystringWhose suggestions to review.
acceptAllbodybooleanAccept every waiting suggestion.
accept, dismissbodystring[]Suggestion ids.
Example request
curl -X POST https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/suggestions/review \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"revision": 4, "tool": "mistakes", "acceptAll": true}'
Response · 200 OK
{
  "tool": "mistakes",
  "accepted": [
    "sug-14"
  ],
  "dismissed": [],
  "left": [],
  "edits": {
    "recordingId": "7a1d3f5b-9c2e-4b6a-8d0f-1e3c5a7b9d20",
    "revision": 5,
    "durationSeconds": 1265.4,
    "editedSeconds": 1198.7,
    "cuts": {
      "removedSeconds": 66.7,
      "cutRegions": 9,
      "words": [
        {
          "id": "5f2c9a1e-3b7d-4e8a-9c6f-0d1e2f3a4b5c",
          "startWord": 120,
          "endWord": 131,
          "start": 48.21,
          "end": 52.9
        }
      ],
      "times": [
        {
          "id": "8d3e1f2a-4b5c-4d6e-8f7a-9b0c1d2e3f4a",
          "start": 61.2,
          "end": 63.5
        }
      ],
      "acceptedSuggestions": 7,
      "waitingSuggestions": 3
    },
    "wordFixes": [
      {
        "startWord": 8,
        "endWord": 9,
        "text": "Vidonto",
        "original": "video toe"
      }
    ],
    "views": [
      {
        "id": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
        "start": 0,
        "end": 12,
        "layout": "bubble",
        "framing": null,
        "corner": "bottom-right",
        "bubbleSize": "medium"
      }
    ],
    "zooms": [
      {
        "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
        "startWord": 40,
        "endWord": 52,
        "kind": "push",
        "start": 16.4,
        "end": 21.8
      }
    ],
    "scenes": [],
    "items": [
      {
        "id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f60",
        "start": 2,
        "end": 5,
        "kind": "text",
        "text": "Welcome",
        "style": "title",
        "position": "center",
        "size": "medium",
        "entrance": "fade",
        "opacity": 1
      }
    ],
    "settings": { … },
    "savedIntros": [
      {
        "id": "3e4f5a6b-7c8d-4e9f-8a0b-1c2d3e4f5a6b",
        "name": "Channel intro",
        "itemCount": 2
      }
    ]
  }
}

Errors: validation_error, unknown_suggestion, edit_conflict, not_found, not_ready and the common errors.

Recording exports

Finish a ready recording the way the Video Editor does: dub it, render it in the cloud, as a polished video or as a short clip, get caption files, write its description and article, and make viewer links. Prices, checks and resume rules are the app’s own. Paid starts send the revision of the edits they use, take an Idempotency-Key, hold the estimate and charge once when the work finishes; failed work isn’t charged, and a render or dub that was started is resumed after an interruption, never sent again. Exports render from the video kept in the cloud (recordings added through the API always are); dubbing needs the recording’s sound prepared, which recordings added through the API are and app recordings are once opened in the Video Editor.

The recording’s dubs

GET/recordings/{recordingId}/dubs

Each dub’s status, and the languages a recording can be dubbed into. stale means it was made before later edits: dub again before exporting it. soundPrepared is false until the sound is ready to send. The dubbed sound plays in the app; export it with dubLanguage.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
Example request
curl https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/dubs \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "recordingId": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
  "revision": 4,
  "spokenLanguage": "en",
  "soundPrepared": true,
  "editedSeconds": 1187.3,
  "dubs": [
    {
      "language": "es",
      "languageName": "Spanish",
      "status": "queued",
      "error": null,
      "ready": false,
      "stale": false,
      "readyAt": null,
      "audioSeconds": null,
      "estimatedCredits": 118.7
    },
    {
      "language": "de",
      "languageName": "German",
      "status": "queued",
      "error": null,
      "ready": false,
      "stale": false,
      "readyAt": null,
      "audioSeconds": null,
      "estimatedCredits": 118.7
    }
  ],
  "languages": [
    {
      "code": "es",
      "name": "Spanish"
    },
    {
      "code": "fr",
      "name": "French"
    },
    {
      "code": "de",
      "name": "German"
    }
  ]
}

Errors: not_found, not_ready and the common errors.

Credits dubbing would use

GET/recordings/{recordingId}/dubs/estimate

Priced on the saved edits. A language already dubbed for these edits costs 0.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
languagesrequiredquerystringComma-separated codes, up to five, such as es,de.
Example request
curl "https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/dubs/estimate?languages=es,de" \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "recordingId": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
  "editedSeconds": 1187.3,
  "languages": [
    {
      "language": "es",
      "languageName": "Spanish",
      "credits": 118.7
    },
    {
      "language": "de",
      "languageName": "German",
      "credits": 118.7
    }
  ],
  "soundPrepared": true,
  "credits": 237.4,
  "balance": 1520,
  "exempt": false,
  "enoughCredits": true
}

Errors: validation_error, not_found, not_ready, everything_cut and the common errors.

Dub into one to five languages

POST/recordings/{recordingId}/dubs

Dubs the saved edits in the background. A language already dubbed for them, or still being dubbed, is left as it is and costs nothing. Credits are held and the dubbed length charged when each dub finishes. Refused with sound_not_prepared until soundPrepared is true. Needs a verified email address.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
Idempotency-KeyheaderstringUp to 255 printable characters without spaces, such as a UUID. See Idempotency.
revisionrequiredbodyintegerThe current revision.
languagesrequiredbodystring[]One to five language codes.
Example request
curl -X POST https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/dubs \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9c1e3a5b-7d2f-4b6e-8a0c-2e4f6a8b0d1c" \
  -d '{"revision": 4, "languages": ["es", "de"]}'
Response · 202 Accepted
{
  "recordingId": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
  "revision": 4,
  "spokenLanguage": "en",
  "soundPrepared": true,
  "editedSeconds": 1187.3,
  "dubs": [
    {
      "language": "es",
      "languageName": "Spanish",
      "status": "queued",
      "error": null,
      "ready": false,
      "stale": false,
      "readyAt": null,
      "audioSeconds": null,
      "estimatedCredits": 118.7
    },
    {
      "language": "de",
      "languageName": "German",
      "status": "queued",
      "error": null,
      "ready": false,
      "stale": false,
      "readyAt": null,
      "audioSeconds": null,
      "estimatedCredits": 118.7
    }
  ],
  "languages": [
    {
      "code": "es",
      "name": "Spanish"
    },
    {
      "code": "fr",
      "name": "French"
    },
    {
      "code": "de",
      "name": "German"
    }
  ],
  "queued": [
    "es",
    "de"
  ]
}

Errors: insufficient_credits, email_unverified, validation_error, edit_conflict, not_found, not_ready, idempotency_key_reused, idempotency_in_progress, sound_not_prepared, everything_cut and the common errors.

Credits an export would use

GET/recordings/{recordingId}/exports/estimate

Priced on the saved edits with the same options as starting it. problem says why it would be refused now (for example no video kept in the cloud, or a background effect that still needs the Video Editor’s check); null when it can start.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
kindrequiredquerystringcloud, polished or clip.
resolutionquerystringFor cloud: original (default), 1080p or 720p.
formatsquerystringFor polished and clip: comma-separated, such as landscape,vertical.
clipIdquerystringFor clip: a clip’s id from the suggestions.
Example request
curl "https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/exports/estimate?kind=cloud&resolution=1080p" \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "recordingId": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
  "kind": "cloud",
  "revision": 4,
  "editedSeconds": 1187.3,
  "uploadReady": true,
  "problem": null,
  "credits": 96.4,
  "balance": 1520,
  "exempt": false,
  "enoughCredits": true
}

Errors: validation_error, not_found, not_ready, clip_not_found, everything_cut and the common errors.

Export in the cloud, as a polished video or a clip

POST/recordings/{recordingId}/exports

cloud renders the edited video at a resolution. polished and clip use the polished-video options saved for the recording, with its AI avatar and background; formats can replace the saved formats. A clip is one of the recording’s short clips, vertical unless formats says otherwise. dubLanguage uses a finished dub instead of the original sound; otherwise the cleaned-up sound is used when it is switched on. Charged once, when it finishes, for the formats that finished. Follow it with GET /recordings/{recordingId}/exports/{exportId} or the export.ready webhook. Needs a verified email address.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
Idempotency-KeyheaderstringUp to 255 printable characters without spaces, such as a UUID. See Idempotency.
kindrequiredbodystringcloud, polished or clip.
revisionrequiredbodyintegerThe current revision.
resolution, formats, clipIdbodystringAs for the estimate; formats is a list.
dubLanguagebodystringA finished dub’s language code.
Example request
curl -X POST https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/exports \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2f4a6c8e-0b1d-4e3f-9a5c-7e9b1d3f5a7c" \
  -d '{"kind": "cloud", "revision": 4, "resolution": "1080p"}'
Response · 202 Accepted
{
  "id": "8f1c3a5e-7b9d-4e2f-a6c8-0d2e4f6a8b1c",
  "recordingId": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
  "kind": "cloud",
  "status": "queued",
  "resolution": "1080p",
  "clipId": null,
  "clipTitle": null,
  "dubLanguage": null,
  "revision": 4,
  "editedSeconds": 1187.3,
  "estimatedCredits": 96.4,
  "progress": 0,
  "etaSeconds": 540,
  "error": null,
  "files": [
    {
      "format": null,
      "width": 1920,
      "height": 1080,
      "bytes": null,
      "ready": false,
      "downloadUrl": null
    }
  ],
  "createdAt": "2026-10-01T14:00:00.000Z",
  "finishedAt": null
}

Errors: insufficient_credits, email_unverified, validation_error, edit_conflict, not_found, not_ready, idempotency_key_reused, idempotency_in_progress, upload_needed, clip_not_found, export_running, no_dub, dub_stale, background_not_ready, lambda_unavailable and the common errors.

List the recording’s exports

GET/recordings/{recordingId}/exports

Cloud renders, polished videos and clips, newest first, including ones started in the app.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
Example request
curl https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/exports \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "recordingId": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
  "exports": [
    {
      "id": "5e2b8d14-6c3a-4f7e-9b1d-0a2c4e6f8b3d",
      "recordingId": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
      "kind": "polished",
      "status": "ready",
      "resolution": null,
      "clipId": null,
      "clipTitle": null,
      "dubLanguage": null,
      "revision": 4,
      "editedSeconds": 1187.3,
      "estimatedCredits": 412.5,
      "progress": 1,
      "etaSeconds": null,
      "error": null,
      "files": [
        {
          "format": "landscape",
          "width": 1920,
          "height": 1080,
          "bytes": 412880311,
          "ready": true,
          "downloadUrl": "/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/exports/5e2b8d14-6c3a-4f7e-9b1d-0a2c4e6f8b3d/video?format=landscape"
        },
        {
          "format": "vertical",
          "width": 1080,
          "height": 1920,
          "bytes": 398120774,
          "ready": true,
          "downloadUrl": "/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/exports/5e2b8d14-6c3a-4f7e-9b1d-0a2c4e6f8b3d/video?format=vertical"
        }
      ],
      "createdAt": "2026-10-01T13:00:00.000Z",
      "finishedAt": "2026-10-01T13:21:40.000Z"
    }
  ]
}

Errors: not_found and the common errors.

Get one export

GET/recordings/{recordingId}/exports/{exportId}

Its status, progress and files. A ready file has a downloadUrl.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
exportIdrequiredpathuuidThe export’s id.
Example request
curl https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/exports/5e2b8d14-6c3a-4f7e-9b1d-0a2c4e6f8b3d \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "id": "5e2b8d14-6c3a-4f7e-9b1d-0a2c4e6f8b3d",
  "recordingId": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
  "kind": "polished",
  "status": "ready",
  "resolution": null,
  "clipId": null,
  "clipTitle": null,
  "dubLanguage": null,
  "revision": 4,
  "editedSeconds": 1187.3,
  "estimatedCredits": 412.5,
  "progress": 1,
  "etaSeconds": null,
  "error": null,
  "files": [
    {
      "format": "landscape",
      "width": 1920,
      "height": 1080,
      "bytes": 412880311,
      "ready": true,
      "downloadUrl": "/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/exports/5e2b8d14-6c3a-4f7e-9b1d-0a2c4e6f8b3d/video?format=landscape"
    },
    {
      "format": "vertical",
      "width": 1080,
      "height": 1920,
      "bytes": 398120774,
      "ready": true,
      "downloadUrl": "/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/exports/5e2b8d14-6c3a-4f7e-9b1d-0a2c4e6f8b3d/video?format=vertical"
    }
  ],
  "createdAt": "2026-10-01T13:00:00.000Z",
  "finishedAt": "2026-10-01T13:21:40.000Z"
}

Errors: not_found and the common errors.

Download an export’s MP4

GET/recordings/{recordingId}/exports/{exportId}/video

Streams the finished file as an attachment, or inline with inline=true. Supports Range requests. For a polished video or clip with several formats, add format.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
exportIdrequiredpathuuidThe export’s id.
formatquerystringlandscape, vertical or square.
inlinequerystringtrue to play it in a browser.
Example request
curl -L -o demo-vertical.mp4 "https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/exports/5e2b8d14-6c3a-4f7e-9b1d-0a2c4e6f8b3d/video?format=vertical" \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
(no body)

Errors: not_found, export_not_ready, format_required and the common errors.

Download a caption file

GET/recordings/{recordingId}/captions

SRT or WebVTT timed on the edited video, the same file the Video Editor downloads. With language, the captions of that finished dub; a dub made before later edits is refused with dub_stale. Free.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
formatquerystringsrt (default) or vtt.
languagequerystringA dub’s language code.
Example request
curl -o demo-es.vtt "https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/captions?format=vtt&language=es" \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
WEBVTT

00:00:00.000 --> 00:00:03.200
Hola a todos, hoy les muestro…

Errors: validation_error, not_found, not_ready, dub_not_found, dub_stale and the common errors.

The description, article and chapters

GET/recordings/{recordingId}/writing

What has been written (null until written), and the chapters timed on the edited video. chapterList is the “0:00 Title” list the app adds to the YouTube description.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
Example request
curl https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/writing \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "recordingId": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
  "description": null,
  "article": {
    "kind": "howto",
    "markdown": "# Set up a project in Vidonto\n\n1. …",
    "usedChapters": true,
    "generatedAt": "2026-10-01T13:40:00.000Z",
    "editedAt": null
  },
  "chapters": [
    {
      "title": "Introduction",
      "seconds": 0
    },
    {
      "title": "Setting up a project",
      "seconds": 142.6
    },
    {
      "title": "Sharing the result",
      "seconds": 811.2
    }
  ],
  "chapterList": "0:00 Introduction\n2:22 Setting up a project\n13:31 Sharing the result"
}

Errors: not_found, not_ready and the common errors.

Credits writing would use

GET/recordings/{recordingId}/writing/estimate

Priced on the kept words.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
piecerequiredquerystringdescription or article.
summaryModelquerystringThe AI model. Defaults to the recording’s, then your saved one.
Example request
curl "https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/writing/estimate?piece=article" \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "recordingId": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
  "piece": "article",
  "credits": 3.2,
  "balance": 1520,
  "exempt": false,
  "enoughCredits": true
}

Errors: validation_error, not_found, not_ready and the common errors.

Write the description or an article

POST/recordings/{recordingId}/writing

description writes a YouTube title, description and tags with TikTok, X, Instagram and LinkedIn posts; article writes a blog post or how-to steps in Markdown. Both use the kept words and replace what was written before. The answer waits for the text, usually under a minute, and is charged once, only when the text is stored; writing_failed (502) charges nothing. Make chapters with the chapters AI tool. Needs a verified email address.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
Idempotency-KeyheaderstringUp to 255 printable characters without spaces, such as a UUID. See Idempotency.
piecerequiredbodystringdescription or article.
articleKindbodystringRequired for an article: blog or howto.
useChaptersbodybooleanArticle headings follow the chapters. Default true.
summaryModelbodystringAs for the estimate.
Example request
curl -X POST https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/writing \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6a8c0e2b-4d1f-4a3e-b5c7-9e1a3c5e7b9d" \
  -d '{"piece": "article", "articleKind": "howto"}'
Response · 200 OK
{ "recordingId": "…", "description": null, "article": { … }, "chapters": [ … ], "chapterList": "…" }

Errors: insufficient_credits, email_unverified, validation_error, not_found, not_ready, writing_failed, idempotency_key_reused, idempotency_in_progress and the common errors.

Credits a thumbnail would use

GET/recordings/{recordingId}/thumbnail/estimate

One picture. The brand, logo and instructions don’t change the price.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
Example request
curl https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/thumbnail/estimate \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "recordingId": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
  "credits": 6,
  "balance": 1520,
  "exempt": false,
  "enoughCredits": true
}

Errors: not_found and the common errors.

Make a thumbnail

POST/recordings/{recordingId}/thumbnail

An AI picture from the recording’s title, chapter titles and written description, with your headline written into it by the AI as part of the design (the only text in it; if a letter comes out wrong, make it again), as Share & post in the Video Editor makes. size is landscape (1280×720, the default) or vertical (1080×1920). Waits for the picture (up to about a minute); only the latest is kept. Charged one picture, once, only when it is stored; thumbnail_failed and logo_unreadable (502) charge nothing. Leaving outbrandId means no brand (not your default brand), so a request with only a headline makes the plain thumbnail. A brand that isn’t yours or was deleted is refused with brand_missing, and a headline that’s empty or too long with headline_too_long, before anything is held. promptId uses one of your saved thumbnail prompts: its instructions and brand, unless you send instructions or brandId too. A prompt that isn’t yours is refused with thumbnail_prompt_not_found, and one whose brand was deleted with brand_missing, before anything is held; the price doesn’t change. Needs a verified email address.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
Idempotency-KeyheaderstringUp to 255 printable characters without spaces, such as a UUID. See Idempotency.
headlinerequiredbodystring1 to 80 characters, written into the picture by the AI as its only text.
sizebodystringlandscape (default) or vertical.
brandIdbodystringOne of your brands (from GET /brands): its colours guide the picture and the headline lettering, and its heading font’s style guides the lettering.
logobodybooleanThe brand’s logo in the top-right corner. Needs brandId, or a promptId whose prompt has a brand.
instructionsbodystringWhat the picture should show and how the headline lettering looks, up to 500 characters. It can’t add other words.
promptIdbodystringOne of your saved thumbnail prompts (from GET /thumbnail-prompts): its instructions and brand are used unless you send instructions or brandId too.
Example request
curl -X POST https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/thumbnail \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3c5e7a9b-1d2f-4b6c-8e0a-2c4e6a8c0e1f" \
  -d '{"headline": "Edit a video in 5 minutes", "brandId": "5b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "logo": true, "instructions": "A laptop on a sunny desk"}'
Response · 200 OK
{
  "recordingId": "7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d",
  "thumbnail": {
    "headline": "Edit a video in 5 minutes",
    "size": "landscape",
    "width": 1280,
    "height": 720,
    "createdAt": "2026-11-07T10:00:00.000Z",
    "brandId": "5b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "logo": true,
    "instructions": "A laptop on a sunny desk",
    "downloadUrl": "/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/thumbnail"
  }
}

Errors: insufficient_credits, email_unverified, validation_error, not_found, brand_missing, thumbnail_prompt_not_found, headline_too_long, thumbnail_failed, logo_unreadable, idempotency_key_reused, idempotency_in_progress and the common errors.

Download the latest thumbnail

GET/recordings/{recordingId}/thumbnail

The JPEG itself (image/jpeg), sent as an attachment unless inline=true.thumbnail_not_found (404) until one is made.

ParameterInTypeDescription
recordingIdrequiredpathuuidThe recording’s id.
inlinequery"true" | "false"Send true to show the picture in a browser instead of downloading it.
Example request
curl -fL -o thumbnail.jpg https://www.vidonto.com/api/v1/recordings/7a3e9c15-2b8d-4f60-a1c4-5e6f7a8b9c0d/thumbnail \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
(the JPEG file, with Content-Type: image/jpeg)

Errors: not_found, thumbnail_not_found and the common errors.

Webhooks

Manage the endpoints that are told when your runs, recordings and exports finish. You can also do all of this on the API keys page in the app. See Webhooks for how deliveries work.

List your webhook endpoints

GET/webhooks

All endpoints, newest first, with the account limit and the event types you can subscribe to.

Example request
curl https://www.vidonto.com/api/v1/webhooks \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "endpoints": [
    {
      "id": "9b2d7c41-0f3e-4a6b-8c5d-2e1f0a9b8c7d",
      "url": "https://example.com/hooks/vidonto",
      "events": [
        "run.succeeded",
        "run.failed"
      ],
      "enabled": true,
      "disabledReason": null,
      "disabledAt": null,
      "secretPrefix": "whsec_AbC123",
      "failedEventsInARow": 0,
      "lastSuccessAt": null,
      "lastFailureAt": null,
      "createdAt": "2026-10-01T11:00:00.000Z",
      "updatedAt": "2026-10-01T11:00:00.000Z"
    }
  ],
  "maxEndpoints": 10,
  "eventTypes": [
    "run.succeeded",
    "run.failed",
    "run.cancelled",
    "run.review_waiting",
    "recording.ready",
    "recording.failed",
    "export.ready",
    "export.failed"
  ]
}

Add a webhook endpoint

POST/webhooks

Returns the signing secret once. Store it straight away; it can’t be read again (rotate it if it is lost). Up to 10 endpoints per account. Needs a verified email address.

ParameterInTypeDescription
urlrequiredbodystringA public HTTPS address, up to 2,048 characters.
eventsbodystring[]Any of run.succeeded, run.failed, run.cancelled, run.review_waiting, recording.ready, recording.failed, export.ready, export.failed. Default: all eight.
enabledbodybooleanDefault true.
Example request
curl -X POST https://www.vidonto.com/api/v1/webhooks \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/vidonto", "events": ["run.succeeded", "run.failed"]}'
Response · 201 Created
{
  "endpoint": {
    "id": "9b2d7c41-0f3e-4a6b-8c5d-2e1f0a9b8c7d",
    "url": "https://example.com/hooks/vidonto",
    "events": [
      "run.succeeded",
      "run.failed"
    ],
    "enabled": true,
    "disabledReason": null,
    "disabledAt": null,
    "secretPrefix": "whsec_AbC123",
    "failedEventsInARow": 0,
    "lastSuccessAt": null,
    "lastFailureAt": null,
    "createdAt": "2026-10-01T11:00:00.000Z",
    "updatedAt": "2026-10-01T11:00:00.000Z"
  },
  "secret": "whsec_AbC123…"
}

Errors: invalid_webhook_url, validation_error, webhook_limit, webhook_busy, email_unverified and the common errors.

Get one webhook endpoint

GET/webhooks/{webhookId}

failedEventsInARow counts events whose deliveries ran out of retries. disabledReason is failing when the endpoint was turned off automatically, manual when you turned it off.

ParameterInTypeDescription
webhookIdrequiredpathuuidThe endpoint’s id.
Example request
curl https://www.vidonto.com/api/v1/webhooks/9b2d7c41-0f3e-4a6b-8c5d-2e1f0a9b8c7d \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "id": "9b2d7c41-0f3e-4a6b-8c5d-2e1f0a9b8c7d",
  "url": "https://example.com/hooks/vidonto",
  "events": [
    "run.succeeded",
    "run.failed"
  ],
  "enabled": true,
  "disabledReason": null,
  "disabledAt": null,
  "secretPrefix": "whsec_AbC123",
  "failedEventsInARow": 0,
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "createdAt": "2026-10-01T11:00:00.000Z",
  "updatedAt": "2026-10-01T11:00:00.000Z"
}

Errors: not_found and the common errors.

Change an endpoint’s URL or events, or turn it on or off

PATCH/webhooks/{webhookId}

Send at least one field. Turning an endpoint back on, or changing its URL, resets its count of failed events.

ParameterInTypeDescription
webhookIdrequiredpathuuidThe endpoint’s id.
urlbodystringA new public HTTPS address.
eventsbodystring[]The event types to receive.
enabledbodybooleanTurn the endpoint on or off.
Example request
curl -X PATCH https://www.vidonto.com/api/v1/webhooks/9b2d7c41-0f3e-4a6b-8c5d-2e1f0a9b8c7d \
  -H "Authorization: Bearer $VIDONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
Response · 200 OK
{
  "id": "9b2d7c41-0f3e-4a6b-8c5d-2e1f0a9b8c7d",
  "url": "https://example.com/hooks/vidonto",
  "events": [
    "run.succeeded",
    "run.failed"
  ],
  "enabled": true,
  "disabledReason": null,
  "disabledAt": null,
  "secretPrefix": "whsec_AbC123",
  "failedEventsInARow": 0,
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "createdAt": "2026-10-01T11:00:00.000Z",
  "updatedAt": "2026-10-01T11:00:00.000Z"
}

Errors: not_found, invalid_webhook_url, validation_error and the common errors.

Delete an endpoint and its delivery history

DELETE/webhooks/{webhookId}

Deliveries still waiting to be retried are dropped.

ParameterInTypeDescription
webhookIdrequiredpathuuidThe endpoint’s id.
Example request
curl -X DELETE https://www.vidonto.com/api/v1/webhooks/9b2d7c41-0f3e-4a6b-8c5d-2e1f0a9b8c7d \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 204 No Content
(no body)

Errors: not_found and the common errors.

Replace the signing secret

POST/webhooks/{webhookId}/rotate-secret

The old secret stops working immediately. Deliveries still waiting to be retried are signed with the new one.

ParameterInTypeDescription
webhookIdrequiredpathuuidThe endpoint’s id.
Example request
curl -X POST https://www.vidonto.com/api/v1/webhooks/9b2d7c41-0f3e-4a6b-8c5d-2e1f0a9b8c7d/rotate-secret \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "endpoint": {
    "id": "9b2d7c41-0f3e-4a6b-8c5d-2e1f0a9b8c7d",
    "url": "https://example.com/hooks/vidonto",
    "events": [
      "run.succeeded",
      "run.failed"
    ],
    "enabled": true,
    "disabledReason": null,
    "disabledAt": null,
    "secretPrefix": "whsec_Zx9Qw2",
    "failedEventsInARow": 0,
    "lastSuccessAt": null,
    "lastFailureAt": null,
    "createdAt": "2026-10-01T11:00:00.000Z",
    "updatedAt": "2026-10-01T11:00:00.000Z"
  },
  "secret": "whsec_Zx9Qw2…"
}

Errors: not_found and the common errors.

Send a test event now

POST/webhooks/{webhookId}/test

Sends a webhook.test event with a sample finished run, ready recording and finished export, and waits for your endpoint’s answer. Works while the endpoint is turned off. Test events are never retried and don’t count toward turning the endpoint off.

ParameterInTypeDescription
webhookIdrequiredpathuuidThe endpoint’s id.
Example request
curl -X POST https://www.vidonto.com/api/v1/webhooks/9b2d7c41-0f3e-4a6b-8c5d-2e1f0a9b8c7d/test \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "id": "c4e8a1f2-7b3d-4e9a-a6c5-1d2e3f4a5b6c",
  "eventId": "evt_0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e",
  "eventType": "webhook.test",
  "runId": null,
  "recordingId": null,
  "status": "delivered",
  "attempts": 1,
  "lastStatusCode": 200,
  "lastError": null,
  "lastAttemptAt": "2026-10-01T12:06:41.000Z",
  "nextAttemptAt": null,
  "deliveredAt": "2026-10-01T12:06:41.000Z",
  "createdAt": "2026-10-01T12:06:40.000Z"
}

Errors: not_found and the common errors.

Recent deliveries to an endpoint

GET/webhooks/{webhookId}/deliveries

Newest first. status is pending (will be tried again at nextAttemptAt), delivered or failed (ran out of retries). Finished deliveries are kept for 30 days.

ParameterInTypeDescription
webhookIdrequiredpathuuidThe endpoint’s id.
limitqueryinteger1 to 100. Default 20.
Example request
curl "https://www.vidonto.com/api/v1/webhooks/9b2d7c41-0f3e-4a6b-8c5d-2e1f0a9b8c7d/deliveries?limit=20" \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "deliveries": [
    {
      "id": "c4e8a1f2-7b3d-4e9a-a6c5-1d2e3f4a5b6c",
      "eventId": "evt_6c1f0e9a2b7d4c3e8f5a1b2c3d4e5f60",
      "eventType": "run.succeeded",
      "runId": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
      "recordingId": null,
      "status": "delivered",
      "attempts": 1,
      "lastStatusCode": 200,
      "lastError": null,
      "lastAttemptAt": "2026-10-01T12:06:41.000Z",
      "nextAttemptAt": null,
      "deliveredAt": "2026-10-01T12:06:41.000Z",
      "createdAt": "2026-10-01T12:06:40.000Z"
    }
  ]
}

Errors: not_found, validation_error and the common errors.

Send one delivery again now

POST/webhooks/{webhookId}/deliveries/{deliveryId}/resend

Same event ID and body, with a fresh timestamp and signature. Waits for your endpoint’s answer.

ParameterInTypeDescription
webhookIdrequiredpathuuidThe endpoint’s id.
deliveryIdrequiredpathuuidThe delivery’s id.
Example request
curl -X POST https://www.vidonto.com/api/v1/webhooks/9b2d7c41-0f3e-4a6b-8c5d-2e1f0a9b8c7d/deliveries/c4e8a1f2-7b3d-4e9a-a6c5-1d2e3f4a5b6c/resend \
  -H "Authorization: Bearer $VIDONTO_API_KEY"
Response · 200 OK
{
  "id": "c4e8a1f2-7b3d-4e9a-a6c5-1d2e3f4a5b6c",
  "eventId": "evt_6c1f0e9a2b7d4c3e8f5a1b2c3d4e5f60",
  "eventType": "run.succeeded",
  "runId": "3f0c6b6e-6a1e-4b8e-9d55-7f3f0a7a2c11",
  "recordingId": null,
  "status": "delivered",
  "attempts": 2,
  "lastStatusCode": 200,
  "lastError": null,
  "lastAttemptAt": "2026-10-01T12:06:41.000Z",
  "nextAttemptAt": null,
  "deliveredAt": "2026-10-01T12:06:41.000Z",
  "createdAt": "2026-10-01T12:06:40.000Z"
}

Errors: not_found, delivery_busy and the common errors.

API description

The OpenAPI 3.1 document for this API. It needs no key.

This API description as JSON

GET/openapi.json

Import it into an API client or a code generator.

Example request
curl https://www.vidonto.com/api/v1/openapi.json
Response · 200 OK
{ "openapi": "3.1.0", "info": { "title": "Vidonto API", … }, … }

This API description as YAML

GET/openapi.yaml

The same document as YAML.

Example request
curl https://www.vidonto.com/api/v1/openapi.yaml
Response · 200 OK
openapi: 3.1.0
info:
  title: Vidonto API
  …