ReelVideo voor developers

Van advertentie naar Reel — programmatisch. Eén REST API, één set gegevens, en een MCP-server zodat elke AI-agent (Claude, ChatGPT, of je eigen agent) dezelfde acties rechtstreeks kan uitvoeren. Alles wat hieronder staat werkt voor eigen koppelingen, voor de botenwebmanager en de kampeermanager, en voor externe partners.

1. Een sleutel aanmaken

Log in op reelvideo.nl/app en ga naar API in de menubalk (/app/api-sleutel.php). Daar maak je een sleutel aan; hij wordt één keer volledig getoond. Elke sleutel hoort bij jouw account (dezelfde advertenties/reels die je ook in de app ziet) en heeft een eigen limiet (plan).

2. Authenticatie en limieten

Stuur bij elke aanroep dezelfde header:

Authorization: Bearer rv_live_<jouw sleutel>

Limieten zijn per sleutel ingesteld (twee assen):

Startplan: 30 aanroepen/minuut, 10 reels/dag. Elk antwoord met sleutel bevat X-RateLimit-Limit en X-RateLimit-Remaining; het volledige verbruik staat in GET /account. Hoger plan nodig? Mail info@arimpex.nl.

3. REST API

Basis-URL: https://reelvideo.nl/api/v1/. Alles JSON (UTF-8), ook de POST-bodies, maximaal 256 KB per aanroep. Antwoorden: {"ok":true,"data":…} of {"ok":false,"error":{"code":…,"message":…}}.

GET /status zonder sleutel

Gezondheid van de dienst: api, worker (ok/vertraagd), lengte van de wachtrij.

GET /pricing zonder sleutel

De prijsstaffel per reel. Zolang de prijzen nog niet gepubliceerd zijn: {"gepubliceerd": false}.

GET /templates

Beschikbare stijlen: id, naam, omschrijving, voorbeeld (plaatje), aanbevolen_muziek. Nu: bold, cinematic, clean, editorial, marketplace, advertentiereel.

GET /music

Rechtenvrije muziek: alleen nummers onder CC0 (publiek domein), commercieel bruikbaar en zonder naamsvermelding, zodat de reel zonder credit gepost kan worden. Met voorbeeld (mp3) om te beluisteren.

GET /voices

Nederlandse stemmen voor een optionele voice-over: id, naam, taal, geslacht, omschrijving en voorbeeld (mp3) om te beluisteren. Nu: eric (standaard), man1 t/m man4, vrouw1 t/m vrouw3.

GET /account

Accountnaam, plan en huidig verbruik/limieten.

GET /listings ?limit=1-300 · GET /listings/{id}

Je advertenties (voertuigen/boten), nieuwste eerst; verwijderde advertenties staan niet in de lijst.

POST /listings

Maakt een advertentie aan of werkt hem bij, op jouw eigen ref (uniek kenmerk in je eigen systeem, bv. het voorraadnummer of de advertentie-ID uit Botenwebmanager/Kampeermanager). Nodig vóórdat je een reel aanvraagt.

curl -X POST https://reelvideo.nl/api/v1/listings \
  -H "Authorization: Bearer rv_live_…" -H "Content-Type: application/json" \
  -d '{
    "ref": "bwm-40213",
    "titel": "Bavaria C42", "merk": "Bavaria", "model": "C42",
    "bouwjaar": "2019", "prijs": 189000, "categorie": "zeiljacht",
    "deeplink": "https://voorbeeld-dealer.nl/aanbod/bavaria-c42-40213",
    "fotos": ["https://…/1.jpg", "https://…/2.jpg", "https://…/3.jpg"],
    "specs": [["Lengte","12,60 m"],["Bouwjaar","2019"]],
    "verkoper": {"naam": "Voorbeeld Jachtmakelaar", "website": "voorbeeld-dealer.nl"}
  }'

We downloaden de foto's zelf zodra de reel gemaakt wordt; je hoeft niets te uploaden. Foto's moeten dus openbaar bereikbaar blijven tot de reel klaar is.

DELETE /listings/{id}

Haalt een advertentie uit je account (bv. verkocht). Bestaande reels blijven bereikbaar; een reel die nog in de wachtrij stond wordt geannuleerd. Een nieuwe POST /listings met dezelfde ref zet hem weer terug.

