Bronnen van afbeeldingen: URL en Base64
Op deze pagina
Bijgewerkt op 3 november 2026. Gebaseerd op de pagina Image Editing en de xAI Images API-referentie: een bronafbeelding kan ook worden opgegeven met behulp van de
file_idvan een bestand in de Files API, als exclusief alternatief voorurl. Bronnen: Image Editing · Images API.
Afbeeldingen aanleveren aan het edit-eindpunt
Het edit-eindpunt accepteert bronafbeeldingen in drie vormen: een openbare URL, een Base64 Data URI of de file_id van een bestand dat al is geüpload naar de xAI Files API. Elke vorm heeft zijn gebruiksscenario’s; als u deze beheerst, kunt u flexibele bewerkingspipelines bouwen.
URL-indeling
De URL-indeling is de handigste optie zolang de afbeelding al online staat: niets te coderen, een kleine payload en een verzoek dat leesbaar blijft in logs. De belangrijkste beperking hier is openbaar: de afbeelding moet door de servers van xAI kunnen worden opgehaald zonder sessie of token.
payload = {
"model": "grok-imagine-image",
"prompt": "Add a gold frame around this image",
"image": {
"url": "https://exemple.com/ma-photo.jpg"
}
}
Beperkingen voor URL’s
- De URL moet openbaar toegankelijk zijn (geen links die door authenticatie zijn beveiligd)
- Ondersteunde indelingen zijn JPEG, PNG en WebP
- De afbeelding moet snel toegankelijk zijn (vermijd trage servers)
Uitvoer-URL’s van de API gebruiken
Dit maakt meertraps bewerking praktisch: de uitvoer van de ene bewerking wordt de invoer voor de volgende, zonder dat de afbeelding ooit naar uw lokale machine hoeft te worden gedownload. Er is wel een kanttekening: deze URL’s verlopen, dus de keten moet in één keer worden uitgevoerd. Voor een workflow die over tijd is gespreid, downloadt u de afbeelding tussen elke stap.
import requests
import os
headers = {
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
}
# Genereer een afbeelding
gen_response = requests.post(
"https://api.x.ai/v1/images/generations",
headers=headers,
json={
"model": "grok-imagine-image",
"prompt": "A medieval castle on a hill"
}
).json()
generated_url = gen_response["data"][0]["url"]
# Bewerk de gegenereerde afbeelding
edit_response = requests.post(
"https://api.x.ai/v1/images/edits",
headers=headers,
json={
"model": "grok-imagine-image",
"prompt": "Add a dragon flying over the castle",
"image": {"url": generated_url}
}
).json()
Base64 Data URI-indeling
Voor afbeeldingen die lokaal zijn opgeslagen of dynamisch worden gegenereerd, gebruikt u de Base64 Data URI-indeling:
import base64
# Lees een lokale afbeelding
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": "Transform this photo into a vector illustration",
"image": {
"url": data_uri
}
}
Wanneer gebruikt u Base64?
Het criterium is eenvoudig: Base64 is nodig wanneer het gebruik van een openbare URL een onnodige omweg zou zijn. Dit geldt voor lokale afbeeldingen die nergens worden gehost; ze uploaden naar een server alleen om ze toegankelijk te maken voor de API voegt een stap en vertraging toe zonder meerwaarde. Het geldt ook voor afbeeldingen die in het geheugen door uw applicatie worden gegenereerd: een grafiek die on-the-fly wordt produced, een screenshot van een render of een dynamisch samengestelde thumbnail hoeven nooit de schijf te raken. Base64 lost ook een privacykwestie op: een afbeelding die in de request-body is gecodeerd, wordt nooit op een openbare server blootgesteld, zelfs niet tijdelijk. Het vereenvoudigt bovendien de architectuur: een geautomatiseerde pipeline die generatie, bewerking en opslag koppelt, werkt end-to-end zonder dat er tussentijds hosting hoeft te worden ingericht, beveiligd en opgeschoond.
Let op de grootte
Base64 blaast de payload met ongeveer een derde op, wat verwaarloosbaar is voor een thumbnail, maar significant wordt voor een foto van meerdere megabytes: langere uploadtijden en het risico dat de limieten voor de verzoeksgrootte worden overschreden. De vuistregel: als de afbeelding al online toegankelijk is, gebruikt u de URL; als deze lokaal staat, is Base64 eenvoudiger dan deze speciaal voor deze gelegenheid hosten.
Derde optie: een bestand uit de Files API
Een afbeelding die al is geüpload naar de xAI Files API, geeft u op via de identifier in plaats van een URL. De twee velden sluiten elkaar uit: een image-object bevat ofwel url ofwel file_id.
payload = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": {"file_id": "file_abc123"}
}
Dit is de natuurlijke keuze voor een afbeelding die bij meerdere bewerkingen wordt hergebruikt: deze wordt slechts één keer verzonden en hoeft niet openbaar te zijn.
Hulpfunctie
Hier is een functie die beide indelingen automatisch afhandelt:
import base64
import os
def prepare_image_source(source):
"""Prepares an image source for the API (URL or local file)."""
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"Invalid source: {source}")
Deze functie detecteert automatisch of de bron een URL of een lokaal bestandspad is en formatteert het object dienovereenkomstig.
Oefening in de praktijk
Test beide indelingen met dezelfde afbeelding en prompt om te verifiëren dat beide paden werken; de resulterende afbeeldingen variëren per uitvoering, zoals bij elke generatie:
# Via URL
payload_url = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": {"url": "https://exemple.com/paysage.jpg"}
}
# Via Base64
payload_b64 = {
"model": "grok-imagine-image",
"prompt": "Add snow to the landscape",
"image": prepare_image_source("paysage.jpg")
}
Belangrijkste punten
- Drie invoervormen: openbare URL, Base64 Data URI of
file_iduit de Files API - Tijdelijke URL’s die door de API worden teruggegeven, kunnen als bron voor bewerkingen dienen
- Base64 vergroot de payload met ongeveer 33%
- Maak een hulpfunctie om beide indelingen automatisch af te handelen
- De URL moet openbaar toegankelijk zijn om te werken