API v1Entwickler-Dokumentation

carvitra Bilder-API-Referenz

Fahrzeugfotos automatisiert veredeln, direkt aus Ihrem System. Für IT-Abteilungen und Agenturen, die die KI-Bildveredelung von carvitra ohne Dashboard nutzen möchten.

Basis-URL: https://www.carvitra.de/api/v1
Format: JSON über HTTPS
Preis: ab 0,14 € netto je Bild

Zum Beispiel API-Schlüssel erzeugen

POST /api/v1/images · 202 Accepted

{ "job_id": "0f6b2c1e-8a4d-4c55-9a51-2d7b3e9f41aa", "status": "queued", "resolution": "l", "requested_output_size": "1920x1440", "price_cents": 18, "balance_cents": 4982, "poll_url": "https://www.carvitra.de/api/v1/images/0f6b2c1e-8a4d-4c55-9a51-2d7b3e9f41aa" }

Kapitel 1

Überblick

Die Bilder-API stellt die KI-Bildveredelung, die carvitra für Fahrzeug-Landingpages einsetzt, als Schnittstelle bereit.

Sie laden ein Fahrzeugfoto hoch, wählen einen Bildstil und erhalten das veredelte Bild als JPEG zum Download. Das Fahrzeug bleibt erhalten, Umgebung und Inszenierung entstehen im gewählten Stil.

Die Verarbeitung läuft asynchron: Ihr Auftrag wird sofort angenommen und im Hintergrund abgearbeitet. Den Fortschritt fragen Sie über die Auftragsnummer job_id ab.

Schritt 1Bildstil wählenGET /styles
Schritt 2Upload-Adresse anfordernPOST /uploads
Schritt 3Foto hochladenPUT upload_url
Schritt 4Auftrag erteilenPOST /images
Schritt 5Status & DownloadGET /images/{job_id}

Voraussetzungen

Tarif: ein bezahlter carvitra-Tarif ab Starter. Eigene Studio-Stile stehen ab Pro zur Verfügung.
Freischaltung: Im Dashboard erscheint der Menüpunkt API-Zugang, sobald die Schnittstelle für Ihr Autohaus freigeschaltet ist.
Rolle: Schlüssel und Guthaben verwalten Inhaber und Admins. Mitglieder sehen den Bereich nur lesend.
Guthaben: Die API wird im Voraus bezahlt. Jeder Auftrag bucht seinen Preis vom Guthaben ab.

Kapitel 2

API-Schlüssel & Guthaben

Jede Anfrage weist sich mit einem API-Schlüssel aus. Den Schlüssel erzeugen Sie selbst im carvitra-Dashboard.

Schlüssel erzeugen

Melden Sie sich im carvitra-Dashboard als Inhaber oder Admin an.
Öffnen Sie in der Navigation API-Zugang.
Klicken Sie im Bereich API-Schlüssel auf Schlüssel erzeugen.
Vergeben Sie einen Namen, damit Sie den Schlüssel später zuordnen können, zum Beispiel den Namen Ihrer Agentur. Bestätigen Sie mit Schlüssel erzeugen.
Kopieren Sie den angezeigten Schlüssel und legen Sie ihn sicher ab. Schließen Sie das Fenster mit Ich habe den Schlüssel gespeichert.

Der Schlüssel wird genau einmal angezeigt

carvitra speichert nur einen Prüfwert, nicht den Schlüssel selbst. Ein verlorener Schlüssel lässt sich deshalb nicht wiederherstellen: Erzeugen Sie einen neuen und widerrufen Sie den alten.

Aufbau eines Schlüssels

carv_live_<48 Hex-Zeichen> # insgesamt 58 Zeichen carv_live_3f9a0c7e41b25d68a0e9f1c4b7d2e5a8c3f6b1d4e7a0c2f5

Schlüssel verwalten

Pro Autohaus sind bis zu 10 aktive Schlüssel möglich. Nutzen Sie je Dienstleister einen eigenen Schlüssel, dann können Sie jedem einzeln den Zugang entziehen.
Die Schlüsseltabelle zeigt Name, Anfang des Schlüssels, Status, Erstellung und letzte Nutzung.
Widerrufen wirkt sofort: Die nächste Anfrage mit diesem Schlüssel wird mit 401 unauthorized abgelehnt.

