The vidBoard API

Quick start

1. Sign in to vidBoard, open your Profile and click Create API key in the vidBoard API card. Copy the key: it is shown once.
2. Start a video. It answers at once with an id.
3. Ask for that video every 15–30 seconds until status is done, then download videoUrl.

curl -X POST https://www.vidboard.ai/tool/api/v1/avatar_video/ \
  -H "X-API-Key: vb_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"text": "Solar panels turn sunlight into electricity. Each panel is made of cells...", "slides": 4, "shape": "portrait"}'

curl https://www.vidboard.ai/tool/api/v1/avatar_video/5be8f425-c48f-45c1-9e2d-c2fa885125a3/ \
  -H "X-API-Key: vb_live_your_key"

{"id": "5be8f425-c48f-45c1-9e2d-c2fa885125a3", "status": "done", "stage": "Ready",
 "createdAt": "2026-11-02T17:39:34.643178Z",
 "videoUrl": "https://video.vidboard.ai/API_video_5be8f425-2026-11-02_17-44-16.mp4"}

import time, requests

BASE = "https://www.vidboard.ai/tool/api/v1"
HEADERS = {"X-API-Key": "vb_live_your_key"}

job = requests.post(f"{BASE}/avatar_video/", headers=HEADERS, json={
    "text": "Solar panels turn sunlight into electricity. Each panel is made of cells...",
    "slides": 4,
}).json()

while job["status"] not in ("done", "failed"):
    time.sleep(20)
    job = requests.get(f"{BASE}/avatar_video/{job['id']}/", headers=HEADERS).json()

print(job.get("videoUrl") or job.get("error"))

const BASE = "https://www.vidboard.ai/tool/api/v1";
const headers = { "X-API-Key": "vb_live_your_key", "Content-Type": "application/json" };

let job = await (await fetch(`${BASE}/avatar_video/`, {
  method: "POST", headers,
  body: JSON.stringify({ text: "Solar panels turn sunlight into electricity. Each panel is made of cells...", slides: 4 }),
})).json();

while (!["done", "failed"].includes(job.status)) {
  await new Promise((r) => setTimeout(r, 20000));
  job = await (await fetch(`${BASE}/avatar_video/${job.id}/`, { headers })).json();
}
console.log(job.videoUrl || job.error);

Keys and requests

• Every address starts with https://www.vidboard.ai/tool/api/v1/ and ends with a /. Without the last slash you get 404 Unknown endpoint.
• Send your key in the X-API-Key header on every request. Not Authorization.
• Send JSON bodies with Content-Type: application/json and snake_case field names (job_id, style_id). Files go as multipart/form-data.
• Answers come back as JSON with camelCase names (jobId, videoUrl, downloadUrl).
• Everything you make through the API belongs to your vidBoard account. Avatar videos also appear in your projects, where you can open and edit them.

Limits and errors

Each plan includes a number of API videos a month for each tool, separate from your in-app credits. Your Profile shows how many you have used this month. Only the call that makes the video counts (marked uses one API video below). Uploads, progress checks and downloads are free. A video that fails on our side is not counted.

Each key can make 30 requests a minute. Progress checks count too, so check every 5 seconds or slower (15–30 seconds is plenty for avatar videos).

Text to video

Send a script or an article. The AI writes the slides and the narration, finds pictures, and the avatar presents it, the way the app's Document tool does.

POSTavatar_video/ USES ONE API VIDEO

curl -X POST https://www.vidboard.ai/tool/api/v1/avatar_video/ \
  -H "X-API-Key: vb_live_your_key" -H "Content-Type: application/json" \
  -d '{"text": "Solar panels turn sunlight into electricity...", "slides": 4}'

Add any of the video settings, and follow it with GET avatar_video/{id}/.

Link to video

Send a web page: a blog post, a news story, a product page. It is read and turned into a presenter video.

POSTavatar_video/ USES ONE API VIDEO

curl -X POST https://www.vidboard.ai/tool/api/v1/avatar_video/ \
  -H "X-API-Key: vb_live_your_key" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/blog/solar-power", "slides": 5, "shape": "portrait"}'

A page behind a login or a paywall cannot be read.

PDF & Word to video

Send a document. Its text is read and made into a presenter video, the same way as Text to video.

POSTavatar_video/ USES ONE API VIDEO

A multipart/form-data request: the file as file, any settings next to it. Let your HTTP library set the Content-Type header.

curl -X POST https://www.vidboard.ai/tool/api/v1/avatar_video/ \
  -H "X-API-Key: vb_live_your_key" \
  -F "file=@report.pdf" -F "slides=5" -F "shape=portrait"

A scanned page is a picture, so it has no text to read: the request is refused with a 400 and nothing is counted. Word tables are read too.

PowerPoint to video

Send a deck. Each slide becomes a scene exactly as you designed it, narrated from its speaker notes, the way the app's PowerPoint tool does.

POSTavatar_video/ USES ONE API VIDEO

A multipart/form-data request, as for PDF & Word.

curl -X POST https://www.vidboard.ai/tool/api/v1/avatar_video/ \
  -H "X-API-Key: vb_live_your_key" \
  -F "file=@pitch.pptx" -F "avatar=avatar_74"

• Only the speaker notes are spoken, never the text on the slide. A slide without notes is shown for 5 seconds in silence.
• The slides are used as they are, so template and language do not apply (sending them is a 400).

Video settings and progress

All four tools above are one endpoint, avatar_video/, so they share these settings and the way you follow a video. Send exactly one of text, url or file. Tool name in your plan: avatar_video.

