input_image vs image_url: De to syntakser
På denne side
To API’er, to syntakser
xAI tilbyder to endpoints til interaktion med Grok, og hver bruger en forskellig syntaks til at sende billeder. Det er afgørende at forstå disse forskelle for at skrive korrekt kode og undgå frustrerende fejl.
Responses API: input_image (anbefalet)
Responses API er xAI’s nye primære endpoint. Nye funktioner tilføjes her først. Dette er det API, du bør prioritere til ethvert nyt projekt.
Syntaks
{
"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."
}
]
}
Egenskaber
- Typen er
input_image(ikkeimage_url) - URL’en eller Data URI’en placeres direkte i
image_url(ingen indlejret objekt) detailsidder på samme niveau somimage_url- Tekst bruger typen
input_text input-arrayet erstattermessages-arrayet fra 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 (forældet)
Chat Completions API er det forældede endpoint, som vedligeholdes for kompatibilitet med eksisterende OpenAI SDK’er. Hvis du migrerer kode skrevet til OpenAI, letter dette API overgangen.
Syntaks
{
"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."
}
]
}
]
}
Egenskaber
- Typen er
image_url(ikkeinput_image) - URL’en sidder i et indlejret
image_url.url-objekt (dobbelt indlejring) detailbefinder sig inde iimage_url-objektet- Tekst bruger typen
text(ikkeinput_text) - Beskeder har en
role(system, user, assistant)
Python med 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)
Sammenligningstabel
| Aspekt | API Responses | Chat Completions |
|---|---|---|
| Status | Primær (anbefalet) | Forældet (kompatibilitet) |
| Billedtype | input_image | image_url |
| Teksttype | input_text | text |
| Billed-URL | image_url: "..." | image_url.url: "..." |
| Tilstandsstyring | Stateful (previous_response_id) | Stateless (gensend alt) |
| Lagring | store: true/false | Nej (stateless) |
| Serverværktøjer | web_search, x_search, code_interpreter | Begrænset |
Almindelige syntaksfejl
Fejl 1: Blanding af formater
# Forkert — Chat Completions-syntaks i Responses API
input=[
{"type": "image_url", "image_url": {"url": "..."}} # Nej!
]
# Korrekt — Responses API-syntaks
input=[
{"type": "input_image", "image_url": "..."} # Ja!
]
Fejl 2: Glemmer indlejret struktur i Chat Completions
# Forkert — Direkte URL i Chat Completions
{"type": "image_url", "image_url": "https://..."} # Nej!
# Korrekt — Indlejret objekt
{"type": "image_url", "image_url": {"url": "https://..."}} # Ja!
Fejl 3: Brug af “text” i stedet for “input_text”
# Forkert — "text"-type i Responses API
input=[
{"type": "text", "text": "Describe."} # Nej!
]
# Korrekt
input=[
{"type": "input_text", "text": "Describe."} # Ja!
]
Hvornår skal du bruge hvilket API?
- Nyt projekt: Brug Responses API. Det giver adgang til de nyeste funktioner og samtalelagring.
- Migration fra OpenAI: Start med Chat Completions for at minimere kodeændringer, og migrer derefter gradvist til Responses API.
- Følsomme billeder: Responses API med
store: falseeller Chat Completions API (naturligt stateless).
Vigtige pointer
- Responses API bruger
input_image+input_text, mens Chat Completions API brugerimage_url+text - URL-strukturen er forskellig: direkte i Responses, indlejret i Chat Completions
- Responses API er det anbefalede valg til al ny udvikling
- Bland aldrig syntakser fra begge API’er i den samme anmodning
- Tjek altid objekttypen (
input_imagevsimage_url) for at undgå stille fejl
Test din viden
xAI API vision: formater, tokens, syntakser – er alt på plads?
1. Hvordan sender du et billede til API'et?
Svar: Via URL eller Base64, i en besked med blandet indhold – under overholdelse af dokumenterede format- og størrelsesbegrænsninger.
2. Hvad styrer detail-parameteren (auto, low, high)?
Svar: Analysegranularitet og omkostninger: low sparer tokens til grove use cases, high maksimerer præcision (OCR, fine detaljer), auto lader API’et beslutte.
3. Hvordan beregnes omkostningerne for et billede?
Svar: I billed-tokens – fra 256 til 1792 afhængigt af opløsning og detail: at skalere dine billeder og dit detail-niveau er den første optimeringshåndtag.
4. Hvad muliggør sammenligning af flere billeder?
Svar: At sende flere billeder i en enkelt anmodning og ræsonnere over dem – forskelle, udviklinger, konsistens – uden begrænsning på antallet af billeder pr. anmodning.
5. input_image eller image_url: hvilken skal du vælge?
Svar: input_image er den moderne syntaks i Responses API; image_url eksisterer fortsat som Chat Completions-arv – til ny kode er den moderne syntaks obligatorisk.
Godt format, god detail, god syntaks: vision styres ligesom tekst – helt ned til token-niveau.