Schlüssel gehören auf den Server

Verwenden Sie den Schlüssel nur in serverseitigem Code, zum Beispiel über eine Umgebungsvariable CARVITRA_API_KEY. Nie in Browser-JavaScript, in einer App oder in einem Git-Repository.

Guthaben aufladen

Im selben Bereich API-Zugang laden Sie Guthaben in festen Paketen auf. Die Zahlung läuft über Stripe. Bei Lastschrift erscheint die Gutschrift, sobald Ihre Bank die Zahlung bestätigt hat.

Paket netto	entspricht Standardbildern
25,00 €	ca. 178
50,00 €	ca. 357
100,00 €	ca. 714
250,00 €	ca. 1.785

Alle Preise netto · zzgl. gesetzlicher USt. Unter 5,00 € Restguthaben zeigt das Dashboard eine Warnung, und Sie erhalten einmalig eine E-Mail. Jede Buchung steht im Buchungsverlauf.

Kapitel 3

Grundlagen

Thema	Regel
Basis-URL	`https://www.carvitra.de/api/v1` · ausschließlich HTTPS
Anmeldung	Header `Authorization: Bearer carv_live_…` an jeder Anfrage
Anfragen	JSON mit `Content-Type: application/json`
Antworten	JSON, Feldnamen in `snake_case`, Meldungstexte auf Englisch
Zeitangaben	ISO 8601 in UTC, z. B. `2026-09-29T08:14:03.512Z`
Beträge	Ganzzahlig in Cent, netto: `"price_cents": 14` = 0,14 €

Header jeder Anfrage

Authorization: Bearer carv_live_3f9a0c7e41b25d68a0e9f1c4b7d2e5a8c3f6b1d4e7a0c2f5

Fehlerformat

Jeder Fehler hat dieselbe Form. Maßgeblich ist error.code: Die Codes sind stabil und maschinenlesbar. Der Text in message kann sich ändern und ist für Menschen gedacht. Auch unbekannte Pfade antworten in dieser Form (404 not_found). Alle Codes stehen in Kapitel 8.

HTTP 402

{ "error": { "code": "insufficient_credit", "message": "Insufficient credit. Top up your balance in the Carvitra dashboard." } }

Idempotenz: sicher wiederholen

POST /images kostet Guthaben. Damit ein Netzwerkabbruch nicht zu einer doppelten Abbuchung führt, senden Sie den Header Idempotency-Key mit (höchstens 200 Zeichen, frei wählbar).

Fall	Antwort	Wirkung
Gleicher Schlüssel, gleiche Parameter	200 OK	Der ursprüngliche Auftrag mit ursprünglichem Preis und aktuellem Status. Keine zweite Abbuchung.
Gleicher Schlüssel, andere Parameter	409 Conflict	`idempotency_conflict`: anderes Bild, anderer Stil oder andere Auflösung.
Schlüssel im JSON-Body statt im Header	400 Bad Request	`invalid_request`: Der Schlüssel gehört in den Header.

Bewährt hat sich ein Schlüssel aus Ihrer eigenen Fahrzeug- und Bildnummer plus Auflösung, etwa fzg-4711-bild-3-l.

Versionierung und Kompatibilität

Version im Pfad

Die Version steht im Pfad (/api/v1). Innerhalb von v1 werden Fehlercodes nie umbenannt, nur ergänzt.

Neue Felder möglich

Antworten können neue Felder erhalten. Ihr Code sollte unbekannte Felder ignorieren.

Kapitel 4

Endpunkte

Alle Pfade sind relativ zur Basis-URL https://www.carvitra.de/api/v1.

Endpunkt	Zweck	Kosten
GET/styles	Verfügbare Bildstile abrufen	kostenfrei
POST/uploads	Upload-Adresse anfordern	kostenfrei
PUT{upload_url}	Foto hochladen	kostenfrei
POST/images	Veredelungsauftrag erteilen	ab 0,14 € netto
GET/images/{job_id}	Status und Ergebnis abrufen	kostenfrei
DELETE/images/{job_id}	Wartenden Auftrag stornieren	Gutschrift

