salvacybersec/Youtube2Feed

Fork 0

Files

salvacybersec 9e3b792e0c docs

2025-11-13 05:43:02 +03:00

11 KiB

Raw Blame History

API Dokümantasyonu

YouTube Transcript RSS Feed API'si, YouTube kanallarının video transcript'lerini RSS/Atom feed formatında sunar.

Base URL

http://localhost:5000

Production için base URL değişebilir.

Authentication

Tüm endpoint'ler API key gerektirir.

API key'i iki şekilde gönderebilirsiniz:

1. HTTP Header (Önerilen)

X-API-Key: your_api_key_here

2. Query Parameter

?api_key=your_api_key_here

API Key Alma

API key'ler config/security.yaml dosyasından yönetilir. Yeni bir API key eklemek için:

security:
  api_keys:
    your_api_key_here:
      name: "Your API Key Name"
      rate_limit: 100  # Dakikada maksimum istek
      enabled: true

Hata Yanıtları

401 Unauthorized - API key eksik veya geçersiz:

{
  "error": "Geçersiz veya eksik API key",
  "message": "X-API-Key header veya api_key query parametresi gerekli"
}

429 Too Many Requests - Rate limit aşıldı:

{
  "error": "Rate limit aşıldı",
  "message": "Dakikada 100 istek limiti",
  "retry_after": 60
}

Rate Limiting

Her API key için dakikada maksimum istek sayısı tanımlanır. Rate limit bilgisi response header'ında döner:

X-RateLimit-Remaining: 45

Rate limit aşıldığında 429 Too Many Requests hatası döner.

Endpoints

1. RSS/Atom Feed Oluştur

YouTube kanalı için transcript feed'i oluşturur.

Endpoint: GET /

Query Parameters:

Parametre	Tip	Zorunlu	Açıklama
`api_key`	string	✅	API key (header ile de gönderilebilir)
`channel_id`	string	⚠️*	YouTube Channel ID (UC ile başlar, 24 karakter)
`channel`	string	⚠️*	Channel handle (@username veya username)
`channel_url`	string	⚠️*	Full YouTube channel URL
`format`	string	❌	Feed formatı: `Atom` (varsayılan) veya `Rss`
`max_items`	integer	❌	Maksimum transcript sayısı (varsayılan: 10, max: 100, 5'şer batch'ler halinde işlenir)

* channel_id, channel veya channel_url parametrelerinden biri zorunludur.

Örnek İstekler:

# Channel ID ile
curl -H "X-API-Key: demo_key_12345" \
  "http://localhost:5000/?channel_id=UC9h8BDcXwkhZtnqoQJ7PggA&format=Atom"

# Channel handle ile
curl -H "X-API-Key: demo_key_12345" \
  "http://localhost:5000/?channel=@tavakfi&format=Atom"

# Channel URL ile
curl -H "X-API-Key: demo_key_12345" \
  "http://localhost:5000/?channel_url=https://www.youtube.com/@tavakfi&format=Atom&max_items=50"

# Query parametresi ile API key
curl "http://localhost:5000/?channel_id=UC9h8BDcXwkhZtnqoQJ7PggA&api_key=demo_key_12345&format=Rss"

Başarılı Yanıt:

Atom Format:

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en">
  <id>UC9h8BDcXwkhZtnqoQJ7PggA</id>
  <title>YouTube Transcript Feed - UC9h8BDcXwkhZtnqoQJ7PggA</title>
  <updated>2025-01-13T00:30:36+00:00</updated>
  <link href="https://www.youtube.com/channel/UC9h8BDcXwkhZtnqoQJ7PggA"/>
  <entry>
    <id>r5KfWUv6wqQ</id>
    <title>Video Title</title>
    <content type="html">
      <p>Transcript content...</p>
    </content>
    <link href="https://www.youtube.com/watch?v=r5KfWUv6wqQ"/>
    <published>2025-01-06T14:13:57+00:00</published>
  </entry>
</feed>

RSS Format:

<?xml version='1.0' encoding='UTF-8'?>
<rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/">
  <channel>
    <title>YouTube Transcript Feed - UC9h8BDcXwkhZtnqoQJ7PggA</title>
    <link>https://www.youtube.com/channel/UC9h8BDcXwkhZtnqoQJ7PggA</link>
    <item>
      <title>Video Title</title>
      <content:encoded><![CDATA[<p>Transcript content...</p>]]></content:encoded>
      <link>https://www.youtube.com/watch?v=r5KfWUv6wqQ</link>
      <pubDate>Mon, 06 Jan 2025 14:13:57 +0000</pubDate>
    </item>
  </channel>
</rss>

Hata Yanıtları:

400 Bad Request - Geçersiz parametreler:

