Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

input_image vs image_url: kaksi syntaksia

Oppitunti 12 / 12 Päivitetty 30. heinäkuuta 2026 Aloittelija
Tällä sivulla
  1. Kaksi rajapintaa, kaksi syntaksia
  2. Responses API: input_image (suositeltu)
  3. Chat Completions API: image_url (vanhentunut)
  4. Vertailutaulukko
  5. Yleiset syntaksivirheet
  6. Milloin käyttää kumpaakin rajapintaa
  7. Keskeiset asiat
  8. Testaa tietosi

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 (ei image_url)
  • URL-osoite tai Data URI sijoitetaan suoraan kenttään image_url (ei sisäkkäistä objektia)
  • detail on samalla tasolla kuin image_url
  • Teksti käyttää tyyppiä input_text
  • Taulukko input korvaa Chat Completions -rajapinnan messages-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 (ei input_image)
  • URL-osoite sijaitsee sisäkkäisessä image_url.url-objektissa (kaksoissisäkkäisyys)
  • detail sijaitsee image_url-objektin sisällä
  • Teksti käyttää tyyppiä text (ei input_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: false tai 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_image vs image_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.