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.
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.
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.
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}
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:
Situation
Status
error.code
No Authorization header, or not a Bearer token
401
missing_api_key
The key is mistyped, was revoked, or belongs to a disabled account
401
invalid_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.
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.
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).
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".
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).
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.
// 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")
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.
Every option is optional, on both POST /runs and POST /runs/batch. For each one you leave out, the API uses the first of:
the value in your request,
your saved setting from the Settings page in the app, for the options marked Saved settings below,
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.
Option
Values
When omitted
targetDuration
Seconds, 10 or more.
90. A target, not a limit: the narration always plays in full.
lengthRange
Topic 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 (chosenByfallback 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).
720p, 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
textMode
narration (a spoken script) or key_points (the main points on screen)
narration
captionLength
short (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.
summaryModel
A script model id from GET /options.
Saved settings then the recommended model.
voiceId
A voice id from GET /options.
Saved settings then the first available voice.
transcriptLanguage
Preferred YouTube caption language, such as en or pt-BR.
Saved settings then en.
videoLanguage
The 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.
openingStyle
See the table below.
Saved settings then coming_up.
endingStyle
See the table below.
Saved settings then none.
customSignOff
Your closing line, up to 200 characters and 20 words.
Saved settings
aiImages
true or false. Generates images for the frames and costs more credits.
false
creditSource
true or false. Credits the original source in the video.
false
instructions
Free text, up to 2,000 characters (instructionsMaxCharacters in GET /options). Steers how the script and storyboard are written. See Instructions.
None.
presenter
An 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.
characterIds
Two 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.
look
auto (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.
showLogo
true or false. With lookbrand, shows the brand’s logo.
false
brandId
With lookbrand, which of your brands to use: an id from brands in GET /options.
Your default brand.
animatedScenes
off, 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
review
true or false. Waits for your approval after the script and after the storyboard. See Review before render.
A short opening and ending can frame the summary. Pick them with openingStyle and endingStyle:
openingStyle
What it does
none
Starts straight into the first point.
coming_up
A quick preview that lists the points the video covers.
cliffhanger
Teases the most surprising point without giving it away.
question
Opens with the central question the video answers.
bottom_line
States the biggest takeaway up front, then explains it.
endingStyle
What it does
none
Ends on the last point.
recap
A quick recap of the main points in order.
takeaway
A one-sentence bottom line to remember.
reflection
Closes with a question for the viewer to think about.
original
Sends the viewer to the full video or article.
custom
Ends with your own line from customSignOff, spoken exactly as written.
With endingStylecustom, 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."
}
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."
}
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.
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).
Two more layouts and three placement fields shape where the presenter stands:
layoutdirector 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.
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.
{
"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"
]
}
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.
Send lookbrand 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 showLogotrue 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.
showLogotrue or a brandId without lookbrand 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.
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.
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.
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 retryablefalse; open the project in the app to approve the storyboard again. With review, frames with soundBitetrue 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.
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.
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 (reviewStepstoryboard). While it waits, its status stays running.
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.
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.
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.
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.
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.
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.
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
}
}
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.
kind
Meaning
reserve
Credits held when a run started (negative).
charge
A finished step. charged is the step’s full price and step names it; credits is only the part the hold did not cover.
release
The unused part of a hold, returned when the run finished (positive).
grant
Credits added to your account, such as starter credits.
purchase
Credits you bought.
refund
Credits removed because a purchase was refunded.
adjustment
A 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.
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.
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.
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"
}
]
}
}
Status
error.code
Meaning
400
invalid_json
The request body is not valid JSON.
401
missing_api_key
No Authorization header, or it is not a Bearer token.
401
invalid_api_key
The key is wrong, was revoked, or its account is disabled.
402
insufficient_credits
Your balance doesn’t cover the run. Includes balance and required.
403
email_unverified
Confirm your email address in the app before starting videos or adding webhooks.
404
not_found
No such run, recording, webhook, delivery or endpoint, or it belongs to another account.
404
thumbnail_prompt_not_found
The promptId isn’t one of your saved thumbnail prompts (see GET /thumbnail-prompts). Nothing was charged.
409
video_not_ready
The run has no finished video yet. Includes the run’s status and stage.
409
retry_not_safe
The run is not a failed run with retryable set, so it can’t be retried.
409
conflict
The 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.
409
transcript_not_ready
The recording is still being added or transcribed. Includes its status.
409
recording_failed
The recording failed, so it has no transcript. The message says why.
409
audio_in_app
The 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.
409
not_uploading
The recording isn’t waiting for file parts: it was added from a link, or every part has already arrived.
409
upload_gone
The upload was given up (7 days after it started) or failed. Add the recording again.
409
brand_missing
The 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.
409
idempotency_in_progress
A request with the same Idempotency-Key is still being handled. Try again shortly.
409
webhook_limit
The account already has 10 webhook endpoints.
409
webhook_busy
Another endpoint is being added at the same moment. Try again.
409
delivery_busy
That delivery is being sent right now. Try again.
413
payload_too_large
The request body is too large.
422
validation_error
A field is missing, has the wrong type or value, or is unknown. issues lists each problem with its path.
422
invalid_source
More than one of url, text and script was sent.
422
invalid_source_url
The link is missing or is not a YouTube video or web page link.
422
empty_text
The pasted text is empty.
422
empty_script
Your own script is empty.
422
script_too_long
Your own script is longer than ownScript.maxCharacters in GET /options.
422
own_script_option
An option that only steers the AI script was sent with script. The message names the fields.
422
unknown_voice
The voiceId is not in GET /options.
422
invalid_sign_off
The custom ending’s sign-off is missing or too long.
422
source_credit_incomplete
Crediting pasted text needs a title.
422
source_too_long
The pasted text is longer than sourceMaxCharacters in GET /options.
422
presenter_unknown
The presenter’s avatarId is not in GET /options.
422
presenter_too_long
A presenter was asked for with a targetDuration over 10 minutes.
422
presenter_renderer
Admin keys only: a presenter needs a Remotion renderProvider.
422
show_logo_needs_brand_look
showLogotrue was sent without lookbrand.
422
brand_id_needs_brand_look
brandId was sent without lookbrand.
422
brand_renderer
Admin keys only: the brand look needs a Remotion renderProvider.
422
invalid_idempotency_key
The Idempotency-Key is empty, too long or contains spaces.
422
idempotency_key_reused
The Idempotency-Key was already used with a different request.
422
file_too_large
The recording’s file is bigger than 16 GiB.
422
invalid_url
The recording link is not a public HTTPS address.
422
link_refused
The recording link answered with an error, needs a login or has expired.
422
link_unreachable
The recording link couldn’t be reached, or redirected too many times.
422
not_a_video
The recording link opens a web page, not a video file. Use a direct download link.
422
link_size_unknown
The recording link doesn’t say how big the file is.
422
rights_not_confirmed
A YouTube, TikTok, X or Facebook video page link needs rightsConfirmed: true (you own the video or have permission to use it).
422
site_not_supported
Videos can’t be read from this site (Instagram, Vimeo). Download the video and upload the file instead.
422
private_video
The 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.
422
site_failed
The 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.
422
invalid_webhook_url
The webhook URL is not a public HTTPS address.
429
rate_limited
Too many requests. Wait retryAfterSeconds (also in the Retry-After header).
500
internal_error
Something went wrong on our side. Try again.
503
…_unavailable
A 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.
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.
Group
Endpoints
Per key
Per account
Reading
Getting and listing runs, cancelling, downloading videos, /options, /estimate, /credits, listing webhooks and deliveries
120 / minute
240 / minute
Starting videos
POST /runs, POST /runs/batch (one request however many links), POST /runs/{runId}/retry
10 / minute
20 / minute
Webhook changes
Adding, changing, deleting, rotating, test events and resends
30 / minute
60 / 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.
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.
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.
A run finished and its video is ready to download.
run.failed
A run failed. data.run.error says why and data.run.retryable whether it can be retried.
run.cancelled
A run was cancelled, in the API or the web app.
run.review_waiting
A 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.ready
A recording was transcribed and is ready to edit, read or download its transcript. Includes recordings made in the app.
recording.failed
Adding or transcribing a recording failed. data.recording.error says why; a recording added through the API or an assistant also has errorCode.
export.ready
A cloud render, polished video or clip finished and its files are ready to download. Includes exports started in the app.
export.failed
An export failed. data.export.error says why; any formats that did finish are listed as ready (only those are charged).
webhook.test
You 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.
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.
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:
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.
Compute an HMAC-SHA256 of <timestamp>.<raw request body>, using the whole secret, including whsec_, as the key. Hex-encode the result.
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
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}.
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.
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:
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
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.
Lists formats, voices, languages, opening and ending styles, AI presenters, looks, your brands and your saved defaults.
estimate_credits
Estimates the credits a video, or several, would use.
start_video
Starts 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_batch
Starts one video per link, up to 100, with the same options. Spends credits.
get_run
Checks a video’s progress and, when it is done, gives a link to it in the Vidonto app.
list_runs
Lists your videos, newest first, with the names you gave them, optionally only those with certain tags or matching a search.
rename_run
Names a video, or clears its name. Only the name it is shown under changes.
cancel_run
Cancels a video that is still being made.
retry_run
Retries a failed video from the step that failed. Spends credits.
get_credits
Gets your credit balance.
get_run_review
Reads the script or storyboard a video started with review is waiting on.
edit_run_script
Changes the waiting script or title before the storyboard is written.
edit_run_storyboard
Changes frames of the waiting storyboard: their words, on-screen text, image prompt and where the presenter stands.
approve_run_review
Approves the waiting script or storyboard so the video continues. Costs nothing extra.
list_brands
Lists your brands with their colours, fonts and logos.
create_brand
Adds a brand, empty or copied from another one.
update_brand
Changes a brand’s name, colours, fonts or whether it is your default.
delete_brand
Deletes a brand after you confirm. Videos already made keep it.
set_brand_logo
Saves a brand’s logo, or its version for dark or light backgrounds, from a public picture link.
remove_brand_logo
Removes a brand’s logo after you confirm.
list_saved_intros
Lists your saved intros.
save_intro
Saves text and logo items as an intro to reuse at the start of recordings.
rename_intro
Renames a saved intro.
delete_intro
Deletes a saved intro after you confirm.
list_saved_styles
Lists your saved polished-video styles.
save_style
Saves a polished-video look as a style, optionally as your default.
update_style
Changes a saved style’s name, look or whether it is your default.
delete_style
Deletes a saved style after you confirm.
list_recordings
Lists 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_recording
Checks a recording: its progress, length, chapters, tags and whether the video is kept in the cloud.
get_recording_transcript
Reads a recording’s transcript, with your fixes to misheard words, optionally with each word’s timing.
set_recording_tags
Replaces a recording’s tags.
rename_recording
Renames a recording. Its edits stay as they are.
delete_recording
Deletes a recording after you confirm. A recording kept in the cloud stops being stored and charged.
estimate_recording_credits
Estimates the credits adding a video from a link would use, and what keeping it in the cloud costs every 30 days.
add_recording_from_link
Adds 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_edits
Reads a recording’s edits: cuts, word fixes, camera views, zooms, scenes, text and logo items, its look settings and your saved intros.
get_recording_suggestions
Reads what the AI tools suggested for a recording, and which suggestions are waiting, accepted or dismissed.
estimate_recording_ai
Estimates the credits an AI tool would use on a recording.
run_recording_ai
Runs 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_suggestions
Accepts all, some or none of a tool’s suggestions, with the same rules as Accept all in the Video Editor.
edit_recording
Edits 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_settings
Changes a recording’s AI model, background, AI avatar, camera shape, cleaned-up sound or polished-video options.
get_recording_dubs
Reads a recording’s dubs and the languages it can be dubbed into.
estimate_recording_dubs
Estimates the credits dubbing a recording into some languages would use.
start_recording_dubs
Dubs a recording into up to five languages at a time. Spends credits.
estimate_recording_export
Estimates the credits a cloud render, polished video or clip would use, and says if anything stops it.
start_recording_export
Renders a recording in the cloud, as a polished video or as one short clip, with its sound or a dub. Spends credits.
list_recording_exports
Reads a recording’s exports and how far along each one is.
get_recording_captions
Gets an SRT or WebVTT caption file for the edited video or for one of its dubs.
get_recording_writing
Reads a recording’s description and posting text, article and chapters.
estimate_recording_writing
Estimates the credits writing a description or an article would use.
write_recording
Writes a recording’s YouTube description and social posts, or a blog post or how-to article. Spends credits.
list_thumbnail_prompts
Lists your saved thumbnail prompts, so a thumbnail can use one.
save_thumbnail_prompt
Saves picture instructions as a named thumbnail prompt, optionally with one of your brands.
update_thumbnail_prompt
Renames a saved thumbnail prompt or changes its picture instructions. Its brand stays the same.
delete_thumbnail_prompt
Deletes a saved thumbnail prompt after you confirm.
estimate_recording_thumbnail
Estimates the credits a recording thumbnail would use.
make_recording_thumbnail
Makes 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_links
Lists a recording’s viewer links and how often each was watched.
create_share_link
Makes a viewer link to a finished export or to the recording kept in the cloud. Each viewer uses credits.
end_share_link
Ends a viewer link for good.
estimate_run_thumbnail
Estimates the credits a thumbnail for a finished summary video would use.
make_run_thumbnail
Makes 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.
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.
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.
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 reviewtrue the run waits for your approval after its script and its storyboard (see Review before render). Needs a verified email address.
Parameter
In
Type
Description
Idempotency-Key
header
string
Up to 255 printable characters without spaces, such as a UUID. See Idempotency.
url
body
string
A YouTube video or web page link, up to 2,000 characters.
text
body
string
Pasted text to summarize, instead of url. Up to sourceMaxCharacters from GET /options (currently 200,000 by default).
script
body
string
Your own script, spoken word for word, instead of url or text. Up to 20,000 characters.
documentUrl
body
string
A public link to a PDF, Word (.docx) or PowerPoint (.pptx) file up to 50 MB, read as pasted text and never stored. See Documents.
sources
body
object[]
2 to 5 sources for one video, each {"url": …}, {"text": …, "title": …, "attribution": …} or {"documentUrl": …, "title": …, "attribution": …}, instead of the fields above. See Several sources.
writingMethod
body
new_piece | summary
With sources only. Default new_piece.
lengthRange
body
object
With 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.
recordingId
body
string
One of your recordings, kept in the cloud and transcribed, for a highlights video of it, instead of the fields above. See Highlights videos.
highlightsStyle
body
narrated | cards
With recordingId only. Default narrated.
title
body
string
A 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.
tags
body
string[]
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, …
body
options
Any of the video options. All are optional; omitted ones use your saved settings. See Options.
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.
Parameter
In
Type
Description
Idempotency-Key
header
string
Up to 255 printable characters without spaces, such as a UUID. See Idempotency.
urlsrequired
body
string[]
1 to 100 YouTube or web page links.
lengthRange
body
object
With topics only: the same range for every run; each run’s AI picks its own length inside it.
tags
body
string[]
Labels given to every run, with the same rules as a single run.
targetDuration, videoFormat, …
body
options
Any of the video options. All are optional; omitted ones use your saved settings. See Options.
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.
Parameter
In
Type
Description
runIdrequired
path
uuid
The run’s id.
namerequired
body
string | null
Up 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"}'
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.
Parameter
In
Type
Description
runIdrequired
path
uuid
The 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"
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.
Parameter
In
Type
Description
runIdrequired
path
uuid
The 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"
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.
Parameter
In
Type
Description
runIdrequired
path
uuid
The run’s id.
inline
query
"true" | "false"
Send true to play the video in a browser instead of downloading it.
Range
header
string
A single byte range, to resume or stream the download.
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.
Parameter
In
Type
Description
runIdrequired
path
uuid
The run’s id.
Idempotency-Key
header
string
Up to 255 printable characters without spaces, such as a UUID. See Idempotency.
headlinerequired
body
string
1 to 80 characters, written into the picture by the AI as its only text.
brandId
body
string
One of your brands (from GET /brands): its colours guide the picture and the headline lettering, and its heading font’s style guides the lettering.
logo
body
boolean
The brand’s logo in the top-right corner. Needs brandId, or a promptId whose prompt has a brand.
instructions
body
string
What the picture should show and how the headline lettering looks, up to 500 characters. It can’t add other words.
promptId
body
string
One of your saved thumbnail prompts (from GET /thumbnail-prompts): its instructions and brand are used unless you send instructions or brandId too.
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.
{
"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
}
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).
Parameter
In
Type
Description
runIdrequired
path
uuid
The run’s id.
title
body
string
The video’s title, up to 200 characters.
script
body
string
The 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
}
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.
Parameter
In
Type
Description
runIdrequired
path
uuid
The run’s id.
framesrequired
body
object[]
1 to 200 changes, each with the frame’s id and only the fields to change.
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.
Parameter
In
Type
Description
runIdrequired
path
uuid
The run’s id.
steprequired
body
"script" | "storyboard"
The step you are approving: the run’s reviewStep.
lengthSeconds
body
integer
With stepsources 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.
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.
Parameter
In
Type
Description
fileNamerequired
query
string
The file’s name with its extension, such as report.pdf.
{
"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
}
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.
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.
Parameter
In
Type
Description
sourceKind
query
youtube | webpage | text | script | mixed | multi
Default 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.
sourceCount
query
integer
With multi: how many sources, 2 to 5. Default 2.
youtubeSources
query
integer
With multi: how many of them are YouTube videos. Default 0.
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.
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.
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.
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}.
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.
Parameter
In
Type
Description
namerequired
body
string
Up to 60 characters.
copyFrom
body
uuid
A brand whose colours, fonts and logos the new one starts with.
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.
Send the picture’s bytes (PNG, JPEG or WebP, up to 5 MB) as the request body. The type is read from the bytes. The second logo (alt) needs a main logo; say which backgrounds it’s for with for. Replacing a logo doesn’t change videos already made.
Parameter
In
Type
Description
brandIdrequired
path
uuid
The brand’s id.
slotrequired
path
"main" | "alt"
Which logo.
for
query
"dark" | "light"
With alt: the backgrounds the second logo is for. Default dark.
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.
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.
Parameter
In
Type
Description
namerequired
body
string
Up to 60 characters.
itemsrequired
body
object[]
Each with start, end, kind (text or logo), its text and placement.
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.
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.
Parameter
In
Type
Description
namerequired
body
string
Up to 60 characters.
instructionsrequired
body
string
What the picture should show. Up to 500 characters.
brandId
body
uuid | null
One 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"
}
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.
Parameter
In
Type
Description
promptIdrequired
path
uuid
The prompt’s id.
name
body
string
Up to 60 characters.
instructions
body
string
Up to 500 characters. They replace the saved ones.
A name and the look to keep: formats, captions, title and end cards, lower third, frame, theme and logo placement. A style with themebrand can name a brandId. isDefault makes it the style new recordings start with. Up to 50 styles.
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.
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.
Parameter
In
Type
Description
totalBytes
query
integer
The file’s size, instead of url.
url
query
string
The link you would add: a YouTube, TikTok, X or Facebook video page, or a direct download link (its size is read from it).
{
"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
}
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.
Parameter
In
Type
Description
Idempotency-Key
header
string
Up to 255 printable characters without spaces, such as a UUID. See Idempotency.
sourcerequired
body
string
upload or link.
url
body
string
For link: a YouTube, TikTok, X or Facebook video page, or a direct HTTPS download link.
rightsConfirmed
body
boolean
For link: true confirms you own the video or have permission to use it. Required for a video page link.
fileName
body
string
Required for upload. For a link, defaults to the page’s title or the link’s last part.
totalBytes
body
integer
For upload: the file’s size in bytes.
contentType
body
string
For upload: a video type such as video/mp4.
title
body
string
Up to 200 characters. Defaults to the video page’s title, or the file name.
Each part is partBytes (16 MiB) except the last. PUT each part’s exact bytes to its uploadUrl, which lasts an hour; ask again for a fresh link. Parts can go in any order and in parallel. Treat the links as secrets.
Parameter
In
Type
Description
recordingIdrequired
path
uuid
The recording’s id.
partsrequired
body
integer[]
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/links \
-H "Authorization: Bearer $VIDONTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"parts": [0, 1]}'
# then, for each part:
curl -X PUT --data-binary @part-0.bin "<uploadUrl>"
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.
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.
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.
Parameter
In
Type
Description
recordingIdrequired
path
uuid
The recording’s id.
words
query
string
false to leave out the word list (words is then null). Default true.
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.
Parameter
In
Type
Description
recordingIdrequired
path
uuid
The recording’s id.
titlerequired
body
string
Up to 300 characters, not empty; spaces at either end are removed.
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.
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.
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.
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.
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.
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.
Parameter
In
Type
Description
recordingIdrequired
path
uuid
The recording’s id.
Idempotency-Key
header
string
Up to 255 printable characters without spaces, such as a UUID. See Idempotency.
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}.
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.
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.
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.
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.
Parameter
In
Type
Description
recordingIdrequired
path
uuid
The recording’s id.
Idempotency-Key
header
string
Up to 255 printable characters without spaces, such as a UUID. See Idempotency.
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.
Parameter
In
Type
Description
recordingIdrequired
path
uuid
The recording’s id.
kindrequired
query
string
cloud, polished or clip.
resolution
query
string
For cloud: original (default), 1080p or 720p.
formats
query
string
For polished and clip: comma-separated, such as landscape,vertical.
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.
Parameter
In
Type
Description
recordingIdrequired
path
uuid
The recording’s id.
Idempotency-Key
header
string
Up to 255 printable characters without spaces, such as a UUID. See Idempotency.
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.
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.
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.
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.
Parameter
In
Type
Description
recordingIdrequired
path
uuid
The recording’s id.
Idempotency-Key
header
string
Up to 255 printable characters without spaces, such as a UUID. See Idempotency.
piecerequired
body
string
description or article.
articleKind
body
string
Required for an article: blog or howto.
useChapters
body
boolean
Article headings follow the chapters. Default true.
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.
Parameter
In
Type
Description
recordingIdrequired
path
uuid
The recording’s id.
Idempotency-Key
header
string
Up to 255 printable characters without spaces, such as a UUID. See Idempotency.
headlinerequired
body
string
1 to 80 characters, written into the picture by the AI as its only text.
size
body
string
landscape (default) or vertical.
brandId
body
string
One of your brands (from GET /brands): its colours guide the picture and the headline lettering, and its heading font’s style guides the lettering.
logo
body
boolean
The brand’s logo in the top-right corner. Needs brandId, or a promptId whose prompt has a brand.
instructions
body
string
What the picture should show and how the headline lettering looks, up to 500 characters. It can’t add other words.
promptId
body
string
One 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"
}
}
A watch page anyone with the link can open, for a finished export (with format when it has several) or, without exportId, the recording kept in the cloud. Making it is free; each viewer uses viewCredits, once per viewing window, as in the app. A link that is already on for that video is returned with 200 instead of a new one.
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.
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.
Parameter
In
Type
Description
urlrequired
body
string
A public HTTPS address, up to 2,048 characters.
events
body
string[]
Any of run.succeeded, run.failed, run.cancelled, run.review_waiting, recording.ready, recording.failed, export.ready, export.failed. Default: all eight.
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.
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.
Parameter
In
Type
Description
webhookIdrequired
path
uuid
The 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"
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.