Cexi API · Partners

Ürününün içine bir yapay zekâ video stüdyosu koy

Tek istek, bir konuyu ya da bağlantıyı araştırılmış bir senaryoya, uygun görüntülere ve doğal bir seslendirmeye çevirir. İmzalı oynatıcıyla sitende ya da uygulamanda göster veya JSON'dan kendi deneyimini kur.

  1. 01

    Başvur

    Ne yapacağını ve nerede kullanacağını anlat (web, iOS, Android, sunucu). Her başvuruyu inceliyoruz.

  2. 02

    Kullanıcı kodunu al

    Onaylanan partnerlere e-postayla kod (CXP-XXXX-XXXX) gelir; portal bu kodla etkinleşir.

  3. 03

    Gizli anahtar oluştur

    Paket seç, portalda anahtar oluştur ve sunucunda sakla.

  4. 04

    Üret ve göster

    Konuyu POST et, hazır olunca webhook'u al, embed adresini sitende ya da uygulamanda aç.

Nasıl çalışır

Videolar arka planda üretilir. Sunucun POST /api/v1/videos çağırır ve hemen bir video kimliği alır. Cexi konuyu web'de araştırır, sahne sahne senaryo yazar, dikey görüntü ya da arşiv görseli seçer ve seslendirmeyi kaydeder — genellikle bir dakikadan kısa sürede.

Video hazır olunca imzalı bir webhook (video.ready) göndeririz. İstersen GET /api/v1/videos/:id ile de sorgulayabilirsin. Yanıtta senaryonun tamamı, medya adresleri, ses ve videoyu altyazılı oynatan, izleyicinin kendi tarayıcısında 1080×1920 MP4 indirmesini sağlayan imzalı bir embed_url bulunur.

Temel adres: https://cexi.app. Tüm istekler ve yanıtlar HTTPS üzerinden JSON'dur.

Kimlik doğrulama

Gizli anahtarını Authorization başlığında gönder: Authorization: Bearer cx_live_… Anahtar oluşturulurken bir kez gösterilir; biz yalnızca özetini saklarız. İptal edilen anahtar anında çalışmaz.

Gizli anahtarlar yalnızca sunucu içindir. Tarayıcıdan gelen istekler reddedilir (browser_not_allowed). Anahtarı asla mobil uygulama paketine koyma — Cexi'yi kendi sunucundan çağır, uygulamana embed adresini ver.

Kullanıcı kodun (CXP-…) hesabını etkinleştirme ve destek için tanımlar. Şifre değildir ve tek başına API çağıramaz.

Hızlı başlangıç

Video oluştur, webhook'u bekle (ya da sorgula), sonra embed_url'i aç.

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"
  }'

Uç noktalar

Tüm uç noktalar gizli anahtar ister.

YöntemYolAçıklama
POST/api/v1/videosBir konudan ya da bağlantıdan yeni video başlatır. "generating" durumuyla 202 döner.
GET/api/v1/videos/:idVideoyu getirir: durum, senaryo, sahneler, medya, ses ve hazırsa 1 saatlik embed_url.
GET/api/v1/videosVideolarını en yeniden eskiye listeler (limit, before).
POST/api/v1/videos/:id/embedHazır video için yeni, imzalı embed_url üretir (1 saat geçerli).
GET/api/v1/videos/:id/audioSeslendirmeyi indirir (audio/mpeg).
GET/api/v1/templatesGörsel şablonları listeler (id, ad, kategori).
GET/api/v1/voicesKullanılabilir yapay zekâ seslerini listeler.
GET/api/v1/accountKullanıcı kodun, paketin, kalan kredin ve sınırların.

Video oluştur

POST /api/v1/videos — kredi baştan düşülür (1 kredi = 10 saniye; 60 saniyelik video 6 kredi). Üretim başarısız olursa kredi otomatik iade edilir.