Direkt zu: /styles · /uploads · Upload · /images · Status · Storno · Details zu Auflösungen in Kapitel 6, zu Fehlergründen in Kapitel 8.

GET

/styles

Bildstile abrufen · kostenfrei

Liefert alle Bildstile, die Sie verwenden dürfen: die Stile von carvitra und ab dem Pro-Tarif Ihre eigenen Studio-Stile. Die id ist genau der Wert, den POST /images als style_id erwartet.

Anfrage

curl https://www.carvitra.de/api/v1/styles \ -H "Authorization: Bearer $CARVITRA_API_KEY"

Antwort 200 OK

Feld	Typ	Bedeutung
`styles[].id`	string	Wert für `style_id`. carvitra-Stile als Kürzel, eigene Stile als `recipe:<uuid>`
`styles[].name`	string	Anzeigename
`styles[].description`	string \| null	Kurzbeschreibung
`styles[].type`	"native" \| "custom"	`native` = carvitra-Stil, `custom` = eigener Studio-Stil

200 OK

{ "styles": [ { "id": "brand_showroom", "name": "Marken-Autohaus", "description": "Brand showroom", "type": "native" }, { "id": "alpine", "name": "Alpenstraße", "description": "…", "type": "native" }, { "id": "recipe:7c1e9d42-5b3a-4f0e-9a6d-2e8f1b4c7a90", "name": "Hausstil Hof", "description": null, "type": "custom" } ] }

Die Antwort darf 5 Minuten zwischengespeichert werden (Cache-Control: private, max-age=300). Der Endpunkt bleibt auch lesbar, wenn Ihr Tarif pausiert ist.

POST

/uploads

Upload-Adresse anfordern · kostenfrei

Das Foto geht nicht an die API selbst, sondern direkt in einen geschützten Speicher. Dafür fordern Sie zuerst eine persönliche Upload-Adresse an. So passen auch große Fotos bis 10 MB durch, und die API muss keine fremden Bild-URLs abrufen.

Body

Feld	Typ	Regel
`file_name`Pflicht	string	Dateiname, 1 bis 200 Zeichen
`content_type`Pflicht	string	`image/jpeg`, `image/png` oder `image/webp`
`file_size`Pflicht	integer	Dateigröße in Byte, höchstens 10 MB

Anfrage

curl -X POST https://www.carvitra.de/api/v1/uploads \ -H "Authorization: Bearer $CARVITRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"file_name":"golf-front.jpg","content_type":"image/jpeg","file_size":2481337}'

Antwort 201 Created

Feld	Typ	Bedeutung
`upload_id`	string	Kennung für `POST /images`. Als undurchsichtige Zeichenkette behandeln.
`upload_url`	string	Signierte Adresse, an die Sie die Datei senden
`method`	"PUT"	HTTP-Methode für den Upload
`expires_in_hours`	integer	Gültigkeit der upload_id: 24 Stunden

201 Created

{ "upload_id": "uploads/8b1f5e2a-…/1759133643512/golf-front.jpg", "upload_url": "https://…/storage/v1/object/upload/sign/api-images/uploads/…?token=…", "method": "PUT", "expires_in_hours": 24 }

Fehler

Status	Code	Ursache
400	`invalid_request`	Feld fehlt, Datei über 10 MB oder anderer Typ als JPEG, PNG oder WebP
401	`unauthorized`	Schlüssel fehlt, ist ungültig oder widerrufen
403	`subscription_required`	Kein bezahlter Tarif

PUT

{upload_url}

Foto hochladen

Senden Sie die Bilddatei unverändert als Body an die upload_url. Der Content-Type muss zum angemeldeten Typ passen.

Hier ohne API-Schlüssel

Die Adresse ist bereits signiert und gehört zum Speicherdienst. Senden Sie Ihren API-Schlüssel dort nicht mit.

Anfrage

curl -X PUT "$UPLOAD_URL" \ -H "Content-Type: image/jpeg" \ --data-binary @golf-front.jpg

