Ohjekeskus / API ja webhookit

API ja webhookit

Luo mainoksia omasta sovelluksestasi ja saat ilmoituksen, kun ne ovat valmiit, allekirjoitetuilla webhookeilla.

Täydellinen viite, jossa on kaikki kentät, löytyy API-dokumentaatiosta. API-dokumentaatio

API-avaimet

Omistajat ja ylläpitäjät luovat avaimet Kehittäjät-osion alla. Avain näytetään vain kerran: tallenna se sovelluksesi salaisiin asetuksiin, älä koskaan selaimessa ajettavaan koodiin. Avaimella tehdyt adit lasketaan työtilasi planiin aivan kuten sovelluksessa tehdyt adit.

Authorization: Bearer rl_live_…

Luo ad

Lähetä brief, halutessasi brändin, median ja formaattien kanssa. Vastaus sisältää job ID:n; ad tehdään taustalla.

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

Lisää "draft": true saadaksesi ensin storyboardin, ja "variants": 3 saadaksesi useita storyboardeja eri konsepteilla. Renderöi draft myöhemmin komennolla POST /v1/jobs/{id}/render.

Tila ja lataukset

GET /v1/jobs/{id} palauttaa tilan (jonossa, sitten käsittelyvaiheet, sitten valmis, draft tai failed) ja valmiina allekirjoitetut latauslinkit kullekin muodolle sekä pikkukuvan. Linkit ovat tilapäisiä: pyydä työ uudelleen saadaksesi uudet linkit.

Webhookit

Kun käytössä on webhook_url, lähetämme POST-pyynnön osoitteeseesi, kun ad on valmis, epäonnistuu tai storyboard on valmis. Tapahtuma on X-Reelamo-Event-otsakkeessa ja rungossa: job.done, job.failed tai job.draft. Runko sisältää saman job-objektin kuin status-endpoint, sekä yksilöllisen delivery_id:n.

• Osoitteen on oltava julkisesti tavoitettavissa; sisäiset ja yksityiset verkko-osoitteet estetään. Käytä https-yhteyttä.
• Vastaa 2xx-tilakoodilla 15 sekunnin kuluessa. Tee varsinainen työ vastauksen jälkeen.
• Jos toimitus epäonnistuu, yritämme uudelleen 10 sekunnin, 1 minuutin, 5 minuutin ja 30 minuutin kuluttua. Uudelleenohjauksia ei seurata.
• Toimitus voi joskus saapua kahdesti: käytä delivery_id:tä tai työn ID:tä kaksoiskappaleiden ohittamiseen.

Allekirjoitusten tarkistaminen

Jokainen webhook allekirjoitetaan työtilasi webhook-salaisuuden avulla (kohdassa Kehittäjät). X-Reelamo-Signature-otsake näyttää tältä t=1760000000,v1=… missä v1 on HMAC-SHA256 aikaleimasta, pisteestä ja raakasisällöstä. Tarkista se ennen kuin luotat sisältöön, ja hylkää vanhat aikaleimat:

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

Rajat ja hyvät käytännöt

• Tilauksesi määrittää, kuinka monta ad:ia voidaan tehdä samanaikaisesti ja kuinka pitkiä ne voivat olla; rajoitusten ylittävät pyynnöt palauttavat virheen selkeällä viestillä (esimerkiksi status 402, kun kuukausittaiset ad:it on käytetty, tai 429, kun liian monta ad:ia on tekeillä yhtä aikaa).
• Lähetä Idempotency-Key-otsake POST /v1/jobs -pyynnön mukana, jotta voit yrittää pyyntöä turvallisesti uudelleen ilman, että luot toista adia.
• Kierrätä avain tai webhook-salaisuus heti, jos se on voinut vuotaa.