VivaPix
Language English
Book a package

VivaPix API

Photo in, AI image out.

Are you building photo booth software, an event platform or a gallery of your own? The VivaPix API takes a photo and a scene and returns the transformed image — with recognisable faces, checked automatically. Your interface stays yours; VivaPix is the step in between.

This is not an announcement: every VivaPix integration already runs on exactly this interface today — the booth on the iPad, the folder watcher in the browser and the Windows program. Anyone integrating it uses the same route we use ourselves every evening.

The interface costs nothing. You pay for AI moments, from 0.18 € per image.

Four calls, one image

The same sequence our own integrations follow — under /api/v1/, versioned from the start.

  1. 1

    Upload

    The photo goes to POST /api/v1/media/. EXIF data is stripped the moment it arrives — the location it was taken and the camera's serial number have no business reaching an AI provider.

  2. 2

    Transform

    POST /api/v1/generations/ with a picture and a scene. The result is checked automatically against the original; if one AI provider fails, the next one in the escalation chain takes over.

  3. 3

    Poll

    GET /api/v1/generations/<id>/ tells you how far along it is. The transformation usually takes a good twenty seconds — long enough that nobody should be holding a connection open for it.

  4. 4

    Download

    GET /api/v1/media/<id>/ returns the finished image — and if you want, it sits in the event's guest gallery at the same time, with a QR code per picture.

What you need

  1. 1

    A business account

    With a balance in AI moments. In it you create events and choose per event the scenes your software may offer.

  2. 2

    A device token

    Every installation of your software identifies itself with its own token — Authorization: Device <token>. It belongs to one event, can be revoked individually and is stored on our side only as a hash.

  3. 3

    The event's scenes

    GET /api/v1/themes/ returns what the event offers — with name, description and the number of people a scene is built for. Your interface shows them however it likes.

What it looks like in code

A sketch of the four calls as the Windows connector sends them today. Partners receive the full field reference with their access. 

# 1. Upload the photo
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. Transform
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. Poll, every few seconds
curl https://vivapix.de/api/v1/generations/$GENERATION_ID/ \
  -H "Authorization: Device $TOKEN"
# → status: pending | processing | completed, plus output_asset, quality_grade, druck

# 4. Fetch the picture
curl https://vivapix.de/api/v1/media/$OUTPUT_ASSET_ID/ \
  -H "Authorization: Device $TOKEN"
# → signed download address

Limits and behaviour

  • Images as JPEG or PNG up to 32 MB. EXIF data is stripped on arrival, and the picture is reduced to 1 megapixel before it goes to the AI — more measurably adds nothing.
  • A transformation usually takes a good twenty seconds, rarely more than a minute with a second attempt. Your software polls instead of waiting.
  • Every scene carries a limit on the number of people. A shot with more people is rejected, not processed badly — your interface can show that beforehand.
  • If a result fails the automatic check on the second attempt too, or the AI provider rejects a picture, the response delivers the original photo, marked as such — nobody faces an empty screen, and the attempt costs nothing.
  • If the event has a print preset, the response also delivers the finished 10×15 print sheet — your printer gets it without you building a layout.
  • Thirty requests per second and address — enough for a photo booth polling every two seconds; for a platform with many booths we agree a dedicated quota.

What you can count on

  • Device tokens instead of user accounts — every device identifies itself and can be revoked individually.
  • Idempotency based on a fingerprint of the image content — a photo sent twice is neither processed twice nor charged twice.
  • Failed attempts do not come off your balance — you pay for the finished image.
  • Servers in Germany, deletion on a deadline, data processing agreements in place.

Where this honestly stands: early access

The API runs in production, but we are not making a public compatibility promise yet: while only a few partners are connected, individual fields may still change. That is why the field reference is not a public page today but comes with a direct line to us — anyone integrating now hears about changes before they happen and gets a say in them.

As soon as v1 is frozen, the reference will live here. Until then, the way in is an email.

Request API access See the terms

No software of your own?

Then you do not need the API: a photo booth you already own gets its AI images through the folder watcher — in the browser, without a line of code. What the whole evening's setup looks like is in the guide on Add AI to a photo booth you already own.