Laden Sie direkt nach dem Anfordern hoch. Ein Upload, der nach 24 Stunden keinem Auftrag zugeordnet ist, wird gelöscht.

POST

/images

Auftrag erteilen · kostenpflichtig

Reicht das hochgeladene Foto zur Veredelung ein. Der Preis der gewählten Auflösung wird bei Annahme sofort vom Guthaben abgebucht. Die Antwort kommt unmittelbar, das Bild entsteht danach im Hintergrund.

Header

Header	Regel
`Authorization`Pflicht	`Bearer carv_live_…`
`Content-Type`Pflicht	`application/json`
`Idempotency-Key`empfohlen	Frei wählbar, höchstens 200 Zeichen (siehe Kapitel 3)

Body

Feld	Typ	Regel
`upload_id`Pflicht	string	Wert aus `POST /uploads`, höchstens 24 Stunden alt, Datei hochgeladen
`style_id`Pflicht	string	Eine `id` aus `GET /styles`
`resolution`optional	"auto" \| "s" \| "m" \| "l" \| "xl"	Standard: `"auto"`. Siehe Kapitel 6

Streng geprüft

Unbekannte Felder und unbekannte resolution-Werte führen zu 400 invalid_request. Nichts wird stillschweigend ignoriert oder auf einen Standardwert zurückgesetzt. So bekommen Sie nie ein anderes Bild, als Sie bestellt und bezahlt haben.

Anfrage

curl -X POST https://www.carvitra.de/api/v1/images \ -H "Authorization: Bearer $CARVITRA_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: fzg-4711-bild-1-l" \ -d '{"upload_id":"uploads/8b1f5e2a-…/1759133643512/golf-front.jpg","style_id":"brand_showroom","resolution":"l"}'

Antwort 202 Accepted · bei Wiederholung 200 OK

Feld	Typ	Bedeutung
`job_id`	uuid	Auftragsnummer für Statusabfrage und Storno
`status`	string	Bei neuen Aufträgen `queued`, bei Wiederholung der aktuelle Status
`resolution`	string	Gebuchte Auflösungsstufe
`requested_output_size`	string \| null	Zugesagte Endgröße, z. B. `"1920x1440"`. `null` bei `auto`, weil sich die Größe dort nach der Vorlage richtet
`price_cents`	integer	Abgebuchter Preis netto in Cent
`balance_cents`	integer \| null	Guthaben nach der Buchung
`poll_url`	string	Vollständige Adresse für `GET /images/{job_id}`

202 Accepted

Fehler

Status	Code	Ursache
400	`invalid_request`	Pflichtfeld fehlt, unbekanntes Feld, ungültige `resolution`, `Idempotency-Key` zu lang
402	`insufficient_credit`	Guthaben reicht nicht für diese Stufe
403	`subscription_required`	Kein bezahlter Tarif, oder eigener Stil ohne Pro-Tarif
403	`access_blocked`	Zugang von carvitra gesperrt
404	`not_found`	Unbekannte `style_id`, unbekannte oder abgelaufene `upload_id`
409	`idempotency_conflict`	Schlüssel schon mit anderen Parametern verwendet
429	`too_many_jobs`	2.000 aktive Aufträge erreicht
503	`output_profile_unavailable`	Diese Auflösung ist für Ihr Autohaus nicht freigeschaltet. Es wird nichts abgebucht.

GET

/images/{job_id}

Status & Ergebnis · kostenfrei

Liefert den aktuellen Stand eines Auftrags. Ist er fertig, enthält die Antwort eine zeitlich begrenzte Download-Adresse. Aufträge anderer Autohäuser sind nicht sichtbar und erscheinen als 404.

Anfrage

curl https://www.carvitra.de/api/v1/images/0f6b2c1e-8a4d-4c55-9a51-2d7b3e9f41aa \ -H "Authorization: Bearer $CARVITRA_API_KEY"

Felder in jeder Antwort 200 OK

