Developer Docs

Referenz

Templates

Zwei Wege: (1) VORLAGEN ANZEIGEN — GET /v1/templates liefert je Vorlage bereits fertige, gecachte `preview_urls` (je Format), die du unverändert direkt als Bild einbettest (img-Tag). Kein eigenes Rendern nötig, kein API-Key in der Bild-URL. (2) EIGENES CREATIVE — GET /v1/templates/{id} (Felder lesen) + POST /v1/templates/render (eigene Inhalte) erzeugt ein Werbemittel für POST /v1/ads.

Verfügbar

GET

/v1/templates

Listet die Vorlagen, die deinem Account zugewiesen sind (nur aktive). Liefert je Vorlage UUID, Name, Beschreibung, `type` (`image` oder `video`) sowie `preview_urls` (je Format die URL des Vorschau-Bildes) und `has_params` (ob für diese Vorlage bereits Vorschau-Werte hinterlegt sind). Das vollständige Parameter-Schema einer Vorlage holst du über GET /v1/templates/{id}.

Query-Parameter

Name	Typ	Pflicht	Beschreibung
limit	integer	optional	Max. Anzahl (Default 25, max. 100). `z. B. 25`
offset	integer	optional	Versatz für Paginierung (Default 0). `z. B. 0`

Request · Next.js

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/templates?limit=25&offset=0`, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
    },
});
const data = await res.json();

Response 200

{
  "data": [
    {
      "id": "1f0c7a44-2d9e-4c61-b3a8-5e7f0c2a1b9d",
      "name": "Event Poster Standard",
      "description": "Klassisches Event-Poster mit Hintergrundbild, Titel, Datum und Badge.",
      "type": "image",
      "has_params": true,
      "preview_urls": {
        "1:1":  "https://api.campaignkit.ventureon.io/v1/templates/1f0c…/preview.png?ratio=1%3A1",
        "4:5":  "https://api.campaignkit.ventureon.io/v1/templates/1f0c…/preview.png?ratio=4%3A5",
        "9:16": "https://api.campaignkit.ventureon.io/v1/templates/1f0c…/preview.png?ratio=9%3A16"
      }
    }
  ],
  "request_id": "…"
}

Das Auflisten rendert NICHT. Die `preview_urls` sind signierte, öffentliche Bild-URLs (ohne API-Key), die du unverändert direkt im Frontend einbetten kannst (img-Tag). Gerendert wird erst beim ersten Abruf eines Bildes und danach gecacht, bis der Betreiber die Vorlage oder die Parameter ändert. Die Parameter pflegt der Betreiber je Kunde im Admin-Dashboard (du setzt sie nicht selbst).

GET

/v1/templates/{id}

Liefert das einheitliche Erklärungs-Schema einer zugewiesenen Vorlage: je Parameter Name, Typ, Pflicht/optional, Bezeichnung, Beschreibung (Hinweis, was inhaltlich rein gehört), Min-/Max-Zeichen und ein Beispiel. Gedacht als Vorlage/Inspiration, damit ein KI-System die Inhalte (`params` für den Render-Call) optimal erzeugt. Ist `supports_highlight: true`, unterstützt dieser Text-Parameter Wort-Hervorhebung: Wörter im Wert, die mit doppelten eckigen Klammern umschlossen werden (`[[Wort]]`), erscheinen im Creative farbig hervorgehoben. Mehrere Wörter (`[[ganz besonders]]`) werden je Wort hervorgehoben. Beispiel-Wert: `"Jetzt [[sparen]] und anmelden"`. Bei `supports_highlight: false` werden die Klammern als normaler Text dargestellt.

Path-Parameter

Name	Typ	Pflicht	Beschreibung
id	string (UUID)	erforderlich	UUID der zugewiesenen Vorlage. `z. B. 1f0c7a44-2d9e-4c61-b3a8-5e7f0c2a1b9d`

Request · Next.js

const id = "1f0c7a44-2d9e-4c61-b3a8-5e7f0c2a1b9d";

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/templates/${id}`, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
    },
});
const data = await res.json();

Response 200

