Yardım merkezi / API ve webhooks

API ve webhooks

Kendi uygulamanızdan adlar oluşturun ve imzalı webhook’larla hazır olduklarında bildirim alın.

Tüm alanları içeren tam referans API belgelerinde yer alır. API dokümanları

API anahtarları

Sahipler ve yöneticiler, anahtarları Developers altında oluşturur. Bir anahtar yalnızca bir kez gösterilir: onu uygulamanın gizli ayarlarında sakla, tarayıcıda çalışan kodun içine asla koyma. Bir anahtarla yapılan ads, uygulamada yapılan ads gibi workspace planına dahil edilir.

Authorization: Bearer rl_live_…

Ad oluştur

Bir brief gönder, isteğe bağlı olarak marka, medya ve formatlarla birlikte. Yanıt bir iş kimliği içerir; ad arka planda oluşturulur.

curl https://reelamo.com/v1/jobs \
  -H "Authorization: Bearer $REELAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Sourdough baked fresh every morning. 20% off this weekend.",
    "brand_id": "brd_…",
    "duration": 15,
    "formats": ["9x16", "1x1"],
    "webhook_url": "https://example.com/hooks/reelamo"
  }'

Önce bir storyboard almak için "draft": true ekle ve farklı konseptlere sahip birkaç storyboard için "variants": 3 kullan. Bir taslağı daha sonra POST /v1/jobs/{id}/render ile render et.

Durum ve indirmeler

GET /v1/jobs/{id} durumu döndürür (sırada, ardından işleme adımları, sonra tamamlandı, draft veya başarısız) ve işlem tamamlandığında her format için imzalı indirme bağlantılarını ve bir küçük resmi verir. Bağlantılar geçicidir: yeni bağlantılar için işi yeniden iste.

Webhooks

webhook_url ile, reklam hazır olduğunda, başarısız olduğunda veya bir storyboard hazır olduğunda adresine bir POST göndeririz. Etkinlik X-Reelamo-Event başlığında ve gövdededir: job.done, job.failed veya job.draft. Gövde, durum uç noktasındakiyle aynı job nesnesini ve ayrıca benzersiz bir delivery_id içerir.

• Adres herkese açık olarak erişilebilir olmalı; dahili ve özel ağ adresleri reddedilir. https kullanın.
• 15 saniye içinde 2xx durum koduyla yanıt ver. Asıl işi yanıttan sonra yap.
• Teslimat başarısız olursa, 10 saniye, 1 dakika, 5 dakika ve 30 dakika sonra tekrar deneriz. Yönlendirmeler izlenmez.
• Bir teslimat bazen iki kez gelebilir: kopyaları yok saymak için delivery_id veya job ID kullan.

İmzalar doğrulanıyor

Her webhook, workspace’in webhook gizli anahtarıyla (Geliştiriciler altında) imzalanır. X-Reelamo-Signature başlığı t=1760000000,v1=… gibi görünür; burada v1, zaman damgası, bir nokta ve ham gövdenin HMAC-SHA256’sıdır. İçeriğe güvenmeden önce bunu doğrula ve eski zaman damgalarını reddet:

import hashlib, hmac, time

def verify(body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts, sig = int(parts["t"]), parts["v1"]
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig) and abs(time.time() - ts) < tolerance

Sınırlamalar ve iyi uygulamalar

• Planın, aynı anda kaç ad oluşturulabileceğini ve ne kadar uzun olabileceklerini belirler; limit aşan istekler net bir mesaj içeren bir hatayla sonuçlanır (örneğin aylık ad hakların bittiğinde 402, ya da aynı anda çok fazla ad oluşturulduğunda 429).
• İsteği ikinci bir ad oluşturmadan güvenle yeniden denemek için POST /v1/jobs ile birlikte bir Idempotency-Key başlığı gönder.
• Bir anahtarı veya webhook sırrını sızmış olabileceğini düşünüyorsan hemen değiştir.