Feld	Typ	Bedeutung
`job_id`	uuid	Auftragsnummer
`status`	string	queuedprocessingcompletedfailedcancelledexpired
`created_at`	ISO 8601	Zeitpunkt der Annahme
`completed_at`	ISO 8601 \| null	Zeitpunkt des Abschlusses
`resolution`	string	Gebuchte Stufe
`requested_output_size`	string \| null	Zugesagte Endgröße, `null` bei `auto`
`price_cents`	integer	Gebuchter Preis netto in Cent

Zusätzliche Felder je Status

Status	Feld	Bedeutung
completed	`result_url`	Download-Adresse des Ergebnisses (JPEG)
completed	`result_url_expires_in_seconds`	`1800`: Die Adresse gilt 30 Minuten. Jeder neue Abruf liefert eine frische Adresse.
completed	`result_available_hours_after_completion`	`24`: So lange liegt das Ergebnis bereit
failed	`error.code`	Grund des Fehlschlags (siehe Kapitel 8)
failed	`error.message`	Beschreibung für Menschen, auf Englisch
failed	`refunded`	`true`, sobald die Gutschrift gebucht ist
cancelled	`refunded`	Immer `true`

completed

processing

failed

200 OK

{ "job_id": "0f6b2c1e-8a4d-4c55-9a51-2d7b3e9f41aa", "status": "completed", "created_at": "2026-09-29T08:14:03.512Z", "completed_at": "2026-09-29T08:14:49.207Z", "resolution": "l", "price_cents": 18, "requested_output_size": "1920x1440", "result_url": "https://…/storage/v1/object/sign/api-images/results/…/processed.jpg?token=…", "result_url_expires_in_seconds": 1800, "result_available_hours_after_completion": 24 }

Dieser Endpunkt bleibt verfügbar, wenn Ihr Tarif pausiert oder der Zugang gesperrt ist: Bereits bezahlte Ergebnisse können Sie bis zum Ablauf der 24 Stunden abholen.

DELETE

/images/{job_id}

Storno · Gutschrift

Storniert einen Auftrag, der noch wartet (queued). Status und Gutschrift ändern sich in einem Schritt, es gibt also keinen stornierten Auftrag ohne Gutschrift. Hat die Verarbeitung schon begonnen, ist kein Storno mehr möglich.

Anfrage

curl -X DELETE https://www.carvitra.de/api/v1/images/0f6b2c1e-8a4d-4c55-9a51-2d7b3e9f41aa \ -H "Authorization: Bearer $CARVITRA_API_KEY"

Antwort 200 OK

200 OK

{ "job_id": "0f6b2c1e-8a4d-4c55-9a51-2d7b3e9f41aa", "status": "cancelled", "refunded": true }

Fehler

Status	Code	Ursache
409	`not_cancellable`	Auftrag läuft bereits, ist abgeschlossen oder schon storniert
404	`not_found`	Unbekannte `job_id`
403	`access_blocked`	Zugang von carvitra gesperrt
503	`service_unavailable`	Vorübergehend nicht möglich. Auftrag unverändert, erneut versuchen

Bei pausiertem Tarif ist der Storno erlaubt, damit Sie an Ihr Guthaben kommen.

Kapitel 5

Status & Abrechnung

Ein Auftrag durchläuft feste Zustände. Vier davon sind Endzustände: Ab dort ändert sich nichts mehr, und Sie können die Abfrage beenden.

Erfolg
queued, dann processing, dann completed, dann nach 24 h, dann expired
Guthaben: berechnet
Fehlschlag
queued, dann processing, dann failed
Guthaben: gutgeschrieben
Storno
queued, dann DELETE, dann cancelled
Guthaben: gutgeschrieben

Status	Bedeutung	Guthaben
queued	Angenommen, wartet auf Verarbeitung. Stornierbar.	abgebucht
processing	Wird gerade verarbeitet	abgebucht
completed	Fertig, `result_url` vorhanden	berechnet
failed	Fehlgeschlagen, `error` nennt den Grund	gutgeschrieben
cancelled	Von Ihnen storniert	gutgeschrieben
expired	Ergebnis nach 24 Stunden gelöscht	bleibt berechnet

So wird abgerechnet

Abbuchung

