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öntem | Yol | Açıklama |
|---|---|---|
| POST | /api/v1/videos | Bir konudan ya da bağlantıdan yeni video başlatır. "generating" durumuyla 202 döner. |
| GET | /api/v1/videos/:id | Videoyu getirir: durum, senaryo, sahneler, medya, ses ve hazırsa 1 saatlik embed_url. |
| GET | /api/v1/videos | Videolarını en yeniden eskiye listeler (limit, before). |
| POST | /api/v1/videos/:id/embed | Hazır video için yeni, imzalı embed_url üretir (1 saat geçerli). |
| GET | /api/v1/videos/:id/audio | Seslendirmeyi indirir (audio/mpeg). |
| GET | /api/v1/templates | Görsel şablonları listeler (id, ad, kategori). |
| GET | /api/v1/voices | Kullanılabilir yapay zekâ seslerini listeler. |
| GET | /api/v1/account | Kullanı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.
| Alan | Tür | Açıklama |
|---|---|---|
| topic | string, zorunlu | Videonun konusu (3–4.000 karakter). En fazla 3 bağlantı ekleyebilirsin; Cexi onları kaynak olarak okur. |
| language | string | en (varsayılan), tr, de, es ya da ar — senaryo ve ses dili. |
| duration_sec | number | 30, 45, 60 (varsayılan), 90 ya da 120 — paketinle sınırlı. |
| template_id | string | Görsel şablon, bkz. GET /api/v1/templates. Varsayılan: klasik. |
| tone | string | samimi (varsayılan), bilgilendirici, enerjik, hikaye, mitkirici ya da esprili. |
| voice_id | string | GET /api/v1/voices listesinden bir ses. Varsayılan: stüdyonun varsayılan sesi. |
| external_ref | string | Kendi 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.
| Alan | Tür | Açıklama |
|---|---|---|
| id | string | vid_… kimliği. |
| status | string | generating → ready ya da failed (kredi iade edilir). |
| title, topic, language, duration_sec, template_id, voice_id | Üretilen içerik. | |
| external_ref | string | null | Senin referansın. |
| credits_charged | number | Kullanılan kredi (iadeden sonra 0). |
| script | object | null | scenes[] (id, kind, narration, on_screen, media {kind, url, thumb, source, author, author_url}), caption, hashtags, sources[]. |
| audio | object | null | url (anahtarınla GET) ve duration_sec. |
| embed_url, embed_expires_at | string | null | İmzalı oynatıcı adresi, 1 saat geçerli. İstediğin zaman yenisini al. |
| created_at, updated_at | string | ISO 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.
| Event | Payload | |
|---|---|---|
| video.ready | data: id, status, title, duration_sec | Video hazır; senaryo ve yeni embed_url için GET et. |
| video.failed | data: id, status, error, credits_refunded | Üretim başarısız, kredi iade edildi. |
| ping | data: message | Portaldaki "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.
| Kod | HTTP | Anlamı |
|---|---|---|
| missing_api_key / invalid_api_key / revoked_api_key | 401 | Authorization başlığını kontrol et ya da yeni anahtar oluştur. |
| browser_not_allowed | 403 | Gizli anahtar tarayıcıdan kullanılamaz. Sunucundan çağır. |
| partner_inactive / partner_suspended | 403 | Portalı kodunla etkinleştir ya da bize yaz. |
| ip_not_allowed | 403 | İstek IP'si izin listende değil. |
| duration_not_in_plan | 403 | Daha kısa süre seç ya da paketini yükselt. |
| invalid_topic / invalid_duration / invalid_template / invalid_tone / invalid_json | 400 | İstek gövdesini düzelt. |
| insufficient_credits | 402 | Kredi yetersiz. Paketini yükselt ya da aylık yenilemeyi bekle. |
| video_not_found | 404 | Bu kimlikte video yok. |
| video_not_ready / audio_not_ready | 409 | "ready" durumunu bekle. |
| rate_limited | 429 | Çok fazla istek; Retry-After başlığına uy. |
| server_error | 500 | Beklenmeyen 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).
- Ayda 1.200 kredi
- En fazla 90 sn video
- Anahtar başına dakikada 30 istek
- 2 gizli anahtar
- Oynatıcıda "Made with Cexi"
- 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ı
- 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ı
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