AlanTürAçıklama
topicstring, zorunluVideonun konusu (3–4.000 karakter). En fazla 3 bağlantı ekleyebilirsin; Cexi onları kaynak olarak okur.
languagestringen (varsayılan), tr, de, es ya da ar — senaryo ve ses dili.
duration_secnumber30, 45, 60 (varsayılan), 90 ya da 120 — paketinle sınırlı.
template_idstringGörsel şablon, bkz. GET /api/v1/templates. Varsayılan: klasik.
tonestringsamimi (varsayılan), bilgilendirici, enerjik, hikaye, mitkirici ya da esprili.
voice_idstringGET /api/v1/voices listesinden bir ses. Varsayılan: stüdyonun varsayılan sesi.
external_refstringKendi referansın (kullanıcı kimliği, sipariş no…); her okumada geri döner. En fazla 120 karakter.

Güvenle yeniden denemek için Idempotency-Key başlığı gönder (benzersiz herhangi bir metin): aynı anahtar her zaman aynı videoyu döndürür, iki kez ücret alınmaz.

Video nesnesi

Tüm video uç noktaları bu nesneyi döndürür.

AlanTürAçıklama
idstringvid_… kimliği.
statusstringgenerating → ready ya da failed (kredi iade edilir).
title, topic, language, duration_sec, template_id, voice_idÜretilen içerik.
external_refstring | nullSenin referansın.
credits_chargednumberKullanılan kredi (iadeden sonra 0).
scriptobject | nullscenes[] (id, kind, narration, on_screen, media {kind, url, thumb, source, author, author_url}), caption, hashtags, sources[].
audioobject | nullurl (anahtarınla GET) ve duration_sec.
embed_url, embed_expires_atstring | nullİmzalı oynatıcı adresi, 1 saat geçerli. İstediğin zaman yenisini al.
created_at, updated_atstringISO 8601 zaman damgaları.
{
  "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"
}

Oynatıcıyı göm

embed_url, senkron altyazılı tam ekran dikey bir oynatıcı ve MP4 düğmesi açar. Web'de iframe'e, iOS'ta WKWebView'a, Android'de WebView'a koy. Cexi hesabı ya da çerez gerekmez — adres imzalıdır, tek videoya bağlıdır ve bir saatte sona erer.

MP4 (1080×1920, H.264) izleyicinin tarayıcısında WebCodecs ile üretilir; render kuyruğu ve ek maliyet yoktur. Growth ve Scale paketlerinde oynatıcı beyaz etiketlidir ("Made with Cexi" yazmaz).

<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>

Oynatıcı üst pencereye mesaj gönderir: { source: "cexi", type: "play" | "pause" | "render_started" | "render_done" | "render_failed" }.

Webhook'lar

Partner portalında bir https adresi kaydet. JSON olayını POST ederiz; adresin 2xx dönmezse 3 kez yeniden deneriz. Hızlı yanıt ver, işi arka planda yap.

Her istek imzalıdır: Cexi-Signature: t=<unix saniye>,v1=<hex>. v1, imza sırrınla (whsec_…) "<t>.<ham gövde>" metninin HMAC-SHA256 değeridir. 5 dakikadan eski olayları reddet.

EventPayload
video.readydata: id, status, title, duration_secVideo hazır; senaryo ve yeni embed_url için GET et.
video.faileddata: id, status, error, credits_refundedÜretim başarısız, kredi iade edildi.
pingdata: messagePortaldaki "Test et" düğmesiyle gönderilir.

Webhook doğrulama (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 || ""));
}

Hatalar

Hatalar 2xx dışı durum ve { "error": { "code", "message" } } döndürür.