Bei Annahme des Auftrags (202) wird der Preis der gewählten Stufe sofort abgebucht. balance_cents zeigt den neuen Stand. Preis pro Bild gilt zum Buchungszeitpunkt.

Gutschrift

Scheitert die Verarbeitung technisch oder erkennt carvitra kein geeignetes Fahrzeugbild, wird der Betrag gutgeschrieben. Ebenso bei einem Storno.

Was berechnet wird

Berechnet wird die erfolgreiche Verarbeitung, nicht das Motiv-Ergebnis. Ein fertiges Bild, das Ihnen gestalterisch nicht gefällt, bleibt berechnet.

Keine verfallenden Aufträge

Bei hoher Systemlast pausiert die Verarbeitung vorübergehend und läuft danach automatisch weiter. Angenommene Aufträge verfallen nicht.

Wie oft abfragen?

Insgesamt werden bis zu rund 300 Bilder pro Stunde verarbeitet — die Kapazität teilen sich alle Nutzer. Aufträge verfallen nicht: In Zeiten hoher Systemlast pausiert die Verarbeitung vorübergehend und läuft danach automatisch weiter. Eine feste Bearbeitungszeit je Auftrag wird nicht zugesagt. Die Stufen auto, s, m und l liegen im selben Zeitrahmen, xl dauert mehrere Minuten je Bild.

Bei vielen Aufträgen fragen Sie jeden höchstens alle 5 Minuten ab, den ältesten zuerst. Darauf ist das Anfrage-Limit je Schlüssel ausgelegt (Kapitel 9).

Kapitel 6

Auflösungen & Preise

Mit resolution legen Sie die Größe des Ergebnisses fest.

Die Stufen mit fester Größe liefern exakt die genannten Maße, immer im Format 4:3. Bei auto richtet sich die Größe nach dem Seitenverhältnis Ihrer Vorlage; deshalb ist requested_output_size dort null.

resolution	Ergebnisgröße	Format	Preis netto je Bild	Freischaltung
`auto`Standard	folgt der Vorlage	JPEG	0,14 €	immer verfügbar
`s`	1.280 × 960 px	JPEG, 4:3	0,14 €	auf Anfrage
`m`	1.600 × 1.200 px	JPEG, 4:3	0,16 €	auf Anfrage
`l`	1.920 × 1.440 px	JPEG, 4:3	0,18 €	auf Anfrage
`xl`	3.840 × 2.880 px	JPEG, 4:3	0,26 €	auf Anfrage

Alle Preise netto · zzgl. gesetzlicher USt. Maßgeblich ist der Preis zum Buchungszeitpunkt; er steht in price_cents jeder Antwort.

Freischaltung der festen Größen

Ist eine Stufe für Ihr Autohaus noch nicht freigeschaltet, antwortet die API mit 503 output_profile_unavailable, und es wird nichts abgebucht. Sprechen Sie Ihren carvitra-Ansprechpartner an, wenn Sie eine feste Größe nutzen möchten.

Kapitel 7

Bildstile

28 Stile stellt carvitra bereit. Die für Ihr Konto gültige Liste liefert immer GET /styles.

Verwenden Sie in Ihrem Code die id, nicht den Anzeigenamen.

Autohaus & Showroom

brand_showroomMarken-Autohaus
modern_dealershipModernes Autohaus
showroomPremium Showroom
stage_presentationModerne Bühnenpräsentation
nature_dealershipNaturnahes Autohaus
industrial_loft_dealershipBackstein-Autohaus
atrium_dealershipLichthof-Autohaus
minimal_concrete_dealershipMinimalistisches Autohaus

Urban & City

urbanUrbane Innenstadt
city_eveningStadtzentrum bei Nacht
industrial_modernModernes Industriegebiet

Natur & Outdoor

country_road_daylightLandstraße bei Tag
coastal_roadKüstenstraße
alpineAlpenstraße
desert_actionWüstenaction
forest_trailWaldweg Abenteuer

Professionell & Atmosphärisch

sunsetAutobahn Sonnenuntergang
parking_garage_premiumPremium-Parkhaus
studioFotostudio Professionell

Jahreszeit & Wetter

