Cexi API · Partners

Put an AI video studio inside your product

One request turns a topic or a link into a researched script, matching footage and a natural voice-over. Show it in your site or app with a signed player, or build your own experience from the JSON.

  1. 01

    Apply

    Tell us what you'll build and where (web, iOS, Android, server). We review every application.

  2. 02

    Get your partner code

    Approved partners receive a code (CXP-XXXX-XXXX) by email and activate the portal with it.

  3. 03

    Create a secret key

    Pick a plan, create a key in the portal and keep it on your server.

  4. 04

    Generate and embed

    POST a topic, receive a webhook when it's ready, open the embed URL in your site or app.

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.

MethodPathDescription
POST/api/v1/videosStart a new video from a topic or a link. Returns 202 with status "generating".
GET/api/v1/videos/:idGet a video: status, script, scenes, media, audio and a 1-hour embed_url once ready.
GET/api/v1/videosList your videos, newest first (limit, before).
POST/api/v1/videos/:id/embedCreate a fresh signed embed_url for a ready video (valid for 1 hour).
GET/api/v1/videos/:id/audioDownload the voice-over (audio/mpeg).
GET/api/v1/templatesList the visual templates (id, name, category).
GET/api/v1/voicesList available AI voices.
GET/api/v1/accountYour 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.

FieldTypeDescription
topicstring, requiredWhat the video is about (3–4,000 characters). You can include up to 3 links; Cexi reads them as sources.
languagestringen (default), tr, de, es or ar — script and voice language.
duration_secnumber30, 45, 60 (default), 90 or 120 — limited by your plan.
template_idstringVisual template, see GET /api/v1/templates. Default: klasik.
tonestringsamimi (friendly, default), bilgilendirici (informative), enerjik (energetic), hikaye (storytelling), mitkirici (myth-busting) or esprili (witty).
voice_idstringA voice from GET /api/v1/voices. Default: the studio's default voice.
external_refstringYour 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.

FieldTypeDescription
idstringvid_… identifier.
statusstringgenerating → ready, or failed (credits refunded).
title, topic, language, duration_sec, template_id, voice_idWhat was produced.
external_refstring | nullYour reference.
credits_chargednumberCredits used (0 after a refund).
scriptobject | nullscenes[] (id, kind, narration, on_screen, media {kind, url, thumb, source, author, author_url}), caption, hashtags, sources[].
audioobject | nullurl (GET with your key) and duration_sec.
embed_url, embed_expires_atstring | nullSigned player URL, valid for 1 hour. Request a new one any time.
created_at, updated_atstringISO 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.

EventPayload
video.readydata: id, status, title, duration_secThe video is ready; GET it for the script and a fresh embed_url.
video.faileddata: id, status, error, credits_refundedGeneration failed and the credits were refunded.
pingdata: messageSent 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" } }.

CodeHTTPMeaning
missing_api_key / invalid_api_key / revoked_api_key401Check the Authorization header or create a new key.
browser_not_allowed403Secret keys can't be used from a browser. Call from your server.
partner_inactive / partner_suspended403Activate the portal with your code, or contact us.
ip_not_allowed403The request IP isn't in your allowlist.
duration_not_in_plan403Choose a shorter duration or upgrade.
invalid_topic / invalid_duration / invalid_template / invalid_tone / invalid_json400Fix the request body.
insufficient_credits402Not enough credits. Upgrade or wait for the monthly reset.
video_not_found404Unknown id for your account.
video_not_ready / audio_not_ready409Wait for status "ready".
rate_limited429Too many requests; respect the Retry-After header.
server_error500Unexpected 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).

Starter
$99/month
  • 1,200 credits per month
  • Videos up to 90 s
  • 30 requests/min per key
  • 2 secret keys
  • "Made with Cexi" on the player
Growth
$299/month
  • 4,000 credits per month
  • Videos up to 120 s
  • 120 requests/min per key
  • 5 secret keys
  • White-label embed player
Scale
$799/month
  • 12,000 credits per month
  • Videos up to 120 s
  • 300 requests/min per key
  • 20 secret keys
  • White-label embed player
Enterprise

Higher volume, custom limits, invoicing and a dedicated contact.

Contact us →

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