İçerik moderasyon API’si nasıl entegre edilir?

Kısa cevap

Bir içerik moderasyon API’sini mevcut sisteminize hızlıca bağlamak için beş kararı önceden verin: hangi anahtarı ve izni kullanacağınızı, içeriği yayından önce mi sonra mı denetleyeceğinizi, sonucu anında mı yoksa webhook ile mi alacağınızı, görseli dosya, base64 ya da bağlantı olarak mı göndereceğinizi ve bayrak kalkınca kararı kimin vereceğini. Detectivision’da bunların her biri tek bir alanla seçilir; aşağıdaki adımlar sırayla gider.

1. Anahtar: hangi izinle?

Her istek Api-Key başlığında bir API anahtarı taşır ve yalnızca HTTPS ile çağrılır. Anahtarları panelin API Keys ekranında oluşturursunuz. Anahtarın tamamı yalnızca oluşturulduğu anda gösterilir; o anda saklayın.

Bir anahtara son kullanma tarihi de verebilirsiniz. Anahtarı sunucunuzda tutun; tarayıcıya ya da mobil uygulamanın içine koymayın.

2. İlk istek nasıl görünür?

Bir yorumu denetlemek için tek bir çağrı yeter:

curl https://api.detectivision.ai/api/v1/moderation \
  -H "Api-Key: $DETECTIVISION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text_moderation",
    "input": "Satıcı tam bir salak, ürün iki haftadır gelmedi.",
    "mode": "detect",
    "metadata": { "commentId": "c_981" }
  }'

Cevapta flagged, en az bir bayrak kalktığında true olur. flags kalkan bayrakları güven puanlarıyla, checked bakılan bayrakları, usage harcanan ve kalan krediyi verir. metadata alanına koyduğunuz yorum ya da kullanıcı numarası (en çok 16 KB) cevapta, panelde ve her webhook’ta değişmeden geri gelir; sonucu kendi kaydınıza böyle bağlarsınız.

3. Sonucu anında mı, arka planda mı almalı?

İki yol var ve ikisi aynı API’dedir:

• Anında cevap (varsayılan). İstek, kontrol bitene kadar bekler ve sonucu döner. Profil fotoğrafı gibi gösterilmeden önce karar gereken içerik için kullanın.
• Arka planda ("async": true). API hemen 202 ve isteğin numarasıyla cevap verir; kontrol kısa süre sonra yapılır ve sonuç webhook ile gelir. Arka planda yapılan kontrol, anında cevabın yarı fiyatınadır. Sohbet mesajları, yorumlar ve toplu yüklemeler için uygundur.

Bir hesapta aynı anda en çok 50 arka plan kontrolü bekleyebilir; fazlası 429 ve Retry-After başlığıyla geri döner, sonuç geldikçe yenisini gönderin. Webhook kurmadan da sonucu GET /api/v1/moderation/{id} ile sorgulayabilirsiniz.

4. Webhook’ları nasıl güvenle alırım?

Panelin Webhooks ekranında bir adres ekler ve hangi olayları alacağınızı seçersiniz. Her olay, adresin gizli anahtarıyla imzalanmış bir HTTPS POST olarak gelir; mesajlar Standard Webhooks belirtimine uyar, bu yüzden onun kütüphaneleriyle doğrulanabilir.

Her mesajın webhook-id başlığı denemeden denemeye değişmez: bir mesajı yalnızca bir kez işlemek için bunu kullanın. webhook-signature başlığındaki HMAC-SHA256 imzayı, JSON’u ayrıştırmadan önce ham gövde üzerinde doğrulayın. Beş gün boyunca her denemede başarısız olan bir adres kapanır; panelden yeniden açabilirsiniz.

5. Görseli nasıl göndermeli: dosya, base64 ya da bağlantı?

Görsel en çok 10 MB, 40 megapiksel ve kenarı 10.000 pikseldir; JPEG, PNG, WebP, BMP ve GIF kabul edilir. Video dosya olarak en çok 20 MB, bağlantıyla en çok 100 MB gider. Metin 1 ile 10.000 karakter arasıdır. Görsel indirilir, denetlenir ve saklanmaz; arka plan isteğinin görseli yalnızca kontrolü yapılana kadar bekler.

