Skip to content

Fikra Board API · v1

Make videos from your code.

Send a prompt, get back a narrated video that looks drawn by hand. The same studio as the app, from your own server: same styles, voices and languages, paid with the same credits.

Base URL
https://vioogen.com/api/v1

Get started

Quickstart

From nothing to a downloaded video in four steps. Every request goes to the base URL above and sends JSON.

  1. 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_…"
  2. 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."
      }'
  3. Step 3: Wait until it's done

    Check the video every few seconds until status is done (or failed). 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"
  4. 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.

Header
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, done or failed.
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:16 or 1: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.
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"
}

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:16 or 1:1.
lengthstring | integer
auto (default) or a length in seconds: 30, 60, 120, 180 or 300.
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), auto to 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"
  }'
Response 202 · Location: /api/v1/videos/6f1d…
{
  "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_credits when the workspace can't cover the estimate. Nothing is created and nothing is charged.
  • 400 invalid_request with fields when 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, done or failed.
folderstring
A folder id, or unfiled for videos in no folder.
limitinteger
1 to 100. Default 20.
cursorstring
The next_cursor of the previous page.
curl "/api/v1/videos?status=done&limit=20" \
  -H "Authorization: Bearer $FIKRABOARD_API_KEY"
Response 200
{
  "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"
Response 200
{
  "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"
  }'
Response 202
{
  "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 conflict when the source video isn't done.
  • 400 invalid_request when 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, paragraph and key_points (strings).
quizobject | null
questions: each with question, 4 choices, answer_index (0 to 3) and explanation.
titlesobject | null
5 titles, a description, hashtags and chapters (time_seconds, title).
thumbnailobject | null
url (temporary), width and height.
makingstring | null
What is being made right now: summary_quiz, titles, thumbnail or null.
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"
Response 200
{
  "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"
Response 202
{
  "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.

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
auto or seconds, as in the create call.
stylestring
Style id.
aspect_ratiostring
16:9, 9:16 or 1:1.
curl "/api/v1/estimate?length=60&style=whiteboard&aspect_ratio=16%3A9" \
  -H "Authorization: Bearer $FIKRABOARD_API_KEY"
Response 200
{
  "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"
Response 200
{
  "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"
Response 200
{
  "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"
Response 200
{
  "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"
Response 200
{
  "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"
Response 200
{
  "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_url when you create a video. A video's own URL wins.
  • We POST JSON to the URL. The URL must be https.
Headers
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…
Body
{
  "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.

  1. Step 1: Read t and v1 from the header

    Split it on commas, then each part on the first =.

  2. Step 2: Reject old timestamps

    If t is more than 5 minutes away from your clock, drop the request. This stops replays.

  3. Step 3: Compute and compare

    HMAC-SHA256 the exact bytes you received (not re-encoded JSON) and compare with v1 in 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 (id in the body, also in X-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.

Response 400
{
  "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:

Response 402
{
  "error": {
    "code": "insufficient_credits",
    "message": "You need about 24 credits for this. Your balance is 10.",
    "required": 24,
    "balance": 10
  }
}
CodeStatusWhat it means
invalid_request400Something in the request is missing or wrong. See fields.
unauthorized401The key is missing, wrong or revoked.
insufficient_credits402Not enough credits. Nothing was started or charged.
forbidden403The key can't do this in its workspace.
not_found404No such video, folder or route in this workspace.
conflict409Not possible right now, e.g. the video isn't done yet.
rate_limited429Too many requests. Wait for Retry-After seconds.
server_error500Something went wrong on our side. Try again.
unavailable503We'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_credits means 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.
We add fields to responses over time. Ignore fields you don't know; existing fields and codes in v1 stay as documented here.