{
  "error": "Channel ID bulunamadı",
  "usage": {
    "channel_id": "UC... (YouTube Channel ID)",
    "channel": "@username veya username",
    "channel_url": "https://www.youtube.com/@username veya https://www.youtube.com/channel/UC...",
    "format": "Atom veya Rss (varsayılan: Atom)",
    "max_items": "Maksimum transcript sayısı (varsayılan: 10, maksimum: 100, 20'şer batch'ler halinde işlenir)"
  }
}

400 Bad Request - Geçersiz format:

{
  "error": "Geçersiz channel_id formatı",
  "message": "Channel ID UC ile başlayan 24 karakter olmalı"
}

404 Not Found - Henüz işlenmiş video yok:

{
  "error": "Henüz işlenmiş video yok",
  "channel_id": "UC9h8BDcXwkhZtnqoQJ7PggA",
  "message": "Lütfen birkaç dakika sonra tekrar deneyin"
}

500 Internal Server Error - Sunucu hatası:

{
  "error": "RSS-Bridge hatası: ...",
  "channel_id": "UC9h8BDcXwkhZtnqoQJ7PggA"
}

2. Health Check

Servisin durumunu kontrol eder. API key gerektirmez.

Endpoint: GET /health

Örnek İstek:

curl "http://localhost:5000/health"

Başarılı Yanıt:

{
  "status": "ok",
  "service": "YouTube Transcript RSS Feed"
}

HTTP Status: 200 OK

3. API Bilgileri

API hakkında bilgi döner.

Endpoint: GET /info

Örnek İstek:

curl -H "X-API-Key: demo_key_12345" "http://localhost:5000/info"

Başarılı Yanıt:

{
  "service": "YouTube Transcript RSS Feed Generator",
  "version": "1.0.0",
  "endpoints": {
    "/": "RSS Feed Generator",
    "/health": "Health Check",
    "/info": "API Info"
  },
  "usage": {
    "channel_id": "UC... (YouTube Channel ID)",
    "channel": "@username veya username",
    "channel_url": "Full YouTube channel URL",
    "format": "Atom veya Rss (varsayılan: Atom)",
    "max_items": "Maksimum transcript sayısı (varsayılan: 10, maksimum: 100, 20'şer batch'ler halinde işlenir)"
  },
  "examples": [
    "/?channel_id=UC9h8BDcXwkhZtnqoQJ7PggA&format=Atom",
    "/?channel=@tavakfi&format=Rss",
    "/?channel_url=https://www.youtube.com/@tavakfi&format=Atom&max_items=50"
  ]
}

HTTP Status: 200 OK

Response Headers

Tüm başarılı response'larda aşağıdaki header'lar bulunur:

Header	Açıklama
`X-RateLimit-Remaining`	Kalan istek sayısı
`X-Content-Type-Options`	`nosniff`
`X-Frame-Options`	`DENY`
`X-XSS-Protection`	`1; mode=block`
`Content-Type`	`application/atom+xml` veya `application/rss+xml`

Hata Kodları

HTTP Status	Açıklama
`200 OK`	İstek başarılı
`400 Bad Request`	Geçersiz parametreler
`401 Unauthorized`	API key eksik veya geçersiz
`404 Not Found`	Kaynak bulunamadı
`429 Too Many Requests`	Rate limit aşıldı
`500 Internal Server Error`	Sunucu hatası

Input Validation

Channel ID Formatı

UC ile başlamalı
Toplam 24 karakter
Alfanumerik karakterler + _ ve -

Örnek: UC9h8BDcXwkhZtnqoQJ7PggA

Channel Handle Formatı

@ ile başlayabilir veya başlamayabilir
Maksimum 30 karakter
Alfanumerik karakterler + _ ve -

Örnekler: @tavakfi, tavakfi

Channel URL Formatı

Sadece aşağıdaki formatlar kabul edilir:

https://www.youtube.com/channel/UC...
https://www.youtube.com/@username
https://youtube.com/channel/UC...
https://youtube.com/@username

max_items

Tip: Integer
Minimum: 1
Maksimum: 100
Varsayılan: 10
Batch İşleme: 5'şer batch'ler halinde işlenir (YouTube IP blocking önleme için)
Batch'ler Arası Bekleme: 60-90 saniye random bekleme (human-like behavior)
İstekler Arası Bekleme: 10-20 saniye random (blocking varsa 30-60 saniye)
Veritabanı Kaydı: Her batch işlendikten sonra hemen veritabanına kaydedilir, böylece sonraki sorgularda görülebilir

CORS

API CORS desteği sağlar. Preflight request'ler için OPTIONS metodu kullanılır.

İzin Verilen Methodlar: GET, OPTIONS

