How it works
Videos are generated asynchronously. Your server calls POST /api/v1/videos and immediately gets a video id. Cexi researches the topic on the web, writes a scene-by-scene script, picks vertical footage or archive images and records the voice-over — usually in under a minute.
When the video is ready we send a signed webhook (video.ready). You can also poll GET /api/v1/videos/:id. The response contains the full script, media URLs, the audio and a signed embed_url that plays the video with captions and lets the viewer download a 1080×1920 MP4 rendered in their own browser.
Base URL: https://cexi.app. All requests and responses are JSON over HTTPS.
Authentication
Send your secret key in the Authorization header: Authorization: Bearer cx_live_… Keys are shown once when created; we only store a hash. Revoking a key takes effect immediately.
Secret keys are for servers only. Requests that come from a browser are rejected (browser_not_allowed). Never ship a key inside a mobile app bundle — call Cexi from your backend and give your app the embed URL.
Your partner code (CXP-…) identifies your account for activation and support. It is not a password and can't call the API by itself.
Quick start
Create a video, wait for the webhook (or poll), then open embed_url.
curl https://cexi.app/api/v1/videos \
-H "Authorization: Bearer $CEXI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042" \
-d '{
"topic": "Why is the Dead Sea so salty?",
"language": "en",
"duration_sec": 60,
"template_id": "klasik",
"external_ref": "user_381"
}'Endpoints
All endpoints require a secret key.
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/videos | Start a new video from a topic or a link. Returns 202 with status "generating". |
| GET | /api/v1/videos/:id | Get a video: status, script, scenes, media, audio and a 1-hour embed_url once ready. |
| GET | /api/v1/videos | List your videos, newest first (limit, before). |
| POST | /api/v1/videos/:id/embed | Create a fresh signed embed_url for a ready video (valid for 1 hour). |
| GET | /api/v1/videos/:id/audio | Download the voice-over (audio/mpeg). |
| GET | /api/v1/templates | List the visual templates (id, name, category). |
| GET | /api/v1/voices | List available AI voices. |
| GET | /api/v1/account | Your partner code, plan, remaining credits and limits. |
Create a video
POST /api/v1/videos — costs credits up front (1 credit = 10 seconds; a 60-second video costs 6). If generation fails the credits are refunded automatically.
| Field | Type | Description |
|---|---|---|
| topic | string, required | What the video is about (3–4,000 characters). You can include up to 3 links; Cexi reads them as sources. |
| language | string | en (default), tr, de, es or ar — script and voice language. |
| duration_sec | number | 30, 45, 60 (default), 90 or 120 — limited by your plan. |
| template_id | string | Visual template, see GET /api/v1/templates. Default: klasik. |
| tone | string | samimi (friendly, default), bilgilendirici (informative), enerjik (energetic), hikaye (storytelling), mitkirici (myth-busting) or esprili (witty). |
| voice_id | string | A voice from GET /api/v1/voices. Default: the studio's default voice. |
| external_ref | string | Your own reference (user id, order id…), returned on every read. Max 120 characters. |
Send an Idempotency-Key header (any unique string) to safely retry: the same key always returns the same video and is never charged twice.
The video object
Returned by every video endpoint.
| Field | Type | Description |
|---|---|---|
| id | string | vid_… identifier. |
| status | string | generating → ready, or failed (credits refunded). |
| title, topic, language, duration_sec, template_id, voice_id | What was produced. | |
| external_ref | string | null | Your reference. |
| credits_charged | number | Credits used (0 after a refund). |
| script | object | null | scenes[] (id, kind, narration, on_screen, media {kind, url, thumb, source, author, author_url}), caption, hashtags, sources[]. |
| audio | object | null | url (GET with your key) and duration_sec. |
| embed_url, embed_expires_at | string | null | Signed player URL, valid for 1 hour. Request a new one any time. |
| created_at, updated_at | string | ISO 8601 timestamps. |
{
"id": "vid_7179fAdMpQkwtw",
"object": "video",
"status": "ready",
"title": "Why is the Dead Sea so salty?",
"language": "en",
"duration_sec": 60,
"credits_charged": 6,
"external_ref": "user_381",
"script": {
"scenes": [
{ "id": "s1", "kind": "hook", "narration": "…", "on_screen": "…",
"media": { "kind": "video", "url": "https://…", "source": "pexels" } }
],
"caption": "…", "hashtags": ["#science"], "sources": [{ "title": "…", "url": "https://…" }]
},
"audio": { "url": "https://cexi.app/api/v1/videos/vid_…/audio", "duration_sec": 57.4 },
"embed_url": "https://cexi.app/partner-embed/vid_…?t=…",
"embed_expires_at": "2026-11-18T22:20:02.574Z"
}Embed the player
embed_url opens a full-screen vertical player with synced captions and an MP4 button. Put it in an iframe on the web, in WKWebView on iOS or in WebView on Android. No Cexi account or cookie is needed — the URL is signed, bound to one video and expires after an hour.
The MP4 (1080×1920, H.264) is rendered in the viewer's browser with WebCodecs, so there is no render queue and no extra cost. On Growth and Scale plans the player is white-label (no "Made with Cexi").
<iframe
src="EMBED_URL_FROM_YOUR_SERVER"
style="width:360px;aspect-ratio:9/19;border:0;border-radius:16px"
allow="autoplay; fullscreen"
></iframe>
<script>
window.addEventListener("message", (e) => {
if (e.data?.source === "cexi") console.log("player:", e.data.type);
});
</script>The player posts messages to the parent window: { source: "cexi", type: "play" | "pause" | "render_started" | "render_done" | "render_failed" }.
Webhooks
Set an https URL in the partner portal. We POST a JSON event and retry up to 3 times if your endpoint doesn't answer 2xx. Respond quickly and process asynchronously.
Every request is signed: Cexi-Signature: t=<unix seconds>,v1=<hex>. v1 is HMAC-SHA256 of "<t>.<raw body>" with your signing secret (whsec_…). Reject events older than 5 minutes.
| Event | Payload | |
|---|---|---|
| video.ready | data: id, status, title, duration_sec | The video is ready; GET it for the script and a fresh embed_url. |
| video.failed | data: id, status, error, credits_refunded | Generation failed and the credits were refunded. |
| ping | data: message | Sent by the "Send test" button in the portal. |
Verify a webhook (Node.js)
import crypto from "node:crypto";
// Express: app.post("/webhooks/cexi", express.raw({ type: "application/json" }), handler)
export function verifyCexi(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // 5 minutes
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 || ""));
}Errors
Errors return a non-2xx status and { "error": { "code", "message" } }.
| Code | HTTP | Meaning |
|---|---|---|
| missing_api_key / invalid_api_key / revoked_api_key | 401 | Check the Authorization header or create a new key. |
| browser_not_allowed | 403 | Secret keys can't be used from a browser. Call from your server. |
| partner_inactive / partner_suspended | 403 | Activate the portal with your code, or contact us. |
| ip_not_allowed | 403 | The request IP isn't in your allowlist. |
| duration_not_in_plan | 403 | Choose a shorter duration or upgrade. |
| invalid_topic / invalid_duration / invalid_template / invalid_tone / invalid_json | 400 | Fix the request body. |
| insufficient_credits | 402 | Not enough credits. Upgrade or wait for the monthly reset. |
| video_not_found | 404 | Unknown id for your account. |
| video_not_ready / audio_not_ready | 409 | Wait for status "ready". |
| rate_limited | 429 | Too many requests; respect the Retry-After header. |
| server_error | 500 | Unexpected error; retry with the same Idempotency-Key. |
Rate limits and credits
Each key has a per-minute request limit from your plan (trial: 10/min). Responses include X-RateLimit-Limit and X-RateLimit-Remaining.
Credits renew monthly with your subscription and don't roll over. Partner credits are separate from any consumer Cexi account.
Security
- Keys are stored as SHA-256 hashes and compared in constant time; you see a key only once.
- Optional IP allowlist per account; instant key revocation; per-key rate limits.
- Embed URLs are HMAC-signed, bound to a single video and expire after 1 hour.
- Webhooks only go to public https endpoints and are signed with your own secret.
- Every API call, key change, payment and admin action is logged to your account's audit trail.
- Content rules: no misleading, harmful or rights-infringing content; you are responsible for what you publish.
Pricing
Monthly plans for partners. 1 credit = 10 seconds of finished video (research, script, footage and first voice-over included).
- 1,200 credits per month
- Videos up to 90 s
- 30 requests/min per key
- 2 secret keys
- "Made with Cexi" on the player
- 4,000 credits per month
- Videos up to 120 s
- 120 requests/min per key
- 5 secret keys
- White-label embed player
- 12,000 credits per month
- Videos up to 120 s
- 300 requests/min per key
- 20 secret keys
- White-label embed player
Approved partners get trial credits to build and test before choosing a plan.
Developer FAQ
- Can I call the API from my iOS or Android app?
- Call it from your backend and pass the embed_url (or the JSON) to your app. Secret keys must never be shipped inside an app.
- Do I get an MP4 file from the API?
- Today the MP4 is rendered in the viewer's browser through the embed player (fast and free of render queues). You also get the full script, media and audio as JSON if you want to build your own renderer.
- How long does a video take?
- Most 30–60 second videos are ready in under a minute. Use the webhook instead of tight polling.
- Which languages are supported?
- English, Turkish, German, Spanish and Arabic for both the script and the voice-over.
- What happens if generation fails?
- The video becomes failed, the credits are refunded automatically and we send video.failed.
Ready to build?
Apply in two minutes. We'll email your partner code once approved.
Apply for API access