API App v0.2.0 Base URL https://chalkboard.studio/api/v1 Last updated 2026-05-29 · Changelog · OpenAPI JSON

Public API

The Chalkboard API.

Generate narrated explainer videos from your code, without the web UI. Authenticate with an API key, POST a topic, get a playable mp4 a few minutes later. Built for CI runners, agent pipelines, internal tools, and anyone wiring Chalkboard into a larger product.

Two ways to run it

We run it, or you run it.

Same FastAPI app, two front doors. The difference that matters: the hosted API is invite-only right now (the open-source build is yours to run today, no gate).

Featured
Hosted

chalkboard.studio

We run the whole pipeline; you just call HTTP. Zero ops: Bearer auth with chk_live_… keys, ready in minutes.

Invite-only Closed beta · code or waitlist
You get
  • HTTP API, no infra
  • Async webhooks
  • Idempotency-Key
  • Cheap chk_test_ CI keys
You skip
  • Running the pipeline
  • Hosting & scaling
  • Managing vendor keys
Sign in →
Self-hosted

Run your own

The same FastAPI app, open source. Clone it, set ANTHROPIC_API_KEY, run python run_server.py behind your own auth. MIT licensed.

Open source Run it now · anyone, no invite
You get
  • The full pipeline
  • Your own keys & auth
  • MIT, fork freely
  • CLI ref at /cli
You bring
  • An Anthropic key
  • OpenAI or ElevenLabs (TTS)
  • A box to run it
Clone ↗

Authentication

API keys.

Create a key at /account → "API keys". Pass it in the standard Authorization: Bearer <key> header. Keys inherit your account's rate limit and spend cap.

Base URL: hosted vs self-hosted

Same routes either way. Only the base URL and how you authenticate change between the managed API and your own build:

  • Hosted (SaaS). Base URL https://chalkboard.studio/api/v1, auth Authorization: Bearer chk_live_… (keys minted at /account). Your account's credits, rate limit and spend cap apply.
  • Self-hosted (OSS). Clone the repo, set ANTHROPIC_API_KEY, run python run_server.py; the base URL becomes http://localhost:8000/api/v1 (or your own host). The managed key and credit system is hosted-only, so you secure it behind your own auth (the bundled App Check gate is off by default). Every endpoint and payload below is identical.

Test-mode keys

Keys prefixed chk_test_ force the cheapest pipeline settings: effort=low, quality=low, qa_density=zero, model=claude-sonnet-4-6, no quiz, no burned-in captions. Much cheaper than a live run; great for CI smoke-tests against new features.

The same code path runs: test mode is a real pipeline execution against real Claude + TTS. Just at the cheap end of every dial. Test runs land in /library with a TEST pill so you can tell them apart from real renders.

Web UI auth