POST /reels

curl -X POST https://reelvideo.nl/api/v1/reels \
  -H "Authorization: Bearer rv_live_…" -H "Content-Type: application/json" \
  -d '{"ref": "bwm-40213", "sjabloon": "advertentiereel", "muziek": "fp_midnightgreenhouse"}'

curl -X POST https://reelvideo.nl/api/v1/reels \
  -H "Authorization: Bearer rv_live_…" -H "Content-Type: application/json" \
  -d '{"ref": "bwm-40213", "muziek": "fp_midnightgreenhouse", "voiceover": true, "stem": "vrouw2"}'

Geef listing_id óf ref op. sjabloon (standaard bold) en muziek (standaard geen) zijn optioneel; een onbekende waarde geeft 422 met de geldige keuzes. voiceover (true/false, standaard false) voegt een Nederlandse voice-over toe met de titel, de eerste specs en de verkoper; de muziek zakt dan weg onder de stem. stem kies je uit GET /voices (standaard eric) en zet de voice-over vanzelf aan. Een voice-over maakt het renderen 3-7 minuten langer. Reageert direct met status: "wachtrij"; het maken is asynchroon.

GET /reels ?limit=1-300 ?ref= · GET /reels/{id}

Met ?ref= krijg je alleen de reels van die ene advertentie (handig als je zelf geen reel-id's opslaat). Poll GET /reels/{id} elke 30-60 seconden. Statussen:

De video_url is een vaste, niet te raden link die je direct kunt downloaden of doorplaatsen.

Met voice-over geeft voiceover_toegepast aan of de stem erin zit (true zodra de reel klaar is; null zolang hij nog gemaakt wordt). Mislukt het inspreken, dan krijg je de reel toch, zonder stem: status: "klaar", voiceover_toegepast: false en waarschuwing: "Voice-over mislukt, reel zonder stem gemaakt". Zonder voice-over is voiceover_toegepast false en waarschuwing null.

Foutcodes

4. MCP: voor AI-agents

ReelVideo is ook een MCP-server, zodat een AI-agent (Claude, ChatGPT, of je eigen agent-framework) dezelfde acties rechtstreeks kan uitvoeren zonder dat je zelf een integratie bouwt. Dezelfde kern, regels en limieten als de REST API.

Server-URL: https://reelvideo.nl/mcp
Transport:  Streamable HTTP (JSON-RPC 2.0 over POST, stateless; antwoorden zijn gewoon JSON, geen SSE)
Protocol:   2025-06-18 (ook 2025-03-26 en 2024-11-05)
Header:     Authorization: Bearer rv_live_…
Ontdekking: https://reelvideo.nl/.well-known/mcp.json

initialize, tools/list en get_pricing werken zonder sleutel, zodat een agent eerst kan zien wat er kan. Fouten in een tool komen terug als resultaat met isError: true en een tekst die begint met de foutcode (validatie, niet_gevonden, al_in_wachtrij, rate_limit). Een ontbrekende of ongeldige sleutel geeft HTTP 401 met JSON-RPC-fout -32001; een limiet HTTP 429 met -32002 en Retry-After.

Typische gang: upsert_listing → create_reel → get_reel herhalen tot klaar → video_url gebruiken.

In Claude (of een andere cliënt met remote-MCP-ondersteuning): voeg een custom connector toe met bovenstaande URL en zet de Authorization-header in de connector-instellingen.

5. Wat de sleutel wel en niet kan

• Een sleutel ziet en beheert uitsluitend de advertenties en reels van het account waar hij bij hoort; geen toegang tot andere accounts.
• Er is geen aparte schrijf- en leessleutel: elke sleutel mag alles binnen zijn eigen account. Intrekken kan direct op /app/api-sleutel.php.
• Reels die worden afgekeurd (ongeschikte foto's) zijn geen storing, maar tellen wel mee voor de daglimiet.
• Foto-URL's moeten openbaar op internet staan; interne adressen en andere protocollen dan http(s) worden geweigerd.

6. Prijzen

De actuele staffel staat op GET /api/v1/pricing (MCP: get_pricing). Zolang daar gepubliceerd: false staat, mail info@arimpex.nl voor de voorwaarden.