Bildquellen: URL und Base64
Auf dieser Seite
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_ideines im Files API hochgeladenen Bildes angegeben werden, als exklusiver Ersatz fürurl. 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_idaus 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