The browser app at /library uses short-lived session ID tokens (1-hour TTL) instead of API keys (irrelevant for programmatic use, but worth knowing if you're inspecting the network tab). The same endpoints accept either.

Quickstart

Create + poll.

Two-step pattern: POST /jobs returns a 202 with a JobResponse; GET /jobs/{id} polls the same shape until status is completed or failed. SSE-streamed updates available at /jobs/{id}/events if you'd rather avoid polling.

The example on the right shows the full lifecycle: create a job, read the id from the 202 response, poll until terminal, then pull final.mp4.

Running your own build? Point these same calls at your host: swap https://chalkboard.studio/api/v1 for http://localhost:8000/api/v1 (default port 8000). Nothing else changes.

Idempotency

Safe retries.

Pass a unique Idempotency-Key on any POST /jobs (or /jobs/{id}/retry, /jobs/{id}/rerender). If the request times out at the load balancer or your client crashes mid-flight, retry with the same key and you'll get the same response back, with no duplicate paid job. Keys are scoped per account and live for 24 hours.

Reuse a key with a different request body inside the 24h window and you get a 409 back. Generate a new key for distinct requests; UUID v4 is a fine default.

Webhooks

Push instead of poll.

Subscribe at /account → "Webhooks". On every terminal job state change we POST a signed JSON payload to your URL. Deliveries are sent asynchronously with exponential backoff, retried up to six times before the endpoint is auto-disabled, so an abandoned endpoint doesn't retry forever.

Verifying the signature

HMAC-SHA256 over the timestamped body: X-Chalkboard-Signature: t=<unix>,v1=<sha256-hex> where the HMAC input is f"{t}.{body}". The signing secret is shown once at create time. Reject signatures older than 5 minutes to defend against replays. The payload + verify snippet are on the right.

Errors

Error shape.

All errors return JSON with a detail field describing what went wrong. Status codes follow the usual REST conventions:

  • 400Idempotency-Key over 200 chars, or other client error
  • 401invalid or missing API key
  • 402insufficient credits to start this render, or the daily spend safety cap was reached
  • 403banned account, or attempting key/webhook management with API-key auth
  • 404job / video / webhook doesn't exist or doesn't belong to you (deliberately ambiguous to avoid leaking existence)
  • 409Idempotency-Key reused with a different body, or retrying an in-flight job
  • 413upload exceeds the size cap (the multipart /jobs/upload path)
  • 422request body failed validation (FastAPI's standard validation error array)
  • 429rate limit exceeded; Retry-After header tells you how long to wait
  • 503service temporarily paused (maintenance / capacity); safe to retry

Rate limits

Per-account ceilings.

Default closed-beta limits:

  • 60/min60 requests / minute: burst-friendly; rolls over each minute
  • 1k/day1,000 credits / day spend cap: about 27 live runs, or about 110 test-mode runs

Need higher? Email us with a sketch of what you're building. Per-account overrides are a first-class admin feature; we're happy to bump cooperative integrators.

Endpoints

What's available.

Every URL below also accepts the unversioned /api/... form, but we recommend the /api/v1/ path for new integrations. Older paths return Deprecation: true + Link: rel=successor-version headers.

POST
/api/v1/jobs
Create a job. Idempotency-Key supported.
POST
/api/v1/jobs/upload
Multipart create. Attach files as context.
POST
/api/v1/jobs/estimate
Pre-flight cost: (low, high) credit range + balance. No job created, no spend.
GET
/api/v1/jobs
List your jobs, newest first.
GET
/api/v1/jobs/{id}
Job detail (status, events, output_files).
GET
/api/v1/jobs/{id}/events
SSE stream of pipeline progress.
GET
/api/v1/jobs/{id}/log
One-shot pipeline log (?format=text|json).
DELETE
/api/v1/jobs/{id}
Cancel an in-flight job.
POST
/api/v1/jobs/{id}/retry
Re-run with the same params (terminal source only).
POST
/api/v1/jobs/{id}/rerender
Reuse the script + voiceover, regenerate the Manim scene.
GET
/api/v1/jobs/{id}/files/{name}
Download a single output file (final.mp4, thumb.jpg, …).
GET
/api/v1/library
Your video library. Filterable by status.
GET
/api/v1/library/{id}
Single video meta + signed download URLs.
DELETE
/api/v1/library/{id}
Delete a video from your library.
POST
/api/v1/webhooks
Subscribe to terminal events.
GET
/api/v1/webhooks
List your webhooks.
DELETE
/api/v1/webhooks/{id}
Remove a webhook subscription.
GET
/api/v1/webhooks/{id}/deliveries
Last 50 delivery attempts (debugging).
GET
/api/meta
App version. Used by clients to gate on schema changes.

Full machine-readable spec at /openapi.json. Paste it into Postman, Insomnia, or any OpenAPI-savvy tool to generate client code.

SDKs

Client libraries.

Python, chalkboard-sdk v0.1.1. Typed sync client wrapping the four canonical flows (create + poll, create + stream events, library, job lifecycle). Single runtime dep (httpx); ships with a verify_webhook_signature helper that round-trips with the server signer.

Install + use 
# install the wheel from the OSS repo's GitHub Release
pip install https://github.com/nicglazkov/Chalkboard/releases/download/sdk-py/v0.1.1/chalkboard_sdk-0.1.1-py3-none-any.whl

from chalkboard import ChalkboardClient

client = ChalkboardClient(api_key="chk_live_…")
job    = client.create_job(topic="How hash tables work")
final  = client.wait_for_completion(job.id, timeout=600)
client.download_file(final.id, "final.mp4", out_path="hash-tables.mp4")

Source + full README: github.com/nicglazkov/Chalkboard/sdk/python ↗. Closed-beta period: shipped via GitHub Releases on the OSS repo until the v1 surface stabilises and we publish to PyPI.

Other languages. No official SDK yet, but curl + the /openapi.json spec are enough to generate a client in any language with openapi-generator.

Questions, bugs, integration help? hello@chalkboard.studio. Closed-beta means we read every email.