Put a film studio inside your product.

How it works

Rendering a film takes minutes, not milliseconds. The API is built around that: you submit, we call you back.

Quickstart

Three requests, start to finished film. Base URL is https://cinefables.com.

1 · Get an access token

# Machine-to-machine. Tokens last 24h — cache and reuse them.
curl -X POST https://cinefables.com/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "cf_app_…",
    "client_secret": "cf_sec_…",
    "scope": "videos.write videos.read"
  }'

# → { "access_token": "cfat_…", "token_type": "Bearer", "expires_in": 86400 }

2 · Start a render

curl -X POST https://cinefables.com/dev/v1/videos \
  -H 'Authorization: Bearer cfat_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "idea": "A street cat in Fort Kochi who guards a fishing boat at night.",
    "duration_seconds": 45,
    "language": "ml",
    "tier": "lite"
  }'

# → { "data": { "id": "a-street-cat-ms0i7mzh", "status": "queued", … } }

3 · Collect the film

# When the webhook says video.completed, fetch the outputs.
curl https://cinefables.com/dev/v1/videos/a-street-cat-ms0i7mzh \
  -H 'Authorization: Bearer cfat_…'

# → data.outputs.video_16x9   "/media/…/final-16x9.mp4?exp=…&sig=…"
#   data.outputs.video_9x16   "/media/…/final-9x16.mp4?exp=…&sig=…"
#   data.outputs.subtitles    data.outputs.thumbnail

Authentication

OAuth 2.0. There are no API keys — every token is scoped, attributable and revocable.

Two grants

Access tokens live 24 hours, refresh tokens 30 days and rotate on every use. Presenting a rotated refresh token revokes the whole grant — that is a theft signal, not a retry.

Scopes

Endpoints

Render parameters

Statuses

Webhooks

A render takes minutes, so don't poll — register a callback and we'll tell you. Events: video.completed and video.failed.

POST /api/your-hook                       HTTPS only
X-Cinefables-Event:     video.completed
X-Cinefables-Signature: t=1785312000,v1=9f86d081…

{
  "event": "video.completed",
  "created_at": "2026-07-28T04:21:00.000Z",
  "data": {
    "id": "a-street-cat-ms0i7mzh",
    "status": "ready",
    "title": "The Boat Cat",
    "failed_scenes": []
  }
}

Verifying a delivery

Your endpoint is a public URL, so the signature is what separates us from anyone else who finds it. HMAC-SHA256 over "<timestamp>.<raw body>".

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!(age < 300)) return false;   // bounds replay

  const expected = createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(parts.v1 ?? '', 'hex');
  return a.length === b.length && timingSafeEqual(a, b);
}

Delivery behaviour

Three attempts — immediately, at 30 seconds, at 5 minutes. We retry on 5xx and network errors only: a 4xx means the body itself is wrong, and sending it again changes nothing. Return 2xx quickly and do your work afterwards. Every attempt is logged, so we can tell you exactly why a callback never arrived.

Errors, limits and credits

{ "error": "insufficient_scope",
  "error_description": "This action requires the \"videos.write\" scope" }

Renders are paid for in credits from the authorising account, at the same price as the studio — there is no cheaper API path and no separate metering to reconcile. A failed render refunds the work that never ran.

Get access

The API is in private beta and applications are registered by hand, so we can talk through your use case and set a sensible quota. There is no self-serve signup yet — deliberately.

Email codezy.ai.tech@gmail.com with what you're building, the volume you expect, and your callback URL. You'll get a client id, a client secret, and a webhook signing secret.