Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Bildquellen: URL und Base64

Lektion 6 von 14 Aktualisiert am 3. November 2026 Anfänger
Auf dieser Seite
  1. Bereitstellung von Bildern für den Endpunkt
  2. URL-Format
  3. Base64-Daten-URI-Format
  4. Dritte Option: Eine Datei aus dem Files API
  5. Hilfsfunktion
  6. Praktische Übung
  7. Kernaussagen

Aktualisiert am 3. November 2026. Basierend auf der Seite Bildbearbeitung und der Referenz für die xAI Images API: Eine Quellbild kann alternativ auch über die file_id eines im Files API hochgeladenen Bildes angegeben werden, als exklusiver Ersatz für url. Quellen: Bildbearbeitung · Images API.

Bereitstellung von Bildern für den Endpunkt

Der Endpunkt für Bearbeitungen akzeptiert Quellbilder in drei Formen: eine öffentliche URL, eine Base64-Daten-URI oder die file_id eines bereits im xAI Files API hochgeladenen Bildes. Jede Form hat ihre spezifischen Anwendungsfälle; die Beherrschung dieser Optionen ermöglicht es Ihnen, flexible Bearbeitungsprozesse zu erstellen.

URL-Format

Das URL-Format ist die bequemste Option, solange das Bild bereits online verfügbar ist: keine Kodierung erforderlich, ein kleiner Datenübertrag und eine Anfrage, die in den Protokollen lesbar bleibt. Die entscheidende Einschränkung hierbei ist öffentlich – das Bild muss von den xAI-Servern ohne Sitzung oder Token abrufbar sein.

payload = {
    "model": "grok-imagine-image",
    "prompt": "Fügen Sie einen goldenen Rahmen um dieses Bild hinzu",
    "image": {
        "url": "https://exemple.com/ma-photo.jpg"
    }
}

URL-Einschränkungen

  • Die URL muss öffentlich zugänglich sein (keine Links, die durch Authentifizierung geschützt sind)
  • Unterstützte Formate sind JPEG, PNG und WebP
  • Das Bild muss schnell abrufbar sein (vermeiden Sie langsame Server)

Nutzung von Ausgabe-URLs aus der API

Dies ist der Grund, warum mehrstufige Bearbeitungen praktikabel sind: Die Ausgabe einer Bearbeitung kann als Eingabe für die nächste dienen, ohne dass das Bild jemals auf Ihren lokalen Computer heruntergeladen werden muss. Es gibt jedoch eine Einschränkung: Diese URLs laufen ab, sodass die gesamte Kette in einem Durchlauf ausgeführt werden muss. Für einen Workflow, der über einen längeren Zeitraum verteilt ist, laden Sie das Bild zwischen den Schritten herunter.

import requests
import os

headers = {
    "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
    "Content-Type": "application/json"
}

# Generieren eines Bildes
gen_response = requests.post(
    "https://api.x.ai/v1/images/generations",
    headers=headers,
    json={
        "model": "grok-imagine-image",
        "prompt": "Eine mittelalterliche Burg auf einem Hügel"
    }
).json()

generated_url = gen_response["data"][0]["url"]

# Bearbeiten des generierten Bildes
edit_response = requests.post(
    "https://api.x.ai/v1/images/edits",
    headers=headers,
    json={
        "model": "grok-imagine-image",
        "prompt": "Fügen Sie einen Drachen hinzu, der über die Burg fliegt",
        "image": {"url": generated_url}
    }
).json()

Base64-Daten-URI-Format

Für lokal gespeicherte oder dynamisch generierte Bilder verwenden Sie das Base64-Daten-URI-Format:

import base64

# Ein lokales Bild lesen
with open("photo_locale.jpg", "rb") as f:
    image_bytes = f.read()

b64_string = base64.b64encode(image_bytes).decode("utf-8")
data_uri = f"data:image/jpeg;base64,{b64_string}"

payload = {
    "model": "grok-imagine-image",
    "prompt": "Transformieren Sie dieses Foto in eine Vektorillustration",
    "image": {
        "url": data_uri
    }
}

Wann Base64 verwenden?

