input_image vs image_url: de twee syntaxen
Op deze pagina
Twee API’s, twee syntaxen
xAI biedt twee eindpunten voor interactie met Grok, die elk een andere syntaxis gebruiken voor het verzenden van afbeeldingen. Het begrijpen van deze verschillen is essentieel om correcte code te schrijven en frustrerende fouten te voorkomen.
Responses API: input_image (aanbevolen)
De Responses API is het nieuwe primaire eindpunt van xAI. Nieuwe functies worden hier als eerste toegevoegd. Dit is de API die u voor elk nieuw project moet prioriteren.
Syntaxis
{
"model": "grok-4.5",
"store": false,
"input": [
{
"type": "input_image",
"image_url": "https://exemple.com/photo.jpg",
"detail": "high"
},
{
"type": "input_text",
"text": "Describe this image."
}
]
}
Kenmerken
- Het type is
input_image(nietimage_url) - De URL of Data URI staat direct in
image_url(geen genest object) detailstaat op hetzelfde niveau alsimage_url- Tekst gebruikt het type
input_text - De
input-array vervangt demessages-array van Chat Completions
Python SDK
response = client.responses.create(
model="grok-4.5",
input=[
{
"type": "input_image",
"image_url": "https://exemple.com/photo.jpg",
"detail": "high"
},
{
"type": "input_text",
"text": "Describe this image."
}
],
store=False
)
print(response.output_text)
Chat Completions API: image_url (verouderd)
De Chat Completions API is het verouderde eindpunt, onderhouden voor compatibiliteit met bestaande OpenAI SDK’s. Als u code migreert die voor OpenAI is geschreven, maakt deze API de overgang gemakkelijker.
Syntaxis
{
"model": "grok-4.5",
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://exemple.com/photo.jpg",
"detail": "high"
}
},
{
"type": "text",
"text": "Describe this image."
}
]
}
]
}
Kenmerken
- Het type is
image_url(nietinput_image) - De URL staat in een genest
image_url.url-object (dubbele nesting) detailzit binnen hetimage_url-object- Tekst gebruikt het type
text(nietinput_text) - Berichten hebben een
role(system, user, assistant)
Python met OpenAI SDK
from openai import OpenAI
client = OpenAI(
api_key="your-xai-key",
base_url="https://api.x.ai/v1"
)
response = client.chat.completions.create(
model="grok-4.5",
messages=[{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://exemple.com/photo.jpg",
"detail": "high"
}
},
{
"type": "text",
"text": "Describe this image."
}
]
}]
)
print(response.choices[0].message.content)
Vergelijkingstabel
| Aspect | API Responses | Chat Completions |
|---|---|---|
| Status | Primair (aanbevolen) | Verouderd (compatibiliteit) |
| Afbeeldingstype | input_image | image_url |
| Teksttype | input_text | text |
| Afbeeldings-URL | image_url: "..." | image_url.url: "..." |
| Statusbeheer | Stateful (previous_response_id) | Stateless (alles opnieuw verzenden) |
| Opslag | store: true/false | Nee (stateless) |
| Servertools | web_search, x_search, code_interpreter | Beperkt |
Veelvoorkomende syntaxisfouten
Fout 1: Formaten mixen
# VERKEERD — Chat Completions-syntaxis in Responses API
input=[
{"type": "image_url", "image_url": {"url": "..."}} # Nee!
]
# CORRECT — Responses API-syntaxis
input=[
{"type": "input_image", "image_url": "..."} # Ja!
]
Fout 2: Geneste structuur vergeten in Chat Completions
# VERKEERD — Directe URL in Chat Completions
{"type": "image_url", "image_url": "https://..."} # Nee!
# CORRECT — Genest object
{"type": "image_url", "image_url": {"url": "https://..."}} # Ja!
Fout 3: “text” gebruiken in plaats van “input_text”
# VERKEERD — "text"-type in Responses API
input=[
{"type": "text", "text": "Describe."} # Nee!
]
# CORRECT
input=[
{"type": "input_text", "text": "Describe."} # Ja!
]
Wanneer welke API gebruiken
- Nieuw project: gebruik de Responses API. Dit geeft toegang tot de nieuwste functies en gespreksopslag.
- Migreren vanaf OpenAI: begin met Chat Completions om codewijzigingen te minimaliseren, en migreer vervolgens geleidelijk naar de Responses API.
- Gevoelige afbeeldingen: Responses API met
store: falseof Chat Completions API (van nature stateless).
Belangrijkste punten
- Responses API gebruikt
input_image+input_text, Chat Completions API gebruiktimage_url+text - De URL-structuur verschilt: direct in Responses, genest in Chat Completions
- Responses API is de aanbevolen keuze voor alle nieuwe ontwikkeling
- Mix nooit syntaxen van beide API’s in hetzelfde verzoek
- Controleer altijd het objecttype (
input_imagevsimage_url) om stille fouten te voorkomen
Test uw kennis
xAI API-visie: formaten, tokens, syntaxen – is alles op orde?
1. Hoe verzendt u een afbeelding naar de API?
Antwoord: Via URL of Base64, in een bericht met gemengde inhoud – met inachtneming van de gedocumenteerde formaat- en groottebeperkingen.
2. Wat regelt de detail-parameter (auto, low, high)?
Antwoord: Analysegranulariteit en kosten: low bespaart tokens voor grove use cases, high maximaliseert precisie (OCR, fijne details), auto laat de API beslissen.
3. Hoe worden de kosten van een afbeelding berekend?
Antwoord: In afbeeldingstokens – van 256 tot 1792, afhankelijk van resolutie en detail: het aanpassen van uw afbeeldingsgrootte en detailniveau is de eerste optimalisatiehefboom.
4. Wat maakt vergelijking van meerdere afbeeldingen mogelijk?
Antwoord: Het verzenden van meerdere afbeeldingen in één verzoek en daarover redeneren – verschillen, evoluties, consistentie – zonder limiet op het aantal afbeeldingen per verzoek.
5. input_image of image_url: welke kiest u?
Antwoord: input_image is de moderne syntaxis van de Responses API; image_url blijft bestaan als legacy van Chat Completions – voor nieuwe code is de moderne syntaxis verplicht.
Goed formaat, goed detail, goede syntaxis: visie wordt aangestuurd als tekst – tot op de token.