{
  "data": {
    "id": "1f0c7a44-2d9e-4c61-b3a8-5e7f0c2a1b9d",
    "name": "Event Poster Standard",
    "description": "Klassisches Event-Poster …",
    "type": "image",
    "params": [
      {
        "name": "title",
        "type": "text",
        "required": true,
        "label": "Titel",
        "description": "Kurzer, prägnanter Event-Titel ohne Datum.",
        "min_chars": 3,
        "max_chars": 40,
        "example": "Summer Open Air",
        "supports_highlight": true
      },
      {
        "name": "brand_color",
        "type": "color",
        "required": false,
        "label": "Markenfarbe",
        "description": "Primärfarbe der Marke (Hex).",
        "min_chars": null,
        "max_chars": null,
        "example": "#0082fb",
        "supports_highlight": false
      }
    ]
  },
  "request_id": "…"
}

Nur dem aufrufenden Kunden zugewiesene, aktive Vorlagen sind abrufbar — sonst 404. Die Zuweisung pflegt der Betreiber im Admin-Dashboard.

GET

/v1/templates/{id}/preview

Liefert die für diese Vorlage hinterlegten Parameter-Werte (vom Betreiber je Kunde im Admin-Dashboard gepflegt) plus die `preview_urls` je Format. Sind noch keine Werte gesetzt, ist `params` ein leeres Objekt und die Vorschau nutzt die Beispiel-Werte der Vorlage.

Path-Parameter

Name	Typ	Pflicht	Beschreibung
id	string (UUID)	erforderlich	UUID der zugewiesenen Vorlage. `z. B. 1f0c7a44-2d9e-4c61-b3a8-5e7f0c2a1b9d`

Request · Next.js

const id = "1f0c7a44-2d9e-4c61-b3a8-5e7f0c2a1b9d";

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/templates/${id}/preview`, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
    },
});
const data = await res.json();

Response 200

{
  "data": {
    "template": "1f0c7a44-2d9e-4c61-b3a8-5e7f0c2a1b9d",
    "params": { "title": "Sommerfest 2026", "brand_color": "#ff0055" },
    "preview_urls": {
      "1:1":  "https://api.campaignkit.ventureon.io/v1/templates/1f0c…/preview.png?ratio=1%3A1",
      "4:5":  "https://api.campaignkit.ventureon.io/v1/templates/1f0c…/preview.png?ratio=4%3A5",
      "9:16": "https://api.campaignkit.ventureon.io/v1/templates/1f0c…/preview.png?ratio=9%3A16"
    }
  },
  "request_id": "…"
}

GET

/v1/templates/{id}/preview.png

Öffentlicher Bild-Endpunkt, direkt im Browser als Bild einbettbar (z. B. img-Tag). KEIN API-Key. autorisiert wird über die signierten Query-Parameter `c` und `k`, die in den preview_urls aus GET /v1/templates bereits enthalten sind. Du baust diese URL nicht selbst, sondern nutzt die fertige preview_url. Liefert das Bild gefüllt mit den vom Betreiber hinterlegten Parametern (sonst mit den Beispiel-Werten der Vorlage) und antwortet mit Redirect (302) auf die dauerhaft gültige Bild-URL. Performance: Das Bild wird vorab gerendert und gecacht (spätestens beim ersten Abruf). Ändern wir die Vorlage oder die hinterlegten Parameter, wird beim nächsten Abruf automatisch einmalig neu gerendert. die signierte URL bleibt unverändert gültig.

Path-Parameter

Name	Typ	Pflicht	Beschreibung
id	string (UUID)	erforderlich	UUID der zugewiesenen Vorlage. `z. B. 1f0c7a44-2d9e-4c61-b3a8-5e7f0c2a1b9d`

Query-Parameter

Name	Typ	Pflicht	Beschreibung
c	string (UUID)	erforderlich	Kunden-Kennung aus der preview_url (Teil der Signatur). Bereits in der preview_url enthalten. `z. B. c0a8…`
k	string	erforderlich	Signierter Lese-Token aus der preview_url. Bereits in der preview_url enthalten. Ohne gültigen Token: 404. `z. B. 9f2b…`
ratio	enum	optional	Format: 1:1, 4:5 oder 9:16. Default 1:1. `z. B. 4:5`

Request · Next.js

const id = "1f0c7a44-2d9e-4c61-b3a8-5e7f0c2a1b9d";

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/templates/${id}/preview.png?c=c0a8%E2%80%A6&k=9f2b%E2%80%A6&ratio=4%3A5`, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
    },
});
const data = await res.json();

