Zıpır API: kendi programından video ders başlat

Kısa yanıt: Zıpır API, panelin yaptığı işi kendi programına açar: anahtarını Authorization: Bearer başlığında gönderirsin, bir belgeyi ya da metni derse çevirirsin, bitmiş videonun indirme bağlantısını alırsın. Ders, paneldeki aynı hattan geçer: belge okunur, sahne planı çıkarılır ve sen panelde onaylamadan tek kare üretilmez.

Anahtar

Kendi kendine bağla. İletişime geçmene gerek yok: panelde anahtarı oluştur, kodu çalıştır. İlk video deneme dakikalarından düşer; sonrası fiyat sayfasındaki dakika paketleriyle aynı sayaçtan gider — API için ayrı ücret yok.

Panelde Hesap → API anahtarları → Anahtar oluştur.
Anahtarı sunucunda ortam değişkeni yap: ZIPIR_API_KEY.
İlk isteği gönder; sonuç JSON döner, video hazır olunca indirme bağlantısı verilir.

Panelde Hesap → API anahtarları → Anahtar oluştur. Anahtar zipir_ ile başlar ve yalnız oluşturulduğu an bir kez gösterilir; sunucuda yalnız sha256 özeti saklanır. Her istek şu başlığı taşır:

Authorization: Bearer $ZIPIR_API_KEY

Anahtarı tarayıcıya ya da istemciye gömme; sunucunda ortam değişkeni olarak tut. Bir anahtar silinince aynı saniyede çalışmayı bırakır.

Uçlar

Makine okunur şema: /openapi.json (OpenAPI 3.1). İstemciler ve araç dizinleri uçları bu dosyadan okur.

Taban adres https://api.zipirapp.com. Gövde ve yanıtlar JSON; dosya yüklemesi multipart/form-data. Bugün 12 biçim açık; listeyi GET /v1/formats verir, adları biçimler sayfasında.

Metot	Yol	Ne yapar
`GET`	`/v1/formats`	Kullanılabilir biçimler; canlı katalog.
`POST`	`/v1/lessons`	Ders başlatır: dosya, metin ya da sayfa bağlantısı. 202 ve ders kimliği.
`GET`	`/v1/lessons/{id}`	Durum, aşama, süre, hata; sahne planı onay bekliyor mu.
`DELETE`	`/v1/lessons/{id}`	Dersi durdurur ve siler.
`GET`	`/v1/lessons/{id}/download`	İmzalı indirme bağlantısı (15 dakika geçerli).
`GET`	`/v1/usage`	Bu anahtarın dönem dakikaları ve dakikada istek sınırı.

Örnekler

Biçimleri oku:

curl https://api.zipirapp.com/v1/formats \
  -H "Authorization: Bearer $ZIPIR_API_KEY"

Bir PDF'ten ders başlat. Idempotency-Key aynı isteğin tekrarını aynı derse bağlar (24 saat):

curl https://api.zipirapp.com/v1/lessons \
  -H "Authorization: Bearer $ZIPIR_API_KEY" \
  -H "Idempotency-Key: isg-2026-10-31" \
  -F "[email protected]" \
  -F "format=briefing" \
  -F "title=İSG oryantasyonu"

Metinden ya da herkese açık bir sayfadan:

curl https://api.zipirapp.com/v1/lessons \
  -H "Authorization: Bearer $ZIPIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Fotosentez, bitkilerin ışık enerjisini kimyasal enerjiye çevirdiği süreçtir."}'

curl https://api.zipirapp.com/v1/lessons \
  -H "Authorization: Bearer $ZIPIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://ornek.com.tr/rehber"}'

Durumu izle ve indirme bağlantısını al:

curl https://api.zipirapp.com/v1/lessons/DERS_KIMLIGI \
  -H "Authorization: Bearer $ZIPIR_API_KEY"

curl "https://api.zipirapp.com/v1/lessons/DERS_KIMLIGI/download?variant=720" \
  -H "Authorization: Bearer $ZIPIR_API_KEY"

Kalan dakikalar:

curl https://api.zipirapp.com/v1/usage -H "Authorization: Bearer $ZIPIR_API_KEY"

Kurallar

Her yanıtta x-request-id var. Hatalar tek biçimde: {"error":{"code","message","request_id"}}. Desteğe yazarken bu kimliği gönder.
Ders hemen başlamaz. POST /v1/lessons 202 döner; durum queued → rendering → done (ya da failed) ilerler. needs_approval: true iken sahne planı panelde onay bekliyordur; onaylanmadan kare üretilmez.
Kota 402, hız 429. Anahtarın aylık dakikası ya da hesabın kendi sınırı dolduğunda 402; dakikada istek sınırı dolduğunda 429 ve Retry-After.
İndirme bir bağlantıdır. 900 saniye geçerlidir. variant=720 her planda açık; variant=1080 Stüdyo ve Takım planlarında.
Tekrar deneme güvenli. Aynı Idempotency-Key 24 saat içinde aynı dersi döndürür; farklı gövdeyle aynı anahtar 409.
Belge 50 MB, metin 5 MB. Kişisel veri içeren belgeler için Güven sayfası geçerli: belgen yalnız videon için okunur, model eğitilmez.

Fiyat

API ayrı ücretlendirilmez; panelin planıyla çalışır: Stüdyo ₺990/ay, ayda 15 bitmiş video dakikası; Takım ₺3.490/ay, ayda 60 bitmiş video dakikası. KDV dahil. Ölçü bitmiş video dakikasıdır. Fiyat sayfası.

Örnek çıktı

Aynı hattın ürettiği videoyu Kanıt sayfasında izleyebilirsin: 6331 sayılı Kanun'un 17. maddesinden yapılmış, her cümlesi kaynağındaki satırı gösteren bir ders.