KodHTTPAnlamı
missing_api_key / invalid_api_key / revoked_api_key401Authorization başlığını kontrol et ya da yeni anahtar oluştur.
browser_not_allowed403Gizli anahtar tarayıcıdan kullanılamaz. Sunucundan çağır.
partner_inactive / partner_suspended403Portalı kodunla etkinleştir ya da bize yaz.
ip_not_allowed403İstek IP'si izin listende değil.
duration_not_in_plan403Daha kısa süre seç ya da paketini yükselt.
invalid_topic / invalid_duration / invalid_template / invalid_tone / invalid_json400İstek gövdesini düzelt.
insufficient_credits402Kredi yetersiz. Paketini yükselt ya da aylık yenilemeyi bekle.
video_not_found404Bu kimlikte video yok.
video_not_ready / audio_not_ready409"ready" durumunu bekle.
rate_limited429Çok fazla istek; Retry-After başlığına uy.
server_error500Beklenmeyen hata; aynı Idempotency-Key ile tekrar dene.

Hız sınırları ve kredi

Her anahtarın paketinden gelen dakikalık istek sınırı vardır (deneme: dakikada 10). Yanıtlarda X-RateLimit-Limit ve X-RateLimit-Remaining bulunur.

Kredi aboneliğinle her ay yenilenir ve devretmez. Partner kredisi, tüketici Cexi hesabından ayrıdır.

Güvenlik

  • Anahtarlar SHA-256 özeti olarak saklanır ve sabit zamanlı karşılaştırılır; anahtarı yalnızca bir kez görürsün.
  • Hesap başına isteğe bağlı IP izin listesi; anında anahtar iptali; anahtar başına hız sınırı.
  • Embed adresleri HMAC ile imzalıdır, tek videoya bağlıdır ve 1 saatte sona erer.
  • Webhook'lar yalnızca herkese açık https adreslerine gider ve kendi sırrınla imzalanır.
  • Her API çağrısı, anahtar değişikliği, ödeme ve yönetici işlemi hesabının denetim kaydına yazılır.
  • İçerik kuralları: yanıltıcı, zararlı ya da hak ihlali içeren içerik yok; yayımladığından sen sorumlusun.

Fiyatlar

Partnerler için aylık paketler. 1 kredi = 10 saniye bitmiş video (araştırma, senaryo, görüntü ve ilk seslendirme dahil).

Starter
$99/ay
  • Ayda 1.200 kredi
  • En fazla 90 sn video
  • Anahtar başına dakikada 30 istek
  • 2 gizli anahtar
  • Oynatıcıda "Made with Cexi"
Growth
$299/ay
  • Ayda 4.000 kredi
  • En fazla 120 sn video
  • Anahtar başına dakikada 120 istek
  • 5 gizli anahtar
  • Beyaz etiketli gömülü oynatıcı
Scale
$799/ay
  • Ayda 12.000 kredi
  • En fazla 120 sn video
  • Anahtar başına dakikada 300 istek
  • 20 gizli anahtar
  • Beyaz etiketli gömülü oynatıcı
Kurumsal

Daha yüksek hacim, özel sınırlar, faturalı ödeme ve size özel iletişim.

Bize yaz →

Onaylanan partnerler paket seçmeden önce geliştirip test etmek için deneme kredisi alır.

Geliştirici SSS

API'yi iOS ya da Android uygulamamdan çağırabilir miyim?
Kendi sunucundan çağır ve embed_url'i (ya da JSON'u) uygulamana ver. Gizli anahtar asla uygulamanın içine konmamalı.
API bana MP4 dosyası veriyor mu?
Bugün MP4, gömülü oynatıcı üzerinden izleyicinin tarayıcısında üretiliyor (hızlı, render kuyruğu yok). Kendi oluşturucunu yapmak istersen senaryo, medya ve ses JSON olarak da elinde.
Bir video ne kadar sürede hazır olur?
30–60 saniyelik videoların çoğu bir dakikadan kısa sürede hazır. Sık sorgulama yerine webhook kullan.
Hangi diller destekleniyor?
Senaryo ve seslendirme için İngilizce, Türkçe, Almanca, İspanyolca ve Arapça.
Üretim başarısız olursa ne olur?
Video failed olur, kredi otomatik iade edilir ve video.failed gönderilir.

Başlamaya hazır mısın?

İki dakikada başvur. Onaylanınca kullanıcı kodunu e-postayla göndereceğiz.

API erişimi için başvur