Integrationen

Veröffentliche auf spirkz aus jedem Scheduler

Die Integrations-API lässt Scheduler von Drittanbietern — Zapier, Metricool, Buffer und ähnliche — Videos im Namen eines Creators bei spirkz einreichen. Ein hier gesendetes Video durchläuft dieselben Regeln und dieselbe Prüfwarteschlange wie eines, das in der App hochgeladen wurde.

Basis-URL: https://server.spirkz.com/api/v1/integrations

So funktioniert es

1
Der Creator erstellt einen API-Schlüssel in der spirkz-App und fügt ihn im Scheduler ein.
2
Der Scheduler ruft POST /videos auf mit einer öffentlichen videoUrl und den Details. spirkz antwortet sofort mit 202.
3
spirkz lädt die Datei im Hintergrund herunter, speichert sie und legt für den Creator eine ausstehende Einreichung an.
4
Das spirkz-Team prüft sie. Wenn sie freigegeben ist und scheduledAt noch in der Zukunft liegt, geht sie zu diesem Zeitpunkt live; andernfalls sofort.
5
Der Scheduler fragt GET /videos/:id ab, um den Fortschritt zu sehen.

Authentifizierung

Sende den Schlüssel des Creators bei jeder Anfrage mit. Ein fehlender, unbekannter oder widerrufener Schlüssel führt zu 401. Schlüssel handeln als der Creator, der sie ausgestellt hat.

Authorization: Bearer spk_...

Ratenlimits, pro Schlüssel

600

Anfragen pro Stunde insgesamt

POST /videos-Aufrufe pro Stunde

Endpunkte

GET/me

Verbindungstest. Ruf ihn direkt auf, nachdem der Creator seinen Schlüssel eingefügt hat.

{ "user": { "id", "name", "username" }, "keyName" }

GET/categoriesGET/languages

Daten für deine Auswahlfelder: gültige categoryIds (aktive Kategorien; ?locale= für Namen) und languageSlug-Werte.

POST/videos

Ein Video einreichen. Der Body ist JSON:

Feld		Regeln
videoUrl	Erforderlich	`https`, öffentlich erreichbar, ≤ 2000 Zeichen. mp4 / mov / webm / avi, ≤ 500 MB. Private oder interne Adressen werden abgelehnt.
source	Erforderlich	Wer sendet, z. B. `"zapier"`, `"metricool"`. ≤ 50 Zeichen, wird kleingeschrieben gespeichert.
name	Erforderlich	≤ 150 Zeichen.
categoryIds	Erforderlich	1–5 IDs aus `GET /categories`.
description	Optional	≤ 500 Zeichen.
languageSlug	Optional	Aus `GET /languages`. Standard `en`.
tag	Optional	Array von Strings, bis zu 10 Tags, jeweils ≤ 40 Zeichen.
duration	Optional	Sekunden, nicht-negative Ganzzahl.
scheduledAt	Optional	ISO 8601. Mindestens 10 Minuten und höchstens 60 Tage in der Zukunft. Weglassen oder `null` = live bei Freigabe.

202 — data.video mit status: "received".
400 / 404 — ein Feld ist ungültig. Nichts wird gespeichert.
409 — der Creator hat bereits 10 Videos, die auf Einreichung oder Prüfung warten (einschließlich solcher, die noch heruntergeladen werden).

GET/videosGET/videos/:id

Die Integrations-Videos des Creators, neueste zuerst (?limit, ?offset), oder eines per ID.

{
  "id": "...",
  "source": "zapier",
  "video_url": "https://...",
  "status": "submitted",
  "error": null,
  "created_at": "...",
  "updated_at": "...",
  "userVideo": {
    "id": "...",
    "name": "...",
    "status": "pending",
    "scheduled_at": "2026-10-10T09:00:00.000Z",
    "decline_reason": null,
    "publishedVideoId": null
  }
}

Ein Video verfolgen

Download — `status`

receivedprocessingsubmittedoderfailed

Bei failed steht der Grund in error.

Prüfung — `userVideo.status`

pendingscheduledapprovedoderdeclined

publishedVideoId wird gesetzt, sobald das Video live ist. Ein abgelehntes Video enthält einen decline_reason.

Beispiel

curl -X POST https://server.spirkz.com/api/v1/integrations/videos \
  -H "Authorization: Bearer spk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://example.com/clip.mp4",
    "source": "zapier",
    "name": "Morning routine",
    "categoryIds": ["<category id>"],
    "description": "Day 1",
    "scheduledAt": "2026-10-10T09:00:00Z"
  }'

Native Unterstützung

Jeder Scheduler kann sich mit den obigen Endpunkten integrieren. Diese Tools unterstützen spirkz bereits von Haus aus:

NativgenzlUnterstützt spirkz nativ — verbinde deinen API-Schlüssel und plane los.genzl.com →

Du baust eine Integration?

Sag uns, was du entwickelst, und wir helfen dir beim Launch.

Schreib uns