The start answers 202 with {"id", "status": "queued"}.

GETavatar_video/{id}/

status moves through these steps:

{"id": "5be8f425-…", "status": "rendering", "stage": "Rendering",
 "createdAt": "2026-11-02T17:39:34.643178Z",
 "progress": {"stage": "assembling", "done": 5, "total": 8}}

GETavatar_video/options/

Lists what you can choose: avatars (id, name, gender, image), templates, languages and shapes.

AI Subtitles

Upload a video, we transcribe it, you pick a caption style, and you get the MP4 back with animated captions burned in. The video keeps its own size. Tool name in your plan: captions.

1. POST captions/upload/ with the video → jobId
2. POST captions/transcribe/{jobId}/ → poll progress/ until transcribed
3. POST captions/generate/ → poll progress/ until done
4. GET captions/download/{jobId}/ → the MP4

POSTcaptions/upload/

Multipart, field file. MP4, MOV or WebM, up to 1 GB and 15 minutes. Answers {"jobId", "videoInfo": {"width", "height", "duration", "fps", "codec"}}.

curl -X POST https://www.vidboard.ai/tool/api/v1/captions/upload/ -H "X-API-Key: vb_live_your_key" -F "file=@talk.mp4"

POSTcaptions/transcribe/{jobId}/

No body. Add ?language=en (a two-letter code) to skip language detection. Answers 202 {"jobId", "status": "queued"}.

GETcaptions/progress/{jobId}/

Always has jobId, status, stage, percent and position (videos ahead of yours, while waiting).

POSTcaptions/generate/ USES ONE API VIDEO

JSON body. Answers 202 {"jobId", "status": "queued"}. Sending it again while the video is being made does not start or count a second one.

curl -X POST https://www.vidboard.ai/tool/api/v1/captions/generate/ \
  -H "X-API-Key: vb_live_your_key" -H "Content-Type: application/json" \
  -d '{"job_id": "JOB_ID", "style_id": "hormozi_1", "vertical": "bottom"}'

GETcaptions/download/{jobId}/

The MP4 itself (not JSON). Use curl -o out.mp4. Jobs and their videos are deleted after 3 days, so download promptly.

GETcaptions/styles/

{"styles": [{"id", "name", "premium", "spec"}]}. Use the id as style_id.

POSTcaptions/translate-transcript/

Optional, free. JSON {"words": [...], "target_language": "es"} → {"words": [...]} in the new language with the same timings. Pass them to generate/ as words for translated captions.

Background removal

Replace the background behind a person in a video with a colour, a picture or another video. No green screen needed. Tool name in your plan: bg_removal.

POSTbg_removal/upload/

Multipart, field file. Up to 200 MB and 5 minutes. Answers {"jobId", "videoInfo": {"width", "height", "fps", "frameCount", "duration"}}.

POSTbg_removal/upload-bg/

Only for a picture or video background. Multipart, fields job_id and file. The file must be sent with an image or video type, for example -F "file=@beach.mp4;type=video/mp4". Answers {"jobId", "bgType"}. A video background loops.

POSTbg_removal/start/ USES ONE API VIDEO PER JOB

JSON body. Answers {"status": "processing"}. It can take up to a minute to answer while our video machine starts. Starting the same job again after a failure is not counted twice.

GETbg_removal/progress/{jobId}/

{"jobId", "status", "progress"}, where status is processing (progress 0–99), done or error (with error; not counted).

GETbg_removal/download/{jobId}/

The MP4 itself. Call it at https://www.vidboard.ai/tool/api/v1/bg_removal/download/{jobId}/ (the downloadUrl in progress is the app's own address). Files are temporary, so download promptly.

Repurpose and reframe

Turn a long video into captioned shorts of its best moments, or reframe the whole video to vertical or square, following the speaker. Tool name in your plan: repurpose. Each uploaded video uses one API video, however many shorts you make from it.

POSTrepurpose/upload/

Multipart, field video. MP4, MOV, WebM or MKV, up to 1 GB and 2 hours. Optional second file bottom: a video to stack under the speaker when reframing. Answers {"jobId", "videoInfo"}.

POSTrepurpose/analyze/{jobId}/ USES ONE API VIDEO PER JOB

Finds the best moments. JSON body, all optional. Answers {"jobId", "status": "transcribing"}.

GETrepurpose/progress/{jobId}/

Finished when status is ready; failed when it is error (with error; not counted). Always check status, not only whether the lists below are filled.

• After analyze: clips = [{"id": "clip-1", "title", "start", "end", "reason", "overallScore", "thumbnail", …}] and faces = the people on screen (face-1…). clips can be empty when the video has no speech.
• After render: outputs = {"clip-1": "https://…/clip-1.mp4", …}.
• After reframe: reframedUrl.

POSTrepurpose/render/{jobId}/

Makes the MP4s for the clips you choose. Free once the job is paid. JSON body. Answers {"jobId", "status": "generating", "clipIds"}.

POSTrepurpose/reframe/{jobId}/ USES ONE API VIDEO PER JOB

The whole video, reframed. JSON {"aspect": "9:16"} (9:16, 1:1 or 16:9), plus optional source_start/source_end. Answers {"jobId", "status": "generating"}; the result is reframedUrl in progress.

GETrepurpose/jobs/ · DELETErepurpose/jobs/{id}/

Your past jobs with their clips (?limit= 1–100), and deleting one with all its files. The id here is the job's id from this list, not its jobId.

Coming soon

Questions or a use case we should support? Write to admin@vidboard.ai.