Centrum pomocy / API i webhooki

API i webhooki

Twórz reklamy ze swojej własnej aplikacji i otrzymuj powiadomienia, gdy będą gotowe, dzięki podpisanym webhookom.

Pełne omówienie wszystkich pól znajdziesz w dokumentacji API. Dokumentacja API

Klucze API

Właściciele i administratorzy tworzą klucze w sekcji Deweloperzy. Klucz jest pokazywany tylko raz: zapisz go w tajnych ustawieniach aplikacji, nigdy w kodzie, który działa w przeglądarce. Ady stworzone z użyciem klucza są liczone do planu workspace, tak samo jak ady stworzone w aplikacji.

Authorization: Bearer rl_live_…

Utwórz ad

Wyślij brief, opcjonalnie z marką, materiałami i formatami. Odpowiedź zawiera identyfikator zadania; Ad jest tworzony w tle.

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"
  }'

Dodaj "draft": true, aby najpierw dostać storyboard, oraz "variants": 3, aby uzyskać kilka storyboardów z różnymi koncepcjami. Wyrenderuj wersję roboczą później przez POST /v1/jobs/{id}/render.

Status i pobieranie

GET /v1/jobs/{id} zwraca status (queued, potem etapy przetwarzania, a następnie done, draft lub failed) oraz, gdy gotowe, podpisane linki do pobrania dla każdego formatu i miniaturę. Linki są tymczasowe: ponownie pobierz job, aby dostać nowe linki.

Webhooks

Za pomocą webhook_url wysyłamy POST na Twój adres, gdy reklama jest gotowa, nie uda się lub storyboard jest gotowy. Zdarzenie znajduje się w nagłówku X-Reelamo-Event, a treść to: job.done, job.failed lub job.draft. Treść zawiera ten sam obiekt job co punkt końcowy statusu, plus unikalne delivery_id.

• Adres musi być publicznie dostępny; adresy wewnętrzne i prywatne są odrzucane. Użyj https.
• Odpowiedz kodem 2xx w ciągu 15 sekund. Właściwą pracę wykonaj po odpowiedzi.
• Jeśli dostarczenie się nie powiedzie, ponawiamy próbę po 10 sekundach, 1 minucie, 5 minutach i 30 minutach. Przekierowania nie są śledzone.
• Dostawa może czasem dotrzeć dwa razy: użyj delivery_id albo ID zadania, aby zignorować duplikaty.

Weryfikowanie podpisów

Każdy webhook jest podpisany sekretem webhooka Twojego workspace'u (w sekcji Deweloperzy). Nagłówek X-Reelamo-Signature wygląda tak: t=1760000000,v1=… gdzie v1 to HMAC-SHA256 z czasu, kropki i surowego body. Sprawdź go, zanim zaufasz treści, i odrzucaj stare znaczniki czasu:

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

Limity i dobre praktyki

• Twój plan określa, ile reklam można tworzyć jednocześnie i jak długie mogą być; żądania przekraczające limit zwracają błąd z jasnym komunikatem (na przykład status 402, gdy wyczerpano miesięczne reklamy, lub 429, gdy zbyt wiele reklam jest tworzonych jednocześnie).
• Wyślij nagłówek Idempotency-Key z POST /v1/jobs, aby bezpiecznie ponowić żądanie bez tworzenia drugiego Ad.
• Od razu obróć klucz albo sekret webhooka, jeśli mógł wyciec.