API Dokumentation

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 und POST /photos/edit.

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: true kennzeichnet 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": {
    "code": "insufficient_credits",
    "message": "Keine Credits verfügbar"
  }
}

Fehler-Codes

Paginierung

Listen-Endpoints unterstützen Cursor-basierte Paginierung mit limit (Standard: 20, Max: 100) und cursor Parametern.

{
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "abc123"
  }
}

Rate Limits

60 Anfragen pro Minute pro Token. Bei Überschreitung: 429 Status mit Retry-After Header.

Tutorial: Bild bearbeiten

Der typische Workflow: Bild hochladen, Job abwarten, Ergebnis abrufen.

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)

# 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"

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"
  }'

Properties

Properties sind Container für Fotos einer Immobilie.

{
  "data": [
    {
      "id": "prp_abc123",
      "name": "Musterstraße 42",
      "created_at": "2024-01-15T10:30:00Z",
      "photo_count": 12
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}

{
  "id": "prp_abc123",
  "name": "Musterstraße 42",
  "created_at": "2024-01-15T10:30:00Z",
  "photo_count": 0
}

{
  "id": "prp_abc123",
  "name": "Musterstraße 42",
  "created_at": "2024-01-15T10:30:00Z",
  "photo_count": 3,
  "photos": [
    {
      "id": "pht_xyz789",
      "title": "Wohnzimmer",
      "image_type": "indoor",
      "thumbnail_url": "https://..."
    }
  ]
}

Photos

{
  "data": [
    {
      "id": "pht_xyz789",
      "title": "Wohnzimmer",
      "image_type": "indoor",
      "current_url": "https://...",
      "thumbnail_url": "https://...",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}

{
  "id": "pht_xyz789",
  "title": "Wohnzimmer",
  "image_type": "indoor",
  "current_url": "https://...",
  "thumbnail_url": "https://...",
  "revisions": [
    {
      "id": "rev_abc123",
      "version": 1,
      "is_original": false,
      "url": "https://...",
      "created_at": "2024-01-15T10:35:00Z"
    }
  ],
  "created_at": "2024-01-15T10:30:00Z"
}

{
  "job_id": "job_abc123",
  "photo_id": "pht_xyz789",
  "status": "pending"
}

{
  "photo_id": "pht_xyz789",
  "property_id": "prp_abc123",
  "property_url": "https://immopix.ai/app/property/prp_abc123/"
}

Jobs

{
  "job_id": "job_abc123",
  "photo_id": "pht_xyz789",
  "status": "completed",
  "presets": ["sunshine", "optimize"],
  "result_url": "https://...",
  "width": 1920,
  "height": 1080,
  "error_message": null,
  "created_at": "2024-01-15T10:30:00Z"
}

Presets

Dieser Endpoint liefert alle Optionen, die eine Bearbeitung annimmt. So halten Sie Ihre Integration aktuell, ohne die Werte fest einzutragen.

{
  "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"}
    ...
  ]
}

Webhooks

Webhook-URLs werden in den Account-Einstellungen konfiguriert. Events: job.completed, job.failed

{
  "event": "job.completed",
  "job": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "photo_id": "pht_xyz789",
    "status": "completed",
    "presets": ["sunshine", "optimize"],
    "result_url": "https://...",
    "width": 1920,
    "height": 1080,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Signatur-Verifizierung

Jeder Webhook enthält einen X-Immopix-Signature Header (HMAC-SHA256).

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

# 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) {
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Credits

Die API verwendet dasselbe Credit-System wie die Web-Oberfläche. Details finden Sie auf unserer Preisseite. Bei einem insufficient_credits-Fehler sind Ihre Credits aufgebraucht.