Direkt einbettbar: setze die preview_url unverändert als Bildquelle in deinem Frontend (img-Tag). Der Token ist stabil und läuft nicht ab, der API-Key bleibt geheim. Der Redirect zeigt auf eine öffentliche, unratbare Bild-URL. die Bytes liefert der Storage-CDN.

POST

/v1/templates/render

Rendert eine aktive Vorlage in drei Formaten (1:1, 4:5, 9:16) und legt einen Creative-ENTWURF an. WICHTIG: Hier entsteht nur das VISUAL. Anzeigentexte (Primärer Text, Überschrift, Beschreibung), Call-to-Action, Ziel-Link und angezeigter Link gehören zur ANZEIGE und werden in POST /v1/ads gesetzt — dort wird aus diesem Entwurf das finale Meta-Creative gebaut. Die zurückgegebene `id` ist die `creative_id` für POST /v1/ads. Welche Parameter eine Vorlage erwartet, zeigt die Vorlagen-Doku (UUID eingeben).

Body-Parameter

Name	Typ	Pflicht	Beschreibung
template	string (UUID)	erforderlich	UUID der Vorlage (im Admin-Dashboard unter „Vorlagen“). Nur aktive Vorlagen werden akzeptiert. `z. B. 1f0c7a44-2d9e-4c61-b3a8-5e7f0c2a1b9d`
params	object	erforderlich	Key/Value je Vorlagen-Parameter (Inhalte des Visuals: Texte im Bild, Farben, Bild-URLs; Bild-URLs akzeptieren JPG, PNG oder WebP, ein nicht erreichbares oder ungültiges Bild wird mit einer klaren 422-Meldung abgelehnt, nicht still weggelassen). Verfügbare Keys, Typen, Pflichtfelder und Zeichengrenzen liefert GET /v1/templates/{id} (bzw. die Vorlagen-Doku unter /docs/templates?id=<uuid>). In Text-Werten kannst du einzelne Wörter mit doppelten eckigen Klammern markieren (z. B. "Jetzt [[sparen]]"); diese werden im Visual hervorgehoben, sofern die Vorlage eine Hervorhebung definiert. `z. B. {"title":"Summer [[Opening]]","brand_color":"#ff0055"}`
name	string	optional	Optionaler interner Name des Creative-Entwurfs. Default: Name der Vorlage.

Request · Next.js

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/templates/render`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      template: 1f0c7a44-2d9e-4c61-b3a8-5e7f0c2a1b9d,
      params: {"title":"Summer [[Opening]]","brand_color":"#ff0055"},
    }),
});
const data = await res.json();

Response 200

{
  "data": {
    "id": "1f0c7a44-2d9e-4c61-b3a8-5e7f0c2a1b9d",
    "template": "1f0c…",
    "type": "IMAGE",
    "formats": {
      "1:1":  "https://…/rendered-creatives/<id>/1-1.png",
      "4:5":  "https://…/rendered-creatives/<id>/4-5.png",
      "9:16": "https://…/rendered-creatives/<id>/9-16.png"
    }
  },
  "request_id": "…"
}

Die Antwort enthält die `id` (= creative_id für POST /v1/ads) und die Vorschau-Bilder je Format — aber noch KEINE `meta_creative_id`: Das finale Creative entsteht erst in POST /v1/ads (mit Texten, CTA und Link). Enthält die Vorlage einen Video-Layer, läuft das Rendern ASYNCHRON (Video-Compositing): Antwort 202 mit `type: VIDEO` und `status: PROCESSING` — danach über GET /v1/templates/render/{id} pollen, bis READY.

GET

/v1/templates/render/{id}

Liefert den Status eines asynchronen Video-Renders: PROCESSING (Compositing/Upload läuft), READY (meta_creative_id vorhanden, in POST /v1/ads nutzbar) oder FAILED. {id} ist die Creative-ID aus dem 202-Response von POST /v1/templates/render.

Path-Parameter

Name	Typ	Pflicht	Beschreibung
id	string (UUID)	erforderlich	Creative-ID aus dem 202-Response des Video-Renders.

Request · Next.js

const id = "…";

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/templates/render/${id}`, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
    },
});
const data = await res.json();

Response 200

{
  "data": { "id": "1f0c…", "status": "READY", "meta_creative_id": "120210394857", "video_id": "239847562018", "output_url": "https://…/rendered-videos/<id>/output.mp4" },
  "request_id": "…"
}

Reporting-Scope genügt. Nur für Video-Vorlagen relevant (Bild-Renders sind synchron).