input_image kontra image_url: De två syntaxerna
På denna sida
Två API:er, två syntaxer
xAI erbjuder två slutpunkter för att interagera med Grok, och var och en använder en annan syntax för att skicka bilder. Att förstå dessa skillnader är avgörande för att skriva korrekt kod och undvika frustrerande fel.
Responses API: input_image (rekommenderas)
Responses API är xAI:s nya primära slutpunkt. Nya funktioner lanseras här först. Detta är det API du bör prioritera för alla nya projekt.
Syntax
{
"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."
}
]
}
Egenskaper
- Typen är
input_image(inteimage_url) - URL:en eller Data URI:n placeras direkt i
image_url(inget nästlat objekt) detailfinns på samma nivå somimage_url- Text använder typen
input_text - Arrayen
inputersätter arrayenmessagesfrån 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 (föråldrat)
Chat Completions API är den föråldrade slutpunkten, som underhålls för kompatibilitet med befintliga OpenAI SDK:er. Om du migrerar kod som skrivits för OpenAI underlättar detta API övergången.
Syntax
{
"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."
}
]
}
]
}
Egenskaper
- Typen är
image_url(inteinput_image) - URL:en finns i ett nästlat
image_url.url-objekt (dubbel nästling) detailfinns inutiimage_url-objektet- Text använder typen
text(inteinput_text) - Meddelanden 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)
Jämförelsetabell
| Aspekt | API Responses | Chat Completions |
|---|---|---|
| Status | Primär (rekommenderas) | Föråldrad (kompatibilitet) |
| Bildtyp | input_image | image_url |
| Texttyp | input_text | text |
| Bild-URL | image_url: "..." | image_url.url: "..." |
| Tillståndshantering | Med tillstånd (previous_response_id) | Utan tillstånd (skicka allt på nytt) |
| Lagring | store: true/false | Nej (utan tillstånd) |
| Serververktyg | web_search, x_search, code_interpreter | Begränsat |
Vanliga syntaxfel
Fel 1: Blanda format
# FEL – Chat Completions-syntax i Responses API
input=[
{"type": "image_url", "image_url": {"url": "..."}} # Nej!
]
# KORREKT – Responses API-syntax
input=[
{"type": "input_image", "image_url": "..."} # Ja!
]
Fel 2: Glömma den nästlade strukturen i Chat Completions
# FEL – Direkt URL i Chat Completions
{"type": "image_url", "image_url": "https://..."} # Nej!
# KORREKT – Nästlat objekt
{"type": "image_url", "image_url": {"url": "https://..."}} # Ja!
Fel 3: Använda “text” istället för “input_text”
# FEL – "text"-typ i Responses API
input=[
{"type": "text", "text": "Describe."} # Nej!
]
# KORREKT
input=[
{"type": "input_text", "text": "Describe."} # Ja!
]
När ska du använda vilket API?
- Nytt projekt: använd Responses API. Det ger tillgång till de senaste funktionerna och konversationslagring.
- Migrering från OpenAI: börja med Chat Completions för att minimera kodändringar, migrera sedan gradvis till Responses API.
- Känsliga bilder: Responses API med
store: falseeller Chat Completions API (naturligt utan tillstånd).
Viktiga punkter
- Responses API använder
input_image+input_text, medan Chat Completions API använderimage_url+text - URL-strukturen skiljer sig: direkt i Responses, nästlad i Chat Completions
- Responses API är det rekommenderade valet för all ny utveckling
- Blanda aldrig syntax från båda API:erna i samma begäran
- Kontrollera alltid objekttypen (
input_imagekontraimage_url) för att undvika tysta fel
Testa dina kunskaper
xAI API vision: format, tokens, syntaxer – är allt på plats?
1. Hur skickar du en bild till API:t?
Svar: Via URL eller Base64, i ett meddelande med blandat innehåll – med respekt för dokumenterade format- och storleksbegränsningar.
2. Vad styr parametern detail (auto, low, high)?
Svar: Analysgranularitet och kostnad: low sparar tokens för grova användningsfall, high maximerar precision (OCR, fina detaljer), auto låter API:t besluta.
3. Hur beräknas kostnaden för en bild?
Svar: I bildtokens – från 256 till 1792 beroende på upplösning och detailjnivå: att anpassa dina bildstorlekar och din detailjnivå är den första optimeringshävstången.
4. Vad möjliggör jämförelse av flera bilder?
Svar: Att skicka flera bilder i en enda begäran och resonera kring dem – skillnader, utveckling, konsekvens – utan gräns för antalet bilder per begäran.
5. input_image eller image_url: vilket ska du välja?
Svar: input_image är den moderna syntaxen för Responses API; image_url finns kvar som legacy för Chat Completions – för ny kod är den moderna syntaxen obligatorisk.
Bra format, bra detaljnivå, bra syntax: vision styrs precis som text – ända ner till token.