6. Bayrak kalkınca kararı kim verir?

Detectivision her içeriği bayraklarıyla cevaplar; yayınlamak, bekletmek ya da silmek, kurallarınıza göre sisteminizde uygulanır. Akışı şöyle kurun:

1. Kuralı koyun. Bir bayrak 0,5 güven puanından itibaren kalkar. İşe flagged ve bayrak adlarıyla başlayın; gerekirse her bayrak için kendi çizginizi çekin, örneğin belirsiz sonuçları bir insana gönderin.
2. Bilinmeyeni temiz saymayın. unchecked doluysa o bayraklara o anda bakılamamıştır: sonuç partial olur ve ücret alınmaz. Bu bayrakları bilinmiyor sayın, kontrolü sonra tekrarlayın.
3. Moderatörler panelden devralsın. Panelin Logs ekranı ücretlendirilen kontrolleri ve bekleyen arka plan isteklerini listeler; bir moderatör bir kontrolü açınca bayraklarını, metadata’nızı ve aksiyonlarınızı görür, her aksiyon mesajının sisteminize ulaşıp ulaşmadığını da orada izler. Onayla ya da Engelle gibi kendi aksiyonlarınızı tanımlarsınız; bir moderatör birini seçince sisteminize moderation.action webhook’u gider ve işlemi sisteminiz yapar.
4. Ya da kendi panelinizden. Aksiyonları yazma izni olan bir anahtarla POST /api/v1/moderation/{id}/actions çağrısıyla da alabilirsiniz.

7. Kodu yazmadan önce Playground’da deneyin

Panelin Playground ekranında kendi metninizi, görselinizi, videonuzu ya da canlı yayınınızı denetleyip sonucu görürsünüz. Hesabınızın bayrakları her tür için orada listelenir; seçtiğiniz bayraklar Code görünümündeki isteğe flags olarak girer ve gösterilen fiyat onlara göre değişir. Video ve Live Stream sekmelerinde takip (Tracking) anahtarını da açabilirsiniz. Playground’daki kontroller de moderation.completed webhook’unu tetikler (source: playground), böylece webhook adresinizi gerçek bir istek yazmadan deneyebilirsiniz.

8. Hangi limitlere ve hatalara hazırlanmalı?

• Dakikalık limit. Bir anahtarla ve bir adresten dakikada en çok 1.200 çağrı.
• Kredi biterse. Bir türün bakiyesi kontrolün fiyatından azsa API 400 insufficient_quota döner; hiçbir şey ücretlendirilmez. Her cevaptaki usage.remaining ile bakiyeyi izleyin.
• Büyük dosya. 10 MB’ı aşan görsel ya da 20 MB’ı aşan video dosyası 413 payload_too_large alır; büyük videoyu bağlantıyla gönderin.
• Yanlış bayrak. Hesabınızda olmayan bir bayrak 400 invalid_flags ile, ücret alınmadan reddedilir.

9. Maliyet nasıl hesaplanır?

Her içerik türünün ayrı kredisi vardır ve bir kontrol kendi türünün kredisini kullanır. Sonuç webhook ile gelirse metin başlayan her 2.500 karakter için bir kredi, görsel bir kredi, video ise denetlenen karelerin başlayan her 60’ı için bir kredi kullanır; anında cevap bunun iki katıdır. Hatalar ve kısmi sonuçlar ücretsizdir. Basic planla 10.000 metin, 10.000 görsel ve 300 video kredisi gelir ve plan iki ay ücretsizdir. Planlar ve fiyatlar fiyatlandırma sayfasında (İngilizce).

Canlı yayınlar oturumla denetlenir ve dakika üzerinden ödenir; ayrıntılar canlı yayın moderasyonu sayfasında.

10. Kodlama asistanıyla bağlamak

Bir kodlama asistanıyla çalışıyorsanız API’nin OpenAPI 3.1 tanımı /openapi.json adresindedir; asistanınız uç noktaları, alanları ve hataları oradan okuyabilir. Adım adım kurulum için hızlı başlangıç dokümanı (İngilizce) ilk istekten webhook’a kadar gider.