winter_snowWinterlandschaft mit Schnee
autumn_forestHerbstwald
luxury_hotelLuxushotel Vorfahrt
night_driveNachtfahrt Autobahn

Motorsport

nuerburgringNürburgring

Kreativ & Lifestyle

hangarFlugzeug-Hangar
glass_factoryGläserne Manufaktur
beach_vacationStrandurlaub
discoDisco

Eigene Studio-Stile

Ab dem Pro-Tarif erscheinen Ihre im carvitra Studio angelegten und aktiven Stile zusätzlich in GET /styles, mit type: "custom" und einer id der Form recipe:<uuid>. Stile anderer Autohäuser sind nicht nutzbar und erscheinen als 404 not_found.

Kapitel 8

Fehlercodes

HTTP-Fehler

Diese Codes stehen im Fehlerformat { "error": { "code", "message" } }. Die Spalte „Wiederholen?“ sagt, ob ein erneuter Versuch ohne Änderung sinnvoll ist.

Status	Code	Bedeutung	Wiederholen?
400	`invalid_request`	Anfrage unvollständig oder Datei zu groß / falscher Typ	Nein, Anfrage korrigieren
401	`unauthorized`	Schlüssel ungültig oder widerrufen	Nein, Schlüssel prüfen
402	`insufficient_credit`	Guthaben reicht nicht — im Dashboard aufladen	Nach dem Aufladen
403	`access_blocked`	Zugang für dieses Konto gesperrt — bitte Carvitra kontaktieren	Nein, carvitra kontaktieren
403	`subscription_required`	Bezahlter Tarif erforderlich (bzw. Pro für eigene Bildstile)	Nein
404	`not_found`	Unbekannte style_id, upload_id oder job_id	Nein
409	`idempotency_conflict`	Derselbe Idempotency-Key wurde mit anderen Bildparametern verwendet	Nein, neuen Schlüssel wählen
409	`not_cancellable`	Storno nur für wartende Aufträge — dieser läuft bereits oder ist abgeschlossen	Nein
429	`rate_limited`	Zu viele Anfragen — kurz warten und erneut versuchen	Ja, nach Retry-After Sekunden
429	`too_many_jobs`	Zu viele gleichzeitige Aufträge — auf Abschluss warten	Ja, sobald Aufträge abgeschlossen sind
503	`output_profile_unavailable`	Diese Auflösung ist für diese Filiale nicht freigeschaltet	Nein, andere Stufe wählen
503	`service_unavailable`	Schnittstelle vorübergehend nicht verfügbar	Ja, mit wachsendem Abstand

Gründe fehlgeschlagener Aufträge

Diese Codes stehen nicht im HTTP-Status, sondern bei status: "failed" im Feld error.code der Statusabfrage.

error.code	Bedeutung
`unsuitable_image`	Kein Fahrzeug erkennbar oder störender Bildinhalt — Betrag gutgeschrieben
`upload_expired`	Quellbild nicht mehr vorhanden (älter als 24 Stunden) — Betrag gutgeschrieben
`processing_failed`	Verarbeitung technisch fehlgeschlagen — Betrag gutgeschrieben
`output_too_large`	4K-Ergebnis überschreitet die Dateigrenze — Betrag gutgeschrieben
`invalid_output`	Ergebnis erfüllt das angeforderte Bildformat nicht — Betrag gutgeschrieben
`worker_timeout`	Verarbeitung mehrfach abgebrochen — Betrag gutgeschrieben

Ein hier nicht aufgeführter Code kann in Zukunft hinzukommen. Behandeln Sie unbekannte Werte wie processing_failed.

Kapitel 9

Limits & Fristen

Bereich	Wert	Hinweis
Dateigröße Upload	10 MB	JPEG, PNG oder WebP
Gültigkeit einer upload_id	24 h	danach 404 not_found
Aktive Aufträge je Autohaus	2.000	queued und processing zusammen
Anfragen je Schlüssel	30.000 / 1 h	darüber 429 rate_limited mit Retry-After
Fehlgeschlagene Anmeldungen je IP-Adresse	10 / 15 min	darüber 429, Retry-After: 900
Gültigkeit der result_url	30 min	jederzeit neu abrufbar
Ergebnis verfügbar	24 h	ab Abschluss, danach expired
Ergebnisdatei	≤ 10 MB	JPEG
Aktive Schlüssel je Autohaus	10	widerrufene zählen nicht
Idempotency-Key	200 Zeichen	Höchstlänge

