API Dokumentation
Programmieren Sie Zugriff auf Immopix-Funktionen. Bearbeiten Sie Bilder, verwalten Sie Properties und integrieren Sie KI-Optimierungen in Ihren Workflow.
Hinweis
Die API ist in allen Paketen enthalten. Jeder API-Aufruf verbraucht Credits wie eine Bearbeitung in der Web-Oberfläche.
Sie möchten Immopix ohne eigene Programmierung in einem KI-Assistenten nutzen? Dafür gibt es den Immopix Connector.
Authentifizierung
Die Immopix API verwendet Token-basierte Authentifizierung. Ihr API-Token kann in den Account-Einstellungen generiert und widerrufen werden.
Senden Sie Ihren Token im Authorization Header bei jeder Anfrage:
Authorization: Token ihr_api_token
Sichere Wiederholungen
Wenn Ihre Verbindung abbricht, senden Sie dieselbe Anfrage mit demselben Idempotency-Key erneut. Immopix legt das Objekt oder den Bearbeitungsauftrag dann nicht doppelt an.
Der optionale Header gilt für POST /properties, POST /photos/upload, POST /photos/edit und POST /jobs/{job_id}/discard.
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
- Verwenden Sie für jeden gewünschten Vorgang einen neuen Schlüssel.
- Der Schlüssel darf 1 bis 128 sichtbare ASCII-Zeichen ohne Leerzeichen enthalten. Eine UUID eignet sich dafür.
- Eine Wiederholung mit denselben Daten gibt die gespeicherte Antwort zurück. Der Response-Header
Idempotency-Replayed: truekennzeichnet diese Antwort. - Wenn Sie die Daten ändern, verwenden Sie einen neuen Schlüssel. Andernfalls antwortet die API mit
409 idempotency_conflict. - Die API speichert auch fachliche Fehler für diesen Schlüssel. Verwenden Sie nach einer Korrektur, zum Beispiel nach einem Guthabenkauf, einen neuen Schlüssel.
Fehlerbehandlung
Bei Fehlern gibt die API ein JSON-Objekt mit einem error Feld zurück:
{
"error": "no_credits",
"message": "No credits available. Please purchase a credit pack."
}
{
"error": "validation_error",
"message": {"presets": ["Invalid preset: 'sunset'. Valid presets: [...]"]}
}
Fehler-Codes
| Code | Status | Beschreibung |
|---|---|---|
not_authenticated | 401 | Kein Token gesendet |
authentication_failed | 401 | Token ist ungültig oder widerrufen |
validation_error | 400 | Die Anfrage ist ungültig, zum Beispiel ein unbekannter Preset-Key, ein Bild über 10 MB oder in einem anderen Format, keine oder mehrere Bildquellen, presets und custom_prompt zusammen, eine unbekannte photo_id oder property_id, oder kein Preset passt zum Foto. message nennt das Feld |
no_credits | 402 | Keine Credits verfügbar |
rate_limit_exceeded | 429 | Rate Limit erreicht |
invalid_idempotency_key | 400 | Schlüssel ist leer, zu lang oder enthält Leerzeichen |
idempotency_conflict | 409 | Derselbe Schlüssel wurde mit anderen Daten verwendet |
idempotency_in_progress | 409 | Der erste Aufruf läuft noch. Wiederholen Sie die Anfrage nach der Zeit im Retry-After Header |
edit_in_progress | 409 | Für dieses Foto läuft bereits eine Bearbeitung. Senden Sie die Anfrage erneut, wenn sie abgeschlossen oder fehlgeschlagen ist |
reason_required | 400 | POST /jobs/{job_id}/discard: Für eine Erstattung braucht dieses Konto eine Begründung mit mindestens 20 Zeichen in reason |
refund_not_allowed | 403 | POST /jobs/{job_id}/discard: Eine Erstattung ist für dieses Konto oder dieses Foto derzeit nicht möglich. Nichts wurde geändert |
job_not_completed | 409 | POST /jobs/{job_id}/discard: Der Job ist nicht abgeschlossen |
not_active_result | 409 | POST /jobs/{job_id}/discard: Das Ergebnis ist nicht mehr die aktuelle Version des Fotos |
already_discarded | 409 | POST /jobs/{job_id}/discard: Das Ergebnis wurde bereits verworfen |
not_discardable | 409 | POST /jobs/{job_id}/discard: Der Job ist keine Bearbeitung (zum Beispiel ein Upscale), oder das Foto ist eine noch nicht freigeschaltete Galerie-Vorschau |
not_configured | 400 | POST /webhooks/test ohne eingetragene Webhook-URL |
delivery_failed | 502 | POST /webhooks/test konnte nicht zugestellt werden |
not_found | 404 | Ressource nicht gefunden |
Paginierung
Listen-Endpoints unterstützen Cursor-basierte Paginierung mit limit (Standard: 20, Max: 100) und cursor Parametern.
{
"data": [...],
"has_more": true,
"next_cursor": "abc123"
}
Rate Limits
60 Anfragen pro Minute pro Token. Bei Überschreitung: 429 Status mit Retry-After Header.
Bild-Limits: Max. 10 MB pro Bild und max. 100 Megapixel. Formate: JPEG, PNG, WebP, GIF und HEIC/HEIF (iPhone-Fotos). Immopix speichert jedes Bild als JPEG: HEIC wird beim Hochladen umgewandelt, die Ausrichtung bleibt erhalten. Eine URL lädt Immopix höchstens 30 Sekunden lang.
Tutorial: Bild bearbeiten
Der typische Workflow: Bild hochladen, Job abwarten, Ergebnis abrufen.
Python
import base64
import time
import uuid
import requests
API_TOKEN = "ihr_api_token"
headers = {"Authorization": f"Token {API_TOKEN}"}
edit_headers = {**headers, "Idempotency-Key": str(uuid.uuid4())}
# 1. Bild hochladen
with open("foto.jpg", "rb") as f:
image_base64 = base64.b64encode(f.read()).decode()
response = requests.post(
"https://immopix.ai/api/v1/photos/edit",
headers=edit_headers,
json={
"image_base64": image_base64,
"presets": "auto" # oder: ["sunshine", "optimize"]
}
)
job = response.json()
job_id = job["job_id"]
print(f"Job gestartet: {job_id}")
# 2. Job-Status abfragen (Polling)
while True:
response = requests.get(
f"https://immopix.ai/api/v1/jobs/{job_id}",
headers=headers
)
job = response.json()
if job["status"] == "completed":
print(f"Fertig: {job['result_url']}")
break
elif job["status"] == "failed":
print(f"Fehler: {job['error_message']}")
break
time.sleep(2)
cURL
# 1. Bild hochladen
curl -X POST "https://immopix.ai/api/v1/photos/edit" \
-H "Authorization: Token ihr_api_token" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://example.com/foto.jpg",
"presets": "auto"
}'
# Response: {"job_id": "job_abc123", "status": "pending", ...}
# 2. Job-Status abfragen
curl "https://immopix.ai/api/v1/jobs/job_abc123" \
-H "Authorization: Token ihr_api_token"
Eigene Anweisungen (custom_prompt)
Statt Presets können Sie auch eigene Anweisungen übergeben:
curl -X POST "https://immopix.ai/api/v1/photos/edit" \
-H "Authorization: Token ihr_api_token" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://example.com/foto.jpg",
"custom_prompt": "Rasen grün machen, Himmel blau, Mülltonnen entfernen"
}'
Tipp: Nutzen Sie Webhooks anstelle von Polling, um bei Job-Abschluss benachrichtigt zu werden.
Properties
Properties sind Container für Fotos einer Immobilie.
Listet alle Properties auf.
Query-Parameter
query | Filtert nach Property-Name. Jeder Teil des Namens passt, Groß- und Kleinschreibung spielt keine Rolle. |
{
"data": [
{
"id": "prp_abc123",
"name": "Musterstraße 42",
"created_at": "2024-01-15T10:30:00Z",
"photo_count": 12
}
],
"has_more": false
}
Erstellt eine neue Property.
Request Body
name * | Name der Property |
{
"id": "prp_abc123",
"name": "Musterstraße 42",
"created_at": "2024-01-15T10:30:00Z",
"photo_count": 0
}
Property-Details mit verschachtelter Foto-Liste.
{
"id": "prp_abc123",
"name": "Musterstraße 42",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-16T08:00:00Z",
"photos": [
{
"id": "pht_xyz789",
"title": "Wohnzimmer",
"image_type": "indoor",
"current_url": "https://...",
"thumbnail_url": "https://...",
"created_at": "2024-01-15T10:30:00Z"
}
]
}
Aktualisiert eine Property. Parameter: name
Löscht Property und alle zugehörigen Fotos. Unwiderruflich.
Photos
Listet alle Fotos einer Property auf.
Query-Parameter
image_type | Filtert nach Bildtyp. Werte: indoor, outdoor, floorplan, other. Ein anderer Wert ergibt 400 validation_error. |
{
"data": [
{
"id": "pht_xyz789",
"title": "Wohnzimmer",
"image_type": "indoor",
"current_url": "https://...",
"thumbnail_url": "https://...",
"created_at": "2024-01-15T10:30:00Z"
}
],
"has_more": false
}
Foto-Details mit Revision-History und URLs.
{
"id": "pht_xyz789",
"property_id": "prp_abc123",
"title": "Wohnzimmer",
"filename": "api_upload.jpg",
"image_type": "indoor",
"floorplan_type": "",
"current_url": "https://...",
"thumbnail_url": "https://...",
"revisions": [
{
"id": "3f2c9a4e-8b1d-4c7a-9e55-0d6f1b2a7c31",
"version": 2,
"is_original": false,
"is_active": true,
"url": "https://...",
"width": 2048,
"height": 1536,
"presets": ["optimize_indoor", "declutter_indoor"],
"custom_prompt": false,
"created_at": "2024-01-15T10:31:10Z"
}
],
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:31:10Z"
}
Sendet ein Bild zur KI-Optimierung.
Request Body
image_base64 | Base64-kodierte Bilddaten |
image_url | URL zum Bild (öffentlich zugänglich) |
photo_id | Bestehendes Foto erneut bearbeiten |
presets | Array von Preset-Keys oder "auto". Alle Keys liefert GET /presets. |
custom_prompt | Eigene Anweisungen (max. 1000 Zeichen). Kernvorgaben werden automatisch angewendet. |
property_id | Mit Property verknüpfen |
edit_mode | "outdoor", "indoor" oder "floorplan". Ohne Angabe ergibt sich der Modus aus den Presets, bei "auto" aus der Bilderkennung. |
lock_camera_angle | Kamerawinkel beibehalten (boolean) |
room_type | Raumtyp für Möblierung. Werte: living_room, bedroom, kitchen, bathroom, kids_room, dining_room, hallway, home_office (privates Arbeitszimmer), office (gewerbliches Büro), garage, basement, dressing_room. Ohne Angabe wird automatisch erkannt. |
furniture_style | Möbelstil für Staging. Werte: modern, skandinavisch, klassisch, landhausstil, industriell. Ohne Angabe wird automatisch erkannt. |
furniture_instructions | Optionale Wünsche zur Einrichtung, maximal 2.000 Zeichen. Für Innenraum-Staging, mit oder ohne Möbelstil. Konkrete Wünsche haben Vorrang vor Stilvorgaben und gelten nur für die Einrichtung. |
intensity | "normal" (Standard) oder "subtle" für dezentere Bearbeitung. |
resolution | "2K" (Standard) oder "4K". 4K verbraucht 2 Credits. |
Sie müssen image_base64, image_url oder photo_id angeben.
Senden Sie entweder presets oder custom_prompt, nicht beides. Ohne Angabe gilt "auto". Für Grundrisse gibt es keine automatische Bearbeitung: Senden Sie genau ein floorplan-Preset, sonst antwortet die API bei einem bestehenden Foto mit 400 validation_error.
"auto": Immopix erkennt, ob das Foto innen oder außen aufgenommen wurde, und verbessert, was im Bild ist. Außen: sunshine, optimize, declutter. Innen: optimize_indoor, declutter_indoor. Auf einer Baustelle bleiben Baumaterialien erhalten, innen dann nur optimize_indoor. "auto" fügt nie Möbel oder Deko hinzu (staging, details). Diese Presets wählen Sie ausdrücklich.
Bei einem neuen Bild (image_base64 oder image_url) und bei einem Foto, dessen Erkennung nach POST /photos/upload noch läuft, erkennt Immopix den Bildtyp nach der Anfrage. Der Job bleibt bis dahin pending mit leerem presets, meist einige Sekunden. Ist das Bild ein Grundriss oder lässt sich der Typ nicht erkennen, endet der Job mit failed, und der Credit wird erstattet. Mit edit_mode oder eigenen presets entfällt die Erkennung.
Die aktuellen Werte für presets, room_type und furniture_style rufen Sie über GET /presets ab.
Verfügbare Presets
Verwenden Sie "auto" für automatische Erkennung, oder wählen Sie für jedes Foto eigene Presets. Die vollständige, aktuelle Liste liefert GET /presets.
Response
{
"job_id": "job_abc123",
"photo_id": "pht_xyz789",
"status": "pending"
}
Lädt ein Foto hoch, ohne eine Bearbeitung auszulösen. Keine Credits werden verbraucht. Das Foto wird gespeichert, kategorisiert und steht im Dashboard zur Bearbeitung bereit.
Request Body
image_base64 | Base64-kodierte Bilddaten |
image_url | URL zum Bild (öffentlich zugänglich) |
property_id | Mit Property verknüpfen (optional, Standard: "API Uploads") |
Sie müssen image_base64 oder image_url angeben (genau eines).
Response (201)
{
"photo_id": "pht_xyz789",
"property_id": "prp_abc123",
"property_url": "https://immopix.ai/app/property/prp_abc123/"
}
Löscht Foto und alle Revisionen.
Jobs
Job-Status abfragen. Status: pending | processing | completed | failed
{
"job_id": "job_abc123",
"photo_id": "pht_xyz789",
"status": "completed",
"presets": ["optimize_indoor", "declutter_indoor"],
"custom_prompt": false,
"qa": {
"status": "passed",
"risk_score": 1,
"reason": "Fenster, Türen und Wände sind unverändert.",
"checked_at": "2024-01-15T10:31:40Z"
},
"discarded_at": null,
"result_url": "https://...",
"width": 2048,
"height": 1536,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:31:40Z"
}
result_url, width, height nur bei status: "completed".
error_message nur bei status: "failed". Die Meldung ist immer auf Deutsch, auch wenn das Konto Englisch eingestellt hat.
presets sind die Presets, die der Job anwendet, nach den Regeln oben aufgelöst. custom_prompt: true heißt, dass der Job eine eigene Anweisung statt Presets ausführt. presets ist dann leer. presets und custom_prompt stehen auch in jeder Revision von GET /photos/{id}.
discarded_at ist der Zeitpunkt, zu dem das Ergebnis verworfen wurde. Das gilt für POST /jobs/{job_id}/discard und für die Web-Oberfläche, zum Beispiel "Nur Credit erstatten" oder "Nochmal versuchen". Solange das Ergebnis gilt, ist der Wert null. Der Status bleibt auch nach dem Verwerfen completed, und result_url zeigt weiter auf das verworfene Ergebnis. Zeigen Sie dieses Ergebnis dann nicht mehr an. Die aktuelle Version des Fotos liefert GET /photos/{photo_id}.
Qualitätskontrolle (qa)
Immopix prüft jedes Ergebnis automatisch: Sind Fenster, Türen, Wände und Decken erhalten? Die Prüfung läuft nach dem Abschluss des Jobs und dauert meist weniger als eine Minute. Dasselbe Objekt qa steht im Webhook. Ein Job, der 30 Minuten nach dem Abschluss noch kein Prüfergebnis hat, zeigt not_checked.
pending | Die Prüfung ist noch nicht fertig. Das Ergebnis kommt mit dem Webhook job.qa_completed. |
passed | Die Prüfung hat keinen Fehler gefunden. |
warning | Die Prüfung hat wahrscheinlich einen Fehler gefunden (risk_score 8 oder höher). Die Web-Oberfläche zeigt bei diesem Ergebnis einen Hinweis. Zeigen Sie Ihren Nutzern denselben Hinweis. |
minor_issue | Die Prüfung hat eine Abweichung mit niedrigerem Risiko gefunden (risk_score unter 8). Die Web-Oberfläche zeigt keinen Hinweis. |
not_checked | Es gibt kein Prüfergebnis und normalerweise kommt auch keins: bei Grundrissen, Upscales, fehlgeschlagenen Jobs und wenn die Prüfung ohne Ergebnis endete. Wenn eine Prüfung sehr lange in der Warteschlange stand, kann ihr Ergebnis in seltenen Fällen noch nach not_checked kommen. |
risk_score (1 bis 10), reason (die Begründung in der Sprache des Kontos) und checked_at gibt es nur mit einem Prüfergebnis. Sonst sind sie null oder leer.
Verwirft das Ergebnis eines Jobs und erstattet die Credits dafür. Das ist die Geld-zurück-Garantie der Web-Oberfläche ("Nur Credit erstatten") mit denselben Regeln. Das Foto zeigt danach wieder die Version vor diesem Ergebnis.
Request Body (optional)
reason | Was am Ergebnis nicht stimmt, maximal 500 Zeichen. Bei sehr vielen Erstattungen in den letzten 30 Tagen verlangt Immopix mindestens 20 Zeichen, sonst antwortet die API mit 400 reason_required. |
Die Erstattung entspricht dem, was der Job gekostet hat. Eine kostenlose Revision erstattet 0 Credits und gibt die freie Revision zurück.
Nur ein abgeschlossener Job, dessen Ergebnis die aktuelle Version des Fotos ist, lässt sich verwerfen. Ein zweiter Aufruf für denselben Job antwortet mit 409 already_discarded und erstattet nichts. Dieselbe Antwort kommt, wenn jemand das Ergebnis in der Web-Oberfläche abgelehnt hat, zum Beispiel mit "Nochmal versuchen". Nach dem Verwerfen zeigt der Job discarded_at.
Konten ohne Kauf und Konten mit sehr vielen Erstattungen bekommen keine Credits zurück (403 refund_not_allowed). Eine kostenlose Revision können sie trotzdem verwerfen.
Response
{
"job_id": "job_abc123",
"photo_id": "pht_xyz789",
"credits_refunded": 1,
"credits_remaining": 24,
"current_url": "https://..."
}
credits_remaining ist Ihr Guthaben nach der Erstattung. current_url ist die Version, die das Foto jetzt zeigt.
Presets
Dieser Endpoint liefert alle Optionen, die eine Bearbeitung annimmt. So halten Sie Ihre Integration aktuell, ohne die Werte fest einzutragen.
Listet alle Presets, Möbelstile und Raumtypen auf.
Response
{
"presets": [
{
"key": "optimize",
"edit_mode": "outdoor",
"label": "Belichtung optimieren",
"description": "Helligkeit, Farben & Kontrast verbessern"
},
{
"key": "staging",
"edit_mode": "indoor",
"label": "Virtuell möblieren",
"description": "Leere Räume mit passenden Möbeln einrichten"
},
{
"key": "floorplan_3d",
"edit_mode": "floorplan",
"label": "3D Grundriss",
"description": "2D-Grundriss in eine 3D-Ansicht umwandeln"
}
...
],
"furniture_styles": ["modern", "skandinavisch", ...],
"room_types": [
{"key": "living_room", "label": "Wohnzimmer"},
{"key": "bedroom", "label": "Schlafzimmer"}
...
]
}
Die key-Werte setzen Sie direkt in POST /api/v1/photos/edit ein: presets aus presets, room_type aus room_types und furniture_style aus furniture_styles.
edit_mode ordnet jedes Preset einem Modus zu: outdoor, indoor oder floorplan. Verwenden Sie nur Presets aus dem Modus, den Sie in der Anfrage senden.
Ohne presets oder mit "auto" wählt Immopix passende Presets für das Bild aus (Regeln).
Webhooks
Webhook-URLs werden in den Account-Einstellungen konfiguriert. Events: job.completed, job.failed, job.qa_completed. Immopix sendet sie für jede Bearbeitung im Konto, auch für Bearbeitungen in der Web-Oberfläche.
{
"event": "job.completed",
"job": {
"id": "job_abc123",
"photo_id": "pht_xyz789",
"status": "completed",
"presets": ["sunshine", "optimize", "declutter"],
"custom_prompt": false,
"qa": {
"status": "pending",
"risk_score": null,
"reason": "",
"checked_at": null
},
"discarded_at": null,
"created_at": "2024-01-15T10:30:00Z",
"result_url": "https://...",
"width": 2048,
"height": 1536
}
}
job.completed kommt sofort nach der Bearbeitung. Die Qualitätskontrolle läuft danach, deshalb steht dort meist "qa": {"status": "pending"}. Wenn die Prüfung endet, sendet Immopix job.qa_completed mit demselben Job-Objekt und dem Ergebnis in qa, auch wenn die Prüfung kein Ergebnis liefert (not_checked). Steht in job.completed bereits not_checked, zum Beispiel bei Grundrissen, folgt kein weiteres Event. Wurde das Ergebnis vor dem Ende der Prüfung verworfen (discarded_at), sendet Immopix kein job.qa_completed.
Die Events können in anderer Reihenfolge ankommen. Ein wiederholtes job.completed kann zum Beispiel nach job.qa_completed ankommen. Ordnen Sie jedes Event über die Job-ID zu und lesen Sie den Stand der Prüfung aus qa.status. Ein pending ersetzt dabei kein Prüfergebnis, das Sie schon haben. Kommt kein job.qa_completed, fragen Sie den Job etwa 30 Minuten nach dem Abschluss einmal mit GET /jobs/{job_id} ab.
Das Job-Objekt im Webhook hat dieselben Felder wie GET /jobs/{job_id}, mit drei Unterschieden: Die Job-ID heißt im Webhook id statt job_id. updated_at fehlt im Webhook. error_message fehlt im Webhook, wenn die Meldung leer ist.
Retry-Policy: Bis zu 4 Versuche: sofort, dann nach 1, 5 und 30 Minuten. Ein Versuch gilt als erfolgreich, wenn Ihr Server innerhalb von 10 Sekunden mit einem Status unter 400 antwortet. Weiterleitungen folgt Immopix nicht.
Immopix schaltet den Webhook erst ab, wenn mindestens 24 Stunden lang keine Zustellung gelungen ist und in dieser Zeit mindestens 4 Versuche fehlgeschlagen sind. Sofort ab schaltet ihn nur eine URL, deren Host direkt eine private oder interne IP-Adresse ist (zum Beispiel 127.0.0.1 oder 10.0.0.5), oder eine URL, die nicht mit http oder https beginnt. Ein Hostname, der auf eine private Adresse zeigt, zählt als normaler Fehlversuch. Immopix versucht es dann erneut, und es gilt die 24-Stunden-Regel. Wenn Immopix den Webhook abschaltet, bekommt der Kontoinhaber eine E-Mail. Solange der Webhook aus ist, sendet Immopix keine Events und holt sie später nicht nach. Fragen Sie den Status dann mit GET /jobs/{job_id} ab. Nach dem Einschalten in den Account-Einstellungen beginnt die Zählung neu.
Signatur-Verifizierung
Jeder Webhook enthält einen X-Immopix-Signature Header (HMAC-SHA256).
import hmac
import hashlib
def verify_signature(payload: bytes, signature: str | None, secret: str) -> bool:
if not signature:
return False
expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected.encode(), signature.encode())
# In Ihrem Webhook-Handler:
signature = request.headers.get("X-Immopix-Signature")
if not verify_signature(request.data, signature, WEBHOOK_SECRET):
return "Invalid signature", 401
const crypto = require('crypto');
function verifySignature(payload, signature, secret) {
if (typeof signature !== 'string') return false;
const expected = Buffer.from(crypto.createHmac('sha256', secret).update(payload).digest('hex'));
const received = Buffer.from(signature);
if (received.length !== expected.length) return false;
return crypto.timingSafeEqual(expected, received);
}
Credits
Die API verwendet dasselbe Credit-System wie die Web-Oberfläche. Details finden Sie auf unserer Preisseite. Bei einem no_credits-Fehler sind Ihre Credits aufgebraucht.