input_image vs image_url: kaksi syntaksia
Tällä sivulla
Kaksi rajapintaa, kaksi syntaksia
xAI tarjoaa kaksi päätepistettä Grokin kanssa vuorovaikuttamiseen, ja kumpikin käyttää erilaista syntaksia kuvien lähettämiseen. Näiden erojen ymmärtäminen on välttämätöntä oikean koodin kirjoittamiseksi ja turhauttavien virheiden välttämiseksi.
Responses API: input_image (suositeltu)
Responses API on xAI:n uusi ensisijainen päätepiste. Uudet ominaisuudet julkaistaan tänne ensimmäisenä. Tämä on rajapinta, joka kannattaa valita kaikille uusille projekteille.
Syntaksi
{
"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."
}
]
}
Ominaisuudet
- Tyyppi on
input_image(eiimage_url) - URL-osoite tai Data URI sijoitetaan suoraan kenttään
image_url(ei sisäkkäistä objektia) detailon samalla tasolla kuinimage_url- Teksti käyttää tyyppiä
input_text - Taulukko
inputkorvaa Chat Completions -rajapinnanmessages-taulukon
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 (vanhentunut)
Chat Completions API on vanhentunut päätepiste, jota ylläpidetään yhteensopivuuden vuoksi olemassa olevien OpenAI SDK:iden kanssa. Jos siirrät Openaille kirjoitettua koodia, tämä rajapinta helpottaa siirtymää.
Syntaksi
{
"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."
}
]
}
]
}
Ominaisuudet
- Tyyppi on
image_url(eiinput_image) - URL-osoite sijaitsee sisäkkäisessä
image_url.url-objektissa (kaksoissisäkkäisyys) detailsijaitseeimage_url-objektin sisällä- Teksti käyttää tyyppiä
text(eiinput_text) - Viesteillä on
role(system, user, assistant)
Python OpenAI SDK:lla
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)
Vertailutaulukko
| Näkökulma | Responses API | Chat Completions |
|---|---|---|
| Tila | Ensisijainen (suositeltu) | Vanhentunut (yhteensopivuus) |
| Kuvatyyppi | input_image | image_url |
| Tekstityyppi | input_text | text |
| Kuvan URL | image_url: "..." | image_url.url: "..." |
| Tilan hallinta | Tilallinen (previous_response_id) | Tilaton (lähetä kaikki uudelleen) |
| Tallennus | store: true/false | Ei (tilaton) |
| Palvelimen työkalut | web_search, x_search, code_interpreter | Rajoitettu |
Yleiset syntaksivirheet
Virhe 1: Muotojen sekoittaminen
# VÄÄRIN — Chat Completions -syntaksi Responses API:ssa
input=[
{"type": "image_url", "image_url": {"url": "..."}} # Ei!
]
# OIKEIN — Responses API -syntaksi
input=[
{"type": "input_image", "image_url": "..."} # Kyllä!
]
Virhe 2: Sisäkkäisen rakenteen unohtaminen Chat Completionsissa
# VÄÄRIN — Suora URL Chat Completionsissa
{"type": "image_url", "image_url": "https://..."} # Ei!
# OIKEIN — Sisäkkäinen objekti
{"type": "image_url", "image_url": {"url": "https://..."}} # Kyllä!
Virhe 3: “text”-tyypin käyttö “input_text”:n sijaan
# VÄÄRIN — "text"-tyyppi Responses API:ssa
input=[
{"type": "text", "text": "Describe."} # Ei!
]
# OIKEIN
input=[
{"type": "input_text", "text": "Describe."} # Kyllä!
]
Milloin käyttää kumpaakin rajapintaa
- Uusi projekti: käytä Responses API:a. Se tarjoaa pääsyn uusimpiin ominaisuuksiin ja keskustelujen tallennukseen.
- Siirtyminen OpenAI:sta: aloita Chat Completionsilla koodimuutosten minimoimiseksi, ja siirry vähitellen Responses API:in.
- Arkaluonteiset kuvat: Responses API asetuksella
store: falsetai Chat Completions API (luonnostaan tilaton).
Keskeiset asiat
- Responses API käyttää
input_image+input_text, Chat Completions API käyttääimage_url+text - URL-rakenne eroaa: suora Responsesissa, sisäkkäinen Chat Completionsissa
- Responses API on suositeltu valinta kaikkeen uuteen kehitykseen
- Älä koskaan sekoita molempien rajapintojen syntakseja samassa pyynnössä
- Tarkista aina objektityyppi (
input_imagevsimage_url) välttääksesi hiljaisia virheitä
Testaa tietosi
xAI API vision: formaatit, tokenit, syntaksit – onko kaikki kunnossa?
1. Miten lähetät kuvan rajapinnalle?
Vastaus: URL-osoitteen tai Base64:n kautta sekasisältöviestissä – noudattaen dokumentoituja formaatti- ja kokorajoituksia.
2. Mitä detail-parametri (auto, low, high) ohjaa?
Vastaus: Analyysin tarkkuutta ja kustannuksia: low säästää tokeneita karkeissa käyttötapauksissa, high maksimoi tarkkuuden (OCR, hienot yksityiskohdat), auto antaa rajapinnan päättää.
3. Miten kuvan kustannus lasketaan?
Vastaus: Kuvatokeneina – 256–1792 riippuen resoluutiosta ja detail-tasosta: kuvien koon ja detail-tason optimointi on ensimmäinen tehostamisvipu.
4. Mitä usean kuvan vertailu mahdollistaa?
Vastaus: Useiden kuvien lähettämisen yhdessä pyynnössä ja niiden yli päättelyn – erot, kehitys, johdonmukaisuus – ilman rajoitusta kuvien määrälle pyyntöä kohden.
5. input_image vai image_url: kumpi valita?
Vastaus: input_image on Responses API:n moderni syntaksi; image_url säilyy Chat Completionsin vanhentuneena versiona – uuteen koodiin modernin syntaksin käyttö on pakollista.
Hyvä formaatti, hyvä detail, hyvä syntaksi: visiota ohjataan kuin tekstiä – token tarkkuudella.