Kapitel 10

Komplettes Beispiel

Ein Foto hochladen, im Stil brand_showroom veredeln und als ergebnis.jpg speichern.

Der Schlüssel kommt jeweils aus der Umgebungsvariable CARVITRA_API_KEY. Die Abfrage alle 60 Sekunden passt für Einzelbilder; bei Stapeln gilt die Empfehlung aus Kapitel 5.

Bash

Node.js

Python

#!/usr/bin/env bash # Benötigt: curl, jq set -euo pipefail API="https://www.carvitra.de/api/v1" AUTH="Authorization: Bearer $CARVITRA_API_KEY" FILE="golf-front.jpg" SIZE=$(wc -c < "$FILE" | tr -d ' ') # 1. Upload-Adresse anfordern UPLOAD=$(curl -sSf -X POST "$API/uploads" -H "$AUTH" -H "Content-Type: application/json" \ -d "{\"file_name\":\"$FILE\",\"content_type\":\"image/jpeg\",\"file_size\":$SIZE}") UPLOAD_ID=$(jq -r .upload_id <<< "$UPLOAD") UPLOAD_URL=$(jq -r .upload_url <<< "$UPLOAD") # 2. Foto hochladen (ohne API-Schlüssel) curl -sSf -X PUT "$UPLOAD_URL" -H "Content-Type: image/jpeg" --data-binary "@$FILE" > /dev/null # 3. Auftrag erteilen JOB=$(curl -sSf -X POST "$API/images" -H "$AUTH" -H "Content-Type: application/json" \ -H "Idempotency-Key: fzg-4711-bild-1-auto" \ -d "{\"upload_id\":\"$UPLOAD_ID\",\"style_id\":\"brand_showroom\"}") JOB_ID=$(jq -r .job_id <<< "$JOB") echo "Auftrag $JOB_ID angenommen, Preis $(jq -r .price_cents <<< "$JOB") ct" # 4. Status abfragen, bis ein Endzustand erreicht ist while :; do sleep 60 STATE=$(curl -sSf "$API/images/$JOB_ID" -H "$AUTH") case "$(jq -r .status <<< "$STATE")" in completed) curl -sSf -o ergebnis.jpg "$(jq -r .result_url <<< "$STATE")"; echo "Gespeichert: ergebnis.jpg"; break ;; failed|cancelled|expired) echo "$STATE" >&2; exit 1 ;; esac done

Kapitel 11

Empfehlungen für den Betrieb

Wiederholen, aber richtig

Bei 429 warten Sie die Sekunden aus Retry-After ab, bei 503 service_unavailable mit wachsendem Abstand. Wiederholen Sie POST /images immer mit demselben Idempotency-Key. Andere 4xx-Fehler nicht wiederholen.

Ergebnisse sichern

Laden Sie fertige Bilder innerhalb von 24 Stunden herunter und speichern Sie sie selbst. Ist eine result_url abgelaufen, rufen Sie den Status erneut ab und erhalten eine frische Adresse.

Guthaben im Blick

Jede Auftragsantwort enthält balance_cents. Werten Sie das Feld aus, dann fällt ein leeres Guthaben auf, bevor Aufträge mit 402 abgelehnt werden.

Gute Vorlagen

Das Fahrzeug sollte gut erkennbar und möglichst vollständig im Bild sein. Bei Bildern ohne erkennbares Fahrzeug endet der Auftrag mit unsuitable_image und wird gutgeschrieben.

Stil-IDs statt Namen

Anzeigenamen können sich ändern, die id nicht. Laden Sie die Liste aus GET /styles und speichern Sie die id.

Robust gegen Neuerungen

Ignorieren Sie unbekannte Antwortfelder und behandeln Sie unbekannte Fehlercodes nach ihrem HTTP-Status. So bleibt Ihre Anbindung stabil, wenn v1 erweitert wird.