Televizyon.app Arşiv API

Kimlik doğrulama

Tüm uç noktalar bir API token'ı ister. Token'ı her istekte Authorization başlığında gönderin:

Authorization: Bearer tv2t_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Token'lar tv2t_ ile başlar ve oluşturulduklarında yalnızca bir kez gösterilir. İptal edilen token anında geçersiz olur. Token'ı adres satırına (URL) koymayın; yalnızca başlıkta gönderin.

Zaman, sayfalama, sınırlar

Zaman biçimi

Tüm zamanlar ISO 8601'dir. Yanıtlar UTC döner (+00:00). Sorgularda saat dilimi belirtebilirsiniz; Türkiye saati için +03:00 kullanın. URL içinde + işareti %2B olarak yazılmalıdır:

from=2026-10-09T09:00:00%2B03:00&to=2026-10-09T12:00:00%2B03:00

Sayfalama

Liste döndüren uç noktalar next_cursor verir. Sonraki sayfa için aynı isteği cursor=<next_cursor> ekleyerek tekrarlayın. next_cursor değeri null ise başka sonuç yoktur. İmleçli sayfalama, sayfa numarasıyla sayfalamadan farklı olarak, derin sayfalarda da yavaşlamaz.

İstek sınırı

Token başına saniyede 20 istek (anlık 60'a kadar). Aşılırsa 429 döner; kısa bir süre bekleyip tekrar deneyin.

Arama nasıl çalışır

• Büyük-küçük harf ve noktalama önemsizdir. Türkçe harfler doğru işlenir (İ/i, I/ı).
• 5 ve daha uzun kelimeler ekleri yakalar: istanbul → İstanbul'da, İstanbul'un, İstanbullu…
• Daha kısa kelimeler tam eşleşir (kesmeli ekler dahil): rize → Rize, Rize'de; ama “rizeli” değil.
• Birden çok kelime (mode=word): hepsi aynı segmentte geçmeli, sıra önemsiz.
• Yakın (mode=near): kelimeler aynı kanalda 60 sn içinde geçmeli (farklı cümlelerde olabilir): başarı ödül.
• Operatörler (word ve near): festival VEYA konser (ya da OR, |) biri yeter · konser -yağmur (ya da DEĞİL, NOT) geçmesin · "iyi haberler" tırnak içi yan yana. Yalnızca -kelime ile arama yapılamaz.
• Konuşmacı: konuşan:ad başarı (ad: panelde tanıtılan kişi) yalnızca o kişinin kendi sesiyle söylediği cümleler (ses tanıma; kişiler yönetim panelinde tanıtılır, bkz. /speakers). Tek başına konuşan:ad kişinin son konuşmalarını listeler. Ad, kayıtlı adın bir parçası olabilir; boşluklu ad tırnakla: konuşan:"ad soyad". kişi: da olur.
• Yan yana ifade (mode=phrase): kelimeler bu sırayla, art arda geçmeli: “merkez bankası”.
• Benzer yazım (mode=fuzzy): konuşma tanıma bazen kelimeyi yanlış yazar (“kpss” → “kfss”). Bu mod benzer yazılışları da bulur; sonuçlar daha geniştir, gözden geçirerek kullanın.

Bir segment, genellikle 2–15 saniyelik bir konuşma cümlesidir; arama sonuçları segment segment döner.

Arama

curl -H "Authorization: Bearer $TELEVIZYON_TOKEN" \
  "https://televizyon.app/api/v1/search?q=festival&from=2026-10-09T00:00:00%2B03:00&limit=20"

import os, requests

r = requests.get(
    "https://televizyon.app/api/v1/search",
    params={"q": "festival", "from": "2026-10-09T00:00:00+03:00", "limit": 20},
    headers={"Authorization": f"Bearer {os.environ['TELEVIZYON_TOKEN']}"},
    timeout=30,
)
for seg in r.json()["results"]:
    for m in seg["matches"]:
        print(m["at"], seg["channel"]["name"], m["text"])

const url = new URL("https://televizyon.app/api/v1/search");
url.searchParams.set("q", "festival");
url.searchParams.set("from", "2026-10-09T00:00:00+03:00");

const res = await fetch(url, { headers: { Authorization: `Bearer ${TELEVIZYON_TOKEN}` } });
const { results, next_cursor } = await res.json();
results.forEach(s => s.matches.forEach(m => console.log(m.at, s.channel.name, m.text)));

{
  "results": [
    {
      "id": 3919,
      "channel": { "id": "ce5c463456", "name": "Bloomberg HT" },
      "started_at": "2026-10-09T14:10:23.511287+00:00",
      "ended_at": "2026-10-09T14:10:38.751287+00:00",
      "lang": "tr",
      "engine": "whisper",
      "text": "… bu yıl festivale geçen yıldan çok daha fazla ziyaretçi geldi, biletler günler önce tükendi …",
      "speaker": null,
      "matches": [
        { "keyword": "festival", "text": "festivale",
          "at": "2026-10-09T14:10:30.951287+00:00", "kind": "exact" }
      ]
    }
  ],
  "next_cursor": "MTc5MTU1NDkzMi40OTIxMTg6MzI0NQ=="
}

Sonuç alanları

Döküm

curl -H "Authorization: Bearer $TELEVIZYON_TOKEN" \
  "https://televizyon.app/api/v1/transcripts?channel=ce5c463456&from=2026-10-09T17:00:00%2B03:00&to=2026-10-09T18:00:00%2B03:00"

# Bir saatlik dökümün tamamı (sayfa sayfa)
params = {"channel": "ce5c463456", "from": "2026-10-09T17:00:00+03:00",
          "to": "2026-10-09T18:00:00+03:00", "limit": 1000}
segments = []
while True:
    page = requests.get("https://televizyon.app/api/v1/transcripts", params=params, headers=H).json()
    segments += page["results"]
    if not page["next_cursor"]:
        break
    params["cursor"] = page["next_cursor"]

include_words=true ile her segmentte ek olarak:

"words": [ { "w": "sandıkta", "at": "2026-10-09T09:32:48.535+00:00" },
           { "w": "da",       "at": "2026-10-09T09:32:49.955+00:00" }, … ]

Zaman çizelgesi

{
  "bucket": "hour",
  "from": "2026-10-08T14:13:57+00:00", "to": "2026-10-09T14:13:57+00:00",
  "series": [
    { "channel": { "id": "d50469f334", "name": "CNBC-e" },       "at": "2026-10-09T14:00:00+00:00", "count": 4 },
    { "channel": { "id": "422fffa5f6", "name": "Ekoturk" },      "at": "2026-10-09T14:00:00+00:00", "count": 2 },
    { "channel": { "id": "ce5c463456", "name": "Bloomberg HT" }, "at": "2026-10-09T14:00:00+00:00", "count": 1 }
  ]
}

Tek segment

Arama sonucundaki id ile çağrılır; yanıt arama sonucu alanlarına ek olarak words içerir. Bulunamazsa 404.

Ses

Yalnızca konuşma içeren bölümler saklanır (müzik ve sessizlik yok) ve 30 gün tutulur. Bir arama sonucundaki eşleşmenin at değerinin birkaç saniye öncesinden istemek, kelimenin söylendiği anı verir.

Yanıt bir ses dosyasıdır. X-Clip-Start başlığı dosyanın ilk örneğinin yayın saatini verir; aralıkta kesinti varsa ses ilk kesintide biter. Ses yoksa 404.

curl -H "Authorization: Bearer $TOKEN" -D - -o an.ogg \
  "https://televizyon.app/api/v1/audio?channel=c651476ffd&from=2026-10-09T21:30:00%2B03:00&to=2026-10-09T21:31:00%2B03:00"

Görüntü

Görüntü yalnızca görüntü arşivindeki kanallar için vardır; hangi kanalın hangi aralıkta görüntüsü olduğu /channels yanıtındaki video alanında, tek tek sonuçlar için video: true ile görülür. Görüntü dökümle sesten hizalanır: from/to döküm ve /audio ile aynı saattir.

Yanıt 360p H.264/AAC bir MP4 dosyasıdır (10 dk ≈ 25–30 MB). Kesit istek anında üretilir (10 dk ≈ 30 sn); aynı anda en çok 2 kesit üretilir, diğerleri sırada bekler. X-Clip-Start başlığı ilk karenin yayın saatini verir; aralıkta görüntü kesintisi varsa kesit ilk kesintide biter. Görüntü yoksa 404.

curl -H "Authorization: Bearer $TOKEN" -D - -o an.mp4 \
  "https://televizyon.app/api/v1/video?channel=c651476ffd&from=2026-10-09T21:30:00%2B03:00&to=2026-10-09T21:31:00%2B03:00"

Kanallar

{
  "id": "04908db814", "name": "24 TV", "logo": "https://i.imgur.com/8FO41es.png",
  "group": "News", "lang": "tr", "stream_status": "ok", "archived": true,
  "archive": { "state": "ok", "engine": "whisper", "lang": "tr", "lag_s": 11.6,
               "queue_s": 0.0, "last_text_at": "2026-10-09T14:13:48.841+00:00", "error": null }
}

Konuşmacılar

Her cümlenin ses izi çıkarılır ve yönetim panelinde tanıtılan kişilerin örnekleriyle karşılaştırılır. Tanınan kişi sonuçlarda speaker alanında döner; aramada konuşan:ad ya da speaker= ile süzülür. Ses izlerinin kendisi API'den verilmez. Çok kısa (2 sn altı), müzikli ya da üst üste konuşmalı cümlelerde tanıma zayıflar; tercüme edilen konuşmalarda duyulan ses tercümanınkidir.

[
  { "id": 1, "name": "Ad Soyad", "segments": 4210, "last_heard_at": "2026-10-14T11:29:12+00:00" }
]

Hata kodları

Hatalar {"detail": "açıklama"} biçiminde döner.

Veri hakkında

• Gecikme: bir konuşma, yayında söylendikten genellikle 10–60 saniye sonra aranabilir hale gelir.
• Saat doğruluğu: zamanlar yayının kendi saat bilgisinden alınır. Yayın sunucusunun saati yanlışsa canlı yayın ucuna göre düzeltilir; bu bilgiyi vermeyen birkaç yayında saat birkaç saniye sapabilir.
• Dökümler otomatik konuşma tanımadır; özel isim ve kısaltmalarda yazım hataları olabilir. Kritik aramalarda mode=fuzzy ile birlikte deneyin.
• Müzik, reklam ve sessizlik kaydedilmez; konuşma tanımanın bu anlarda uydurduğu kalıplar filtrelenir.
• Kürtçe ve Zazaca kanallar ayrı bir modelle çevrilir (engine: "omni"); bu kanallarda kelime zamanları ±1–2 sn hassasiyettedir.

Uç noktaları tarayıcıdan denemek için Swagger arayüzü: sağ üstteki Authorize düğmesine token'ı girin.