Das Kriterium ist einfach: Base64 ist dann notwendig, wenn die Nutzung einer öffentlichen URL unnötig wäre. Dies gilt für lokale Bilder, die nirgendwo gehostet sind – das Hochladen auf einen Server nur, um sie für die API zugänglich zu machen, fügt einen Schritt und eine Verzögerung hinzu, ohne Mehrwert. Es gilt auch für Bilder, die im Arbeitsspeicher von Ihrer Anwendung generiert werden: Eine Chart, die auf dem Fly erstellt wird, ein Screenshot eines Renders oder ein dynamisch zusammengesetztes Vorschaubild müssen niemals die Festplatte berühren. Base64 adressiert zudem ein Datenschutzbedenken – ein im Anforderungskörper kodiertes Bild wird niemals auf einem öffentlichen Server offengelegt, auch nicht vorübergehend – und vereinfacht die Architektur: Ein automatischer Prozess, der Generierung, Bearbeitung und Speichern verknüpft, funktioniert von Ende zu Ende ohne Zwischenhosting, das bereitgestellt, gesichert und bereinigt werden müsste.

Achten Sie auf die Größe

Base64 vergrößert den Datenübertrag um etwa ein Drittel, was für ein Vorschaubild vernachlässigbar ist, aber bei einem mehrmegabytegroßen Foto signifikant wird – längere Upload-Zeiten und ein Risiko, die Größenlimits der Anfrage zu überschreiten. Faustregel: Wenn das Bild bereits online zugänglich ist, verwenden Sie die URL; wenn es lokal ist, ist Base64 einfacher als das Hosten nur für diesen Anlass.

Dritte Option: Eine Datei aus dem Files API

Ein Bild, das bereits im xAI Files API hochgeladen wurde, wird durch seine Kennzeichnung angegeben, anstatt durch eine URL. Die beiden Felder sind sich gegenseitig ausschließend: Ein image-Objekt enthält entweder url oder file_id.

payload = {
    "model": "grok-imagine-image",
    "prompt": "Fügen Sie Schnee in die Landschaft hinzu",
    "image": {"file_id": "file_abc123"}
}

Dies ist die natürliche Wahl für ein Bild, das über mehrere Bearbeitungen hinweg wiederverwendet wird: Es wird nur einmal gesendet und muss nicht öffentlich sein.

Hilfsfunktion

Hier ist eine Funktion, die beide Formate automatisch verarbeitet:

import base64
import os

def prepare_image_source(source):
    """Vorbereitet eine Bildquelle für die API (URL oder lokale Datei)."""
    if source.startswith("http://") or source.startswith("https://"):
        return {"url": source}

    if os.path.isfile(source):
        ext = source.rsplit(".", 1)[-1].lower()
        mime_map = {"jpg": "jpeg", "jpeg": "jpeg", "png": "png", "webp": "webp"}
        mime_type = mime_map.get(ext, "jpeg")

        with open(source, "rb") as f:
            b64 = base64.b64encode(f.read()).decode("utf-8")
        return {"url": f"data:image/{mime_type};base64,{b64}"}

    raise ValueError(f"Ungültige Quelle: {source}")

Diese Funktion erkennt automatisch, ob die Quelle eine URL oder ein lokaler Dateipfad ist, und formatiert das Objekt entsprechend.

Praktische Übung

Testen Sie beide Formate mit demselben Bild und demselben Prompt, um zu überprüfen, dass beide Wege funktionieren; die resultierenden Bilder variieren von Lauf zu Lauf, wie bei jeder Generierung:

# Über URL
payload_url = {
    "model": "grok-imagine-image",
    "prompt": "Fügen Sie Schnee in die Landschaft hinzu",
    "image": {"url": "https://exemple.com/paysage.jpg"}
}

# Über Base64
payload_b64 = {
    "model": "grok-imagine-image",
    "prompt": "Fügen Sie Schnee in die Landschaft hinzu",
    "image": prepare_image_source("paysage.jpg")
}

Kernaussagen

  • Drei Eingabeformen: öffentliche URL, Base64-Daten-URI oder file_id aus dem Files API
  • Temporäre URLs, die von der API zurückgegeben werden, können als Bearbeitungsquellen dienen
  • Base64 vergrößert den Datenübertrag um ~33 %
  • Erstellen Sie eine Hilfsfunktion, um beide Formate automatisch zu verarbeiten
  • Die URL muss öffentlich zugänglich sein, um zu funktionieren