VivaPix
Sprache Deutsch
Paket buchen

VivaPix API

Bild hinein, KI-Bild zurück.

Du baust eine Fotobox-Software, eine Eventplattform oder eine eigene Galerie? Die VivaPix-API nimmt ein Foto und ein Motiv entgegen und liefert das verwandelte Bild zurück — mit erkennbaren Gesichtern, automatisch geprüft. Deine Oberfläche bleibt deine; VivaPix ist der Schritt dazwischen.

Das ist keine Ankündigung: über genau diese Schnittstelle laufen heute alle VivaPix-Anbindungen — das Booth auf dem iPad, der Ordnerwächter im Browser und das Windows-Programm. Wer sie einbindet, benutzt denselben Weg, den wir selbst jeden Abend benutzen.

Die Schnittstelle kostet nichts. Bezahlt werden KI-Momente, ab 0,18 € je Bild.

Vier Aufrufe, ein Bild

Derselbe Ablauf, den unsere eigenen Anbindungen gehen — unter /api/v1/, versioniert von Anfang an.

  1. 1

    Hochladen

    Das Foto geht an POST /api/v1/media/. Die EXIF-Daten werden sofort beim Eingang entfernt — Aufnahmeort und Geräteseriennummer haben bei einem KI-Anbieter nichts zu suchen.

  2. 2

    Verwandeln

    POST /api/v1/generations/ mit Bild und Motiv. Das Ergebnis wird automatisch gegen das Original geprüft; fällt ein KI-Anbieter aus, übernimmt der nächste in der Eskalationskette.

  3. 3

    Nachfragen

    GET /api/v1/generations/<id>/ sagt, wie weit es ist. Die Verwandlung dauert meist gut zwanzig Sekunden — lang genug, dass niemand auf eine offene Verbindung warten soll.

  4. 4

    Herunterladen

    GET /api/v1/media/<id>/ liefert das fertige Bild — und auf Wunsch liegt es zugleich in der Gästegalerie des Events, mit QR-Code je Bild.

Was du brauchst

  1. 1

    Ein Geschäftskonto

    Mit Guthaben in KI-Momenten. Darin legst du Events an und wählst je Event die Motive, die deine Software anbieten darf.

  2. 2

    Ein Gerätetoken

    Jede Installation deiner Software weist sich mit einem eigenen Token aus — Authorization: Device <token>. Es gehört zu einem Event, lässt sich einzeln zurückziehen und wird bei uns nur als Hash gespeichert.

  3. 3

    Die Motive des Events

    GET /api/v1/themes/ liefert, was das Event anbietet — mit Name, Beschreibung und der Personenzahl, für die ein Motiv gebaut ist. Deine Oberfläche zeigt sie, wie sie will.

So sieht das im Code aus

Eine Skizze der vier Aufrufe, wie sie der Windows-Connector heute sendet. Die vollständige Feld-Referenz bekommen Partner mit dem Zugang. 

# 1. Foto hochladen
curl -X POST https://vivapix.de/api/v1/media/ \
  -H "Authorization: Device $TOKEN" \
  -F "file=@aufnahme.jpg" \
  -F "event=$EVENT_ID" \
  -F "source=photobox" \
  -F "idempotency_key=sha256-der-datei"
# → { "id": "…", "status": "ready" }

# 2. Verwandeln
curl -X POST https://vivapix.de/api/v1/generations/ \
  -H "Authorization: Device $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input_asset": "$ASSET_ID", "theme": "$THEME_ID", "idempotency_key": "sha256-der-datei:$THEME_ID"}'

# 3. Nachfragen, alle paar Sekunden
curl https://vivapix.de/api/v1/generations/$GENERATION_ID/ \
  -H "Authorization: Device $TOKEN"
# → status: pending | processing | completed, dazu output_asset, quality_grade, druck

# 4. Bild holen
curl https://vivapix.de/api/v1/media/$OUTPUT_ASSET_ID/ \
  -H "Authorization: Device $TOKEN"
# → signierte Adresse zum Herunterladen

Grenzen und Verhalten

  • Bilder als JPEG oder PNG bis 32 MB. Die EXIF-Daten werden beim Eingang entfernt, das Bild wird vor dem Versand an die KI auf 1 Megapixel verkleinert — mehr bringt messbar nichts.
  • Eine Verwandlung dauert meist gut zwanzig Sekunden, mit einem zweiten Versuch selten mehr als eine Minute. Deine Software fragt nach, statt zu warten.
  • Jedes Motiv trägt eine Personengrenze. Eine Aufnahme mit mehr Personen wird abgelehnt, nicht schlecht verarbeitet — deine Oberfläche kann das vorher anzeigen.
  • Besteht ein Ergebnis die automatische Prüfung auch im zweiten Anlauf nicht oder lehnt der KI-Anbieter ein Bild ab, liefert die Antwort das Originalfoto mit Kennzeichnung — niemand steht vor einem leeren Bildschirm, und der Versuch kostet nichts.
  • Hat das Event eine Druckvorgabe, liefert die Antwort zusätzlich das fertige Druckblatt im Format 10×15 — dein Drucker bekommt es, ohne dass du ein Layout bauen musst.
  • Dreißig Anfragen je Sekunde und Adresse — genug für eine Fotobox, die alle zwei Sekunden nachfragt, und für eine Plattform mit vielen Boxen sprechen wir über ein eigenes Kontingent.

Womit du rechnen kannst

  • Gerätetoken statt Benutzerkonto — jedes Gerät weist sich selbst aus und lässt sich einzeln zurückziehen.
  • Idempotenz über den Fingerabdruck des Bildinhalts — ein doppelt gesendetes Foto wird nicht doppelt verarbeitet und nicht doppelt bezahlt.
  • Misslungene Versuche gehen nicht auf dein Guthaben — bezahlt wird das fertige Bild.
  • Server in Deutschland, Löschung mit Frist, Auftragsverarbeitung geregelt.

Der ehrliche Stand: Early Access

Die API läuft produktiv, aber wir geben noch kein öffentliches Kompatibilitätsversprechen: solange wenige Partner angebunden sind, können sich einzelne Felder noch ändern. Deshalb gibt es die Feld-Referenz heute nicht als öffentliche Seite, sondern zusammen mit einem direkten Draht zu uns — wer jetzt einbindet, erfährt Änderungen, bevor sie passieren, und kann sie mitprägen.

Sobald v1 eingefroren ist, steht die Referenz hier. Bis dahin ist der Weg eine E-Mail.

API-Zugang anfragen Konditionen ansehen

Keine eigene Software?

Dann brauchst du die API nicht: eine vorhandene Fotobox bekommt ihre KI-Bilder über den Ordnerwächter — im Browser, ohne eine Zeile Code. Wie der ganze Abend-Aufbau aussieht, steht im Ratgeber unter Vorhandene Fotobox mit KI nachrüsten.