İzin Verilen Header'lar: Content-Type, X-API-Key

Örnek Kullanım Senaryoları

1. RSS Reader ile Kullanım

RSS reader uygulamanızda feed URL'si olarak kullanın:

http://your-api.com/?channel_id=UC9h8BDcXwkhZtnqoQJ7PggA&format=Rss&api_key=your_api_key

2. Programatik Kullanım (Python)

import requests

api_key = "your_api_key_here"
channel_id = "UC9h8BDcXwkhZtnqoQJ7PggA"

headers = {
    "X-API-Key": api_key
}

response = requests.get(
    f"http://localhost:5000/?channel_id={channel_id}&format=Atom",
    headers=headers
)

if response.status_code == 200:
    feed_content = response.text
    print(feed_content)
else:
    print(f"Error: {response.status_code}")
    print(response.json())

3. Programatik Kullanım (JavaScript)

const apiKey = "your_api_key_here";
const channelId = "UC9h8BDcXwkhZtnqoQJ7PggA";

fetch(`http://localhost:5000/?channel_id=${channelId}&format=Atom`, {
  headers: {
    "X-API-Key": apiKey
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.text();
  })
  .then(feedContent => {
    console.log(feedContent);
  })
  .catch(error => {
    console.error("Error:", error);
  });

4. cURL ile Test

# API key ile test
API_KEY="demo_key_12345"
CHANNEL_ID="UC9h8BDcXwkhZtnqoQJ7PggA"

curl -H "X-API-Key: $API_KEY" \
  "http://localhost:5000/?channel_id=$CHANNEL_ID&format=Atom&max_items=50"

Notlar

İlk İstek: İlk istekte transcript'ler henüz işlenmemiş olabilir. Birkaç dakika bekleyip tekrar deneyin.
Rate Limiting: Her API key için farklı rate limit tanımlanabilir. Limit aşıldığında 60 saniye beklemeniz gerekir.
Transcript İşleme:
- Transcript'ler 5'şer batch'ler halinde işlenir (YouTube IP blocking önleme için)
- Her batch işlendikten sonra veritabanına kaydedilir
- max_items parametresi ile her istekte işlenecek transcript sayısını kontrol edebilirsiniz (maksimum 100)
- Batch'ler arası 60-90 saniye random bekleme (human-like behavior)
- İstekler arası 10-20 saniye random bekleme (blocking varsa 30-60 saniye)
- Yeni videolar için birkaç dakika gecikme olabilir
Format Seçimi: Atom formatı daha modern ve önerilir. RSS formatı eski RSS reader'lar için uygundur.
API Key Güvenliği: API key'lerinizi güvenli tutun ve asla public repository'lere commit etmeyin.
Batch İşleme Örneği:
- max_items=50 isteği: 5+5+5+5+5+5+5+5+5+5 batch'ler halinde işlenir
- Her batch tamamlandığında veritabanına kaydedilir
- Batch'ler arası 60-90 saniye random bekleme
- Sonraki sorgularda tüm işlenmiş transcript'ler görülebilir
FlareSolverr Desteği:
- YouTube bot korumasını aşmak için FlareSolverr kullanılabilir
- Config dosyasında flaresolverr.url ayarlanabilir
- FlareSolverr erişilemezse otomatik olarak normal istek yapılır
- Gerçek tarayıcı (headless browser) kullanarak istekler yapılır
Gerçek Tarayıcı Header'ları:
- 7 farklı tarayıcı User-Agent'ı rotasyon ile kullanılır
- Tam tarayıcı header seti (Accept, Sec-Fetch-*, Referer, vb.)
- Her istekte random User-Agent seçilir
Detaylı Loglama:
- Tüm işlemler kategorize edilmiş loglarla takip edilir
- Timestamp'li, seviyeli log sistemi (DEBUG, INFO, WARNING, ERROR)
- Docker logları ile kolay takip

Destek

Sorularınız için GitHub Issues kullanabilirsiniz.

11 KiB Raw Blame History Unescape Escape

API Dokümantasyonu

Base URL

Authentication

1. HTTP Header (Önerilen)

2. Query Parameter

API Key Alma

Hata Yanıtları

Rate Limiting

Endpoints

1. RSS/Atom Feed Oluştur

2. Health Check

3. API Bilgileri

Response Headers

Hata Kodları

Input Validation

Channel ID Formatı

Channel Handle Formatı

Channel URL Formatı

max_items

CORS

Örnek Kullanım Senaryoları

1. RSS Reader ile Kullanım

2. Programatik Kullanım (Python)

3. Programatik Kullanım (JavaScript)

4. cURL ile Test

Notlar

Destek

11 KiB

Raw Blame History