Get started
Quickstart
From nothing to a downloaded video in four steps. Every request goes to the base URL above and sends JSON.
Step 1: Create a key
Open Workspace → API, choose Create key and copy it. It starts with
sk_live_and is shown once. Keep it in an environment variable on your server:Shell export FIKRABOARD_API_KEY="sk_live_…"Step 2: Create a video
Send a prompt. Everything else has a sensible default. The answer comes right away with the video queued.
curl -X POST "/api/v1/videos" \ -H "Authorization: Bearer $FIKRABOARD_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Explain how the heart pumps blood, for 12-year-olds." }'Step 3: Wait until it's done
Check the video every few seconds until
statusisdone(orfailed). Most videos are ready in a few minutes. Or skip polling and get a webhook when it's ready.curl "https://vioogen.com/api/v1/videos/6f1d2c3b-8a47-4f0e-9b2d-1c5e7a9f3b10" \ -H "Authorization: Bearer $FIKRABOARD_API_KEY"Step 4: Download it
The download link redirects to the MP4 file. Follow the redirect and save it.
curl -L -o video.mp4 "/api/v1/videos/6f1d2c3b-8a47-4f0e-9b2d-1c5e7a9f3b10/download" \ -H "Authorization: Bearer $FIKRABOARD_API_KEY"
Send your key in the Authorization header of every request. There are no cookies and no CSRF tokens.
Authorization: Bearer sk_live_…- A key belongs to a workspace, your personal one or an organization, and acts as that workspace: it sees its videos and folders and spends its credits.
- In an organization only owners and admins create and revoke keys. In your personal workspace you can.
- Keep keys secret. Use them only on your server, never in a browser, a mobile app or a public repository.
- If a key leaks, revoke it in Workspace → API. It stops working at once.
A missing, wrong or revoked key gets 401 with the code unauthorized.
Endpoints
Videos
Create videos, follow them while they're made, then download, translate or delete them.
The video object
Every video endpoint answers with this object (the list wraps it in data).
Fields
- idstring
- The video's id.
- titlestring
- A short title, written from your prompt.
- statusstring
queued(waiting to start),making,doneorfailed.- progressinteger
- 0 to 100 while the video is made; 100 when it's done.
- errorstring | null
- Why the video failed, in plain words. null otherwise.
- languagestring
- Language code, from /languages.
- stylestring
- Style id, from /styles.
- aspect_ratiostring
16:9,9:16or1:1.- durationnumber | null
- Length in seconds, once it's done.
- video_urlstring | null
- A temporary link to the MP4, once it's done.
- poster_urlstring | null
- A temporary link to a still image of the video.
- created_atstring
- When it was created (ISO 8601, UTC).
- finished_atstring | null
- When it finished or failed.
video_url and poster_url are temporary links. Don't store them: fetch the video again for fresh ones, or use the download endpoint.{
"id": "6f1d2c3b-8a47-4f0e-9b2d-1c5e7a9f3b10",
"title": "How the heart works",
"status": "done",
"progress": 100,
"error": null,
"language": "en",
"style": "whiteboard",
"aspect_ratio": "16:9",
"duration": 62.4,
"video_url": "https://files.example.com/v/6f1d2c3b.mp4?expires=1791371741&sig=3c9a…",
"poster_url": "https://files.example.com/v/6f1d2c3b.jpg?expires=1791371741&sig=8b21…",
"created_at": "2026-10-07T09:12:03Z",
"finished_at": "2026-10-07T09:15:41Z"
}Create a video
POST/api/v1/videos
Creates a video and starts making it. The answer comes at once with the video queued; its URL is also in the Location header. The workspace's credits pay for it, as in the studio.
Body (JSON)
- promptstringrequired
- What the video is about, up to 20,000 characters. Plain words work best.
- languagestring
- Language code from /languages. Default
en. - stylestring
- Style id from /styles. Default
whiteboard. - aspect_ratiostring
16:9(default),9:16or1:1.- lengthstring | integer
auto(default) or a length in seconds:30,60,120,180or300.- voicestring
- Voice id from /voices. A default voice is used when left out.
- subtitlesboolean
- Burn subtitles into the video. Default
false. - soundsboolean
- Drawing sounds under the voice. Default
true. - musicstringrolling out
- Background music:
""for none (default),autoto match your video (picks music that fits the video's purpose and style), or a mood:calm,upbeat,inspiring,corporate,playful,dramatic,ambient. Available when your plan includes background music. - brandbooleanrolling out
- Use the workspace's brand kit. Default
false. - charactersstring[]rolling out
- Up to 2 character ids to keep the same people across videos.
- folderstring
- Folder id from /folders.
- teamstring
- Team id, for organization workspaces. Required when the key's creator belongs to more than one team. Ids are in /account.
- attachmentsobject[]
- Up to 3 files to build the video from, as
{"url": "https://…"}. We download them: PDF, PowerPoint (.pptx), PNG, JPG or WebP, up to 20 MB each. The URLs must be https and publicly reachable. - webhook_urlstring
- An https URL for this video's webhook events. Wins over the workspace default.
curl -X POST "/api/v1/videos" \
-H "Authorization: Bearer $FIKRABOARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Explain how the heart pumps blood, for 12-year-olds.",
"language": "en",
"style": "whiteboard",
"aspect_ratio": "16:9",
"length": 60,
"subtitles": true,
"webhook_url": "https://example.com/webhooks/fikraboard"
}'{
"id": "6f1d2c3b-8a47-4f0e-9b2d-1c5e7a9f3b10",
"title": "How the heart works",
"status": "queued",
"progress": 0,
"error": null,
"language": "en",
"style": "whiteboard",
"aspect_ratio": "16:9",
"duration": null,
"video_url": null,
"poster_url": null,
"created_at": "2026-10-07T09:12:03Z",
"finished_at": null
}402 insufficient_creditswhen the workspace can't cover the estimate. Nothing is created and nothing is charged.400 invalid_requestwithfieldswhen something in the body is off.- Up to 10 new videos a minute per key (creates and translations together).
List videos
GET/api/v1/videos
The workspace's videos, newest first, a page at a time.
Query
- statusstring
queued,making,doneorfailed.- folderstring
- A folder id, or
unfiledfor videos in no folder. - limitinteger
- 1 to 100. Default
20. - cursorstring
- The
next_cursorof the previous page.
curl "/api/v1/videos?status=done&limit=20" \
-H "Authorization: Bearer $FIKRABOARD_API_KEY"{
"data": [
{
"id": "6f1d2c3b-8a47-4f0e-9b2d-1c5e7a9f3b10",
"title": "How the heart works",
"status": "done",
"progress": 100,
"error": null,
"language": "en",
"style": "whiteboard",
"aspect_ratio": "16:9",
"duration": 62.4,
"video_url": "https://files.example.com/v/6f1d2c3b.mp4?expires=1791371741&sig=3c9a…",
"poster_url": "https://files.example.com/v/6f1d2c3b.jpg?expires=1791371741&sig=8b21…",
"created_at": "2026-10-07T09:12:03Z",
"finished_at": "2026-10-07T09:15:41Z"
}
],
"next_cursor": "eyJjcmVhdGVkIjoiMjAyNi0xMC0wN1QwOToxMjowM1oifQ"
}next_cursor is null on the last page.
Get a video
GET/api/v1/videos/{id}
One video, with its current status and progress. Use it to poll, and to get fresh temporary links.
curl "/api/v1/videos/6f1d2c3b-8a47-4f0e-9b2d-1c5e7a9f3b10" \
-H "Authorization: Bearer $FIKRABOARD_API_KEY"{
"id": "6f1d2c3b-8a47-4f0e-9b2d-1c5e7a9f3b10",
"title": "How the heart works",
"status": "done",
"progress": 100,
"error": null,
"language": "en",
"style": "whiteboard",
"aspect_ratio": "16:9",
"duration": 62.4,
"video_url": "https://files.example.com/v/6f1d2c3b.mp4?expires=1791371741&sig=3c9a…",
"poster_url": "https://files.example.com/v/6f1d2c3b.jpg?expires=1791371741&sig=8b21…",
"created_at": "2026-10-07T09:12:03Z",
"finished_at": "2026-10-07T09:15:41Z"
}Delete a video
DELETE/api/v1/videos/{id}
Deletes the video and its files for good. Answers 204 with no body.
curl -X DELETE "/api/v1/videos/6f1d2c3b-8a47-4f0e-9b2d-1c5e7a9f3b10" \
-H "Authorization: Bearer $FIKRABOARD_API_KEY"Download a video
GET/api/v1/videos/{id}/download
Redirects (302) to a temporary link to the MP4. With curl, pass -L to follow it. Answers 409 conflict while the video isn't done.
curl -L -o video.mp4 "/api/v1/videos/6f1d2c3b-8a47-4f0e-9b2d-1c5e7a9f3b10/download" \
-H "Authorization: Bearer $FIKRABOARD_API_KEY"Translate a video
POST/api/v1/videos/{id}/translate
Makes a new video from a finished one, in another language. The answer is the new video, queued. It costs credits like a new video.
Body (JSON)
- languagestringrequired
- The language to make it in, from /languages.
- voicestring
- Voice id for the new video, from /voices. Optional.
- webhook_urlstring
- An https URL for the new video's webhook events.
curl -X POST "/api/v1/videos/6f1d2c3b-8a47-4f0e-9b2d-1c5e7a9f3b10/translate" \
-H "Authorization: Bearer $FIKRABOARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"language": "es"
}'{
"id": "9a2e4b71-3c5d-4f8a-b1e2-7d6c0f9a8e35",
"title": "Cómo funciona el corazón",
"status": "queued",
"progress": 0,
"error": null,
"language": "es",
"style": "whiteboard",
"aspect_ratio": "16:9",
"duration": null,
"video_url": null,
"poster_url": null,
"created_at": "2026-10-07T09:12:03Z",
"finished_at": null
}409 conflictwhen the source video isn't done.400 invalid_requestwhen the language is the video's own.
Endpoints
Extras
From a finished video, make a summary and a quiz, titles with a description, hashtags and chapters, or a thumbnail. They're written in the video's language.
The extras object
- summaryobject | null
headline,paragraphandkey_points(strings).- quizobject | null
questions: each withquestion, 4choices,answer_index(0 to 3) andexplanation.- titlesobject | null
- 5
titles, adescription,hashtagsandchapters(time_seconds,title). - thumbnailobject | null
url(temporary),widthandheight.- makingstring | null
- What is being made right now:
summary_quiz,titles,thumbnailornull. - estimatesobject
- Credits each kind costs:
summary_quiz,titles,thumbnail.
Get extras
GET/api/v1/videos/{id}/extras
What has been made so far, what is being made and what each kind costs.
curl "/api/v1/videos/6f1d2c3b-8a47-4f0e-9b2d-1c5e7a9f3b10/extras" \
-H "Authorization: Bearer $FIKRABOARD_API_KEY"{
"summary": {
"headline": "Your heart is a four-room pump",
"paragraph": "The heart pushes blood through two loops: one through the lungs to pick up oxygen, and one through the body to deliver it.",
"key_points": [
"The heart has four chambers.",
"Valves keep blood flowing one way.",
"The right side pumps to the lungs, the left side to the body."
]
},
"quiz": {
"questions": [
{
"question": "Where does blood pick up oxygen?",
"choices": [
"In the lungs",
"In the stomach",
"In the heart valves",
"In the bones"
],
"answer_index": 0,
"explanation": "The right side of the heart pumps blood to the lungs, where it picks up oxygen."
}
]
},
"titles": null,
"thumbnail": null,
"making": null,
"estimates": {
"summary_quiz": 2,
"titles": 1,
"thumbnail": 3
}
}Make extras
POST/api/v1/videos/{id}/extras/{kind}
Starts making one kind: summary_quiz (the summary and quiz together), titles or thumbnail. It costs the credits in estimates. Poll Get extras until making is null.
curl -X POST "/api/v1/videos/6f1d2c3b-8a47-4f0e-9b2d-1c5e7a9f3b10/extras/summary_quiz" \
-H "Authorization: Bearer $FIKRABOARD_API_KEY"{
"summary": {
"headline": "Your heart is a four-room pump",
"paragraph": "The heart pushes blood through two loops: one through the lungs to pick up oxygen, and one through the body to deliver it.",
"key_points": [
"The heart has four chambers.",
"Valves keep blood flowing one way.",
"The right side pumps to the lungs, the left side to the body."
]
},
"quiz": {
"questions": [
{
"question": "Where does blood pick up oxygen?",
"choices": [
"In the lungs",
"In the stomach",
"In the heart valves",
"In the bones"
],
"answer_index": 0,
"explanation": "The right side of the heart pumps blood to the lungs, where it picks up oxygen."
}
]
},
"titles": null,
"thumbnail": null,
"making": "summary_quiz",
"estimates": {
"summary_quiz": 2,
"titles": 1,
"thumbnail": 3
}
}409 conflict when the video isn't done or extras are already being made for it.
Endpoints
Options and account
Ids for the create call, a credit estimate and the workspace's balance.
Estimate credits
GET/api/v1/estimate
About how many credits a video will cost, and whether the workspace has enough.
Query
- lengthstring | integer
autoor seconds, as in the create call.- stylestring
- Style id.
- aspect_ratiostring
16:9,9:16or1:1.
curl "/api/v1/estimate?length=60&style=whiteboard&aspect_ratio=16%3A9" \
-H "Authorization: Bearer $FIKRABOARD_API_KEY"{
"credits": 12,
"balance": 480,
"enough": true
}Styles
GET/api/v1/styles
The drawing styles you can pass as style.
curl "/api/v1/styles" \
-H "Authorization: Bearer $FIKRABOARD_API_KEY"{
"data": [
{
"id": "whiteboard",
"name": "Whiteboard",
"description": "Marker drawings on a clean white board."
},
{
"id": "chalkboard",
"name": "Chalkboard",
"description": "Chalk on a dark slate."
},
{
"id": "sketch",
"name": "Pencil sketch",
"description": "Pencil lines on paper."
}
]
}Voices
GET/api/v1/voices
The voices you can pass as voice, including the workspace's own voices (custom: true).
curl "/api/v1/voices" \
-H "Authorization: Bearer $FIKRABOARD_API_KEY"{
"data": [
{
"id": "amy",
"name": "Amy",
"description": "Bright and friendly",
"custom": false
},
{
"id": "kadir",
"name": "Kadir",
"description": "Warm and unhurried",
"custom": false
},
{
"id": "f41c9e2a-77b0-4d1e-9a3c-5e2b8d6f0c14",
"name": "Our founder",
"description": "Your own voice",
"custom": true
}
]
}Languages
GET/api/v1/languages
The languages you can pass as language.
curl "/api/v1/languages" \
-H "Authorization: Bearer $FIKRABOARD_API_KEY"{
"data": [
{
"code": "en",
"name": "English"
},
{
"code": "es",
"name": "Spanish"
},
{
"code": "hi",
"name": "Hindi"
}
]
}Folders
GET/api/v1/folders
The workspace's folders, for folder when you create or list videos. In an organization each folder belongs to a team.
curl "/api/v1/folders" \
-H "Authorization: Bearer $FIKRABOARD_API_KEY"{
"data": [
{
"id": "c3e8a1f0-2b4d-4c6e-8f9a-0b1c2d3e4f50",
"name": "Biology",
"video_count": 12,
"team": {
"id": "t-7d1e",
"name": "Science"
}
},
{
"id": "d4f9b2a1-3c5e-4d7f-9a0b-1c2d3e4f5a61",
"name": "Onboarding",
"video_count": 3,
"team": null
}
]
}Account
GET/api/v1/account
The workspace the key belongs to, its credit balance and, in an organization, the teams the key's creator is in (ids for team).
curl "/api/v1/account" \
-H "Authorization: Bearer $FIKRABOARD_API_KEY"{
"workspace": {
"id": "0b7e5c2a-9d14-4f3b-8e6a-2c1d9f0e7a53",
"kind": "organization",
"name": "Acme Learning"
},
"credits": 480,
"teams": [
{
"id": "t-7d1e",
"name": "Science"
},
{
"id": "t-2a9c",
"name": "Marketing"
}
]
}OpenAPI schema
GET/api/v1/openapi.json
The whole API as an OpenAPI 3.1 schema, for code generators and API clients. No key needed. Open the schema
Guides
Webhooks
Instead of polling, let us tell your server when a video is ready. We send two events: video.done and video.failed.
- Set a default URL for the workspace in Workspace → API, or pass
webhook_urlwhen you create a video. A video's own URL wins. - We POST JSON to the URL. The URL must be https.
Content-Type: application/json
User-Agent: FikraBoard-Webhooks/1.0
X-FikraBoard-Event: video.done
X-FikraBoard-Delivery: 3f9d2c1e-7b4a-4e8f-9c2d-5a6b7c8d9e0f
X-FikraBoard-Signature: t=1791371742,v1=5f2b8c…{
"id": "3f9d2c1e-7b4a-4e8f-9c2d-5a6b7c8d9e0f",
"type": "video.done",
"created_at": "2026-10-07T09:15:42Z",
"data": {
"video": {
"id": "6f1d2c3b-8a47-4f0e-9b2d-1c5e7a9f3b10",
"title": "How the heart works",
"status": "done",
"progress": 100,
"error": null,
"language": "en",
"style": "whiteboard",
"aspect_ratio": "16:9",
"duration": 62.4,
"video_url": "https://files.example.com/v/6f1d2c3b.mp4?expires=1791371741&sig=3c9a…",
"poster_url": "https://files.example.com/v/6f1d2c3b.jpg?expires=1791371741&sig=8b21…",
"created_at": "2026-10-07T09:12:03Z",
"finished_at": "2026-10-07T09:15:41Z"
}
}
}Check the signature
Every webhook carries X-FikraBoard-Signature: t=<unix seconds>,v1=<hex>. v1 is an HMAC-SHA256 of t + "." + the raw request body, keyed with your workspace's signing secret (the whole whsec_… string). Find the secret in Workspace → API.
Step 1: Read t and v1 from the header
Split it on commas, then each part on the first
=.Step 2: Reject old timestamps
If
tis more than 5 minutes away from your clock, drop the request. This stops replays.Step 3: Compute and compare
HMAC-SHA256 the exact bytes you received (not re-encoded JSON) and compare with
v1in constant time.
# Check a signature by hand with openssl:
BODY='{"id":"3f9d2c1e-7b4a-4e8f-9c2d-5a6b7c8d9e0f","type":"video.done",…}'
T=1791371742
printf '%s.%s' "$T" "$BODY" \
| openssl dgst -sha256 -hmac "$FIKRABOARD_WEBHOOK_SECRET" -hex
# The hex digest must equal v1.Answer fast, expect retries
- Answer with a 2xx status within 10 seconds. Do slow work after you answer.
- Anything else, including a redirect or a timeout, is retried up to 5 times with growing gaps: about 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours.
- An event can arrive more than once. Use the delivery id (
idin the body, also inX-FikraBoard-Delivery) to skip ones you have handled.
Errors use the HTTP status and a JSON body with a stable code and a message you can show to people.
{
"error": {
"code": "invalid_request",
"message": "Check the fields and try again.",
"fields": {
"prompt": [
"This field is required."
]
}
}
}Validation errors add fields, with messages per field. insufficient_credits adds required and balance:
{
"error": {
"code": "insufficient_credits",
"message": "You need about 24 credits for this. Your balance is 10.",
"required": 24,
"balance": 10
}
}| Code | Status | What it means |
|---|---|---|
invalid_request | 400 | Something in the request is missing or wrong. See fields. |
unauthorized | 401 | The key is missing, wrong or revoked. |
insufficient_credits | 402 | Not enough credits. Nothing was started or charged. |
forbidden | 403 | The key can't do this in its workspace. |
not_found | 404 | No such video, folder or route in this workspace. |
conflict | 409 | Not possible right now, e.g. the video isn't done yet. |
rate_limited | 429 | Too many requests. Wait for Retry-After seconds. |
server_error | 500 | Something went wrong on our side. Try again. |
unavailable | 503 | We're busy or down for a moment. Try again shortly. |
Each key can make up to:
- 60 requests a minute, and
- 10 new videos a minute (creates and translations together).
Every answer has X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit you get 429 rate_limited with a Retry-After header in seconds. Wait that long, then try again.
- Making a video, translating one and making extras spend the workspace's credits, the same as in the studio.
- Call /estimate first to see what a video costs and whether the balance covers it. /account shows the balance.
402 insufficient_creditsmeans nothing was started and nothing was charged.- If a video fails because of us, its credits come back on their own.
- Buy more credits in Billing.