Media

Übergibt fertige Bild und Video-Assets per URL an Meta und liefert die Referenz (image_hash bzw. video_id) für Creatives. Wir komprimieren NICHT und speichern die Datei nicht. Der Kunde ist für Format, Größe, Kompression und Versionierung selbst zuständig und übergibt nur die finale, öffentlich erreichbare URL.

Verfügbar

POST

/v1/media/images

Übergibt ein Bild per öffentlich erreichbarer URL. Unser Server lädt die Datei von der URL und reicht die Bytes UNVERÄNDERT (keine Kompression) an Meta weiter; zurück kommt ein image_hash für Creatives. Synchron. Die URL wird serverseitig validiert (nur https, keine internen Ziele, keine Weiterleitungen).

Body-Parameter

Name	Typ	Pflicht	Beschreibung
url	string (https URL)	erforderlich	Direkte, öffentlich erreichbare https-URL zur fertigen Bilddatei (JPG/PNG/WebP, ≤ 30 MB). Wenn ihr das von uns aufgesetzte Supabase nutzt: signierte URL via supabase.storage.from(bucket).createSignedUrl(path, 3600) erzeugen. Ohne Supabase: jede öffentlich erreichbare https-URL (CDN, S3 Presigned-URL o. ä.). Sie muss von unserem Backend abrufbar sein und darf NICHT weiterleiten. `z. B. https://<projekt>.supabase.co/storage/v1/object/sign/media/headliner.jpg?token=…`

Request · Next.js

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/media/images`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      url: "https://<projekt>.supabase.co/storage/v1/object/sign/media/headliner.jpg?token=…",
    }),
});
const data = await res.json();

Response 200

{
  "data": { "id": "b3f1…", "image_hash": "a1b2c3d4e5f6", "url": "https://…fbcdn.net/…" },
  "request_id": "…"
}

Richtlinien: JPG/PNG/WebP, ≤ 30 MB, empfohlen ≥ 1080 px Kantenlänge. Seitenverhältnis je Platzierung (1:1, 4:5, 9:16, 1.91:1). Komprimierung macht der Kunde.

GET

/v1/media/images

Listet die Ad-Images des Werbekontos direkt aus Meta (hash, Vorschau-URL, Maße, Name, Erstellzeit). Da Konto und Kunde 1:1 zugeordnet sind, ist das die komplette Bild-Mediathek des Kunden. Optional per hash auf ein einzelnes Bild gefiltert.

Query-Parameter

Name	Typ	Pflicht	Beschreibung
hash	string	optional	Auf einen einzelnen image_hash filtern. `z. B. a1b2c3d4e5f6`

Request · Next.js

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

Response 200

{
  "data": [
    { "image_hash": "a1b2c3d4e5f6", "url": "https://…fbcdn.net/…", "width": 1080, "height": 1080, "name": "headliner.jpg", "created_time": "2026-06-15T12:00:00+0000" }
  ],
  "request_id": "…"
}

Reporting-Scope genügt. Quelle ist Meta live (zeigt auch extern angelegte Bilder).

POST

/v1/media/videos

Übergibt ein Video per öffentlich erreichbarer URL. Anders als beim Bild lädt META die Datei selbst von der URL (file_url) — die Bytes laufen nie durch uns, daher sind große bis 4K-Videos möglich. Zurück kommt die video_id und ein Status. Die Verarbeitung bei Meta ist asynchron: über GET /v1/media/videos/{id} pollen, bis READY, bevor das Video in einem Creative genutzt wird.

Body-Parameter

Name	Typ	Pflicht	Beschreibung
url	string (https URL)	erforderlich	Direkte, öffentlich erreichbare https-URL zum fertigen Video (MP4/MOV). Wenn ihr das von uns aufgesetzte Supabase nutzt: signierte URL via supabase.storage.from(bucket).createSignedUrl(path, 3600) erzeugen (Gültigkeit ≥ 1 h, da Meta sie abruft). Ohne Supabase: jede öffentlich erreichbare https-URL (CDN, S3 Presigned-URL o. ä.). Sie muss von Metas Servern abrufbar sein. `z. B. https://<projekt>.supabase.co/storage/v1/object/sign/media/teaser.mp4?token=…`

Request · Next.js

const res = await fetch(`https://api.campaignkit.ventureon.io/v1/media/videos`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      url: "https://<projekt>.supabase.co/storage/v1/object/sign/media/teaser.mp4?token=…",
    }),
});
const data = await res.json();

Response 200

{
  "data": { "id": "b3f1…", "video_id": "239847562018", "status": "PROCESSING" },
  "request_id": "…"
}

Richtlinien: MP4/MOV, H.264 + AAC, ≤ 4 GB. Seitenverhältnis 1:1, 4:5, 9:16 oder 16:9. Async: über GET /v1/media/videos/{id} pollen, bis status=READY.

GET

/v1/media/videos

Listet die Ad-Videos des Werbekontos direkt aus Meta (video_id, Titel, Status, Länge, Erstellzeit). Da Konto und Kunde 1:1 zugeordnet sind, ist das die komplette Video-Mediathek des Kunden.

Request · Next.js

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

Response 200

{
  "data": [
    { "video_id": "239847562018", "title": "Teaser", "status": "READY", "length": 15, "created_time": "2026-06-15T12:00:00+0000" }
  ],
  "request_id": "…"
}

Reporting-Scope genügt. Quelle ist Meta live (zeigt auch extern angelegte Videos).

GET

/v1/media/videos/{id}

Liefert den aktuellen Verarbeitungsstatus eines Videos: PROCESSING (Meta transkodiert noch), READY (nutzbar im Creative) oder FAILED (Verarbeitung fehlgeschlagen). {id} ist die interne ID aus POST /v1/media/videos.

Path-Parameter

Name	Typ	Pflicht	Beschreibung
id	string (UUID)	erforderlich	Interne Video-Asset-ID aus POST /v1/media/videos.

Request · Next.js

const id = "…";

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

Response 200

{
  "data": { "id": "b3f1…", "video_id": "239847562018", "status": "READY", "processed_at": "2026-06-15T12:00:00Z" },
  "request_id": "…"
}

Reporting-Scope genügt. PROCESSING heißt: erneut pollen.