Lähe põhisisu juurde
Eesti— Vali keel
Menüü

input_image vs image_url: kaks süntaksit

Õppetund 12 / 12 Värskendatud 30. juuli 2026 Algajatele
Sellel lehel
  1. Kaks API-d, kaks süntaksit
  2. Responses API: input_image (soovitatav)
  3. Chat Completions API: image_url (pärandvara)
  4. Võrdlustabel
  5. Levinud süntaksivead
  6. Millal kumb API valida
  7. Peamised punktid
  8. Testi oma teadmisi

Kaks API-d, kaks süntaksit

xAI pakub Grokiga suhtlemiseks kahte lõpppunkti ja kumbki kasutab piltide saatmiseks erinevat süntaksit. Nende erinevuste mõistmine on hädavajalik korrektse koodi kirjutamiseks ja tüütute vigade vältimiseks.

Responses API: input_image (soovitatav)

Responses API on xAI uus peamine lõpppunkt. Uued funktsioonid lisatakse esmalt siia. See on API, mida tuleks eelistada kõigis uutes projektides.

Süntaks

{
  "model": "grok-4.5",
  "store": false,
  "input": [
    {
      "type": "input_image",
      "image_url": "https://exemple.com/photo.jpg",
      "detail": "high"
    },
    {
      "type": "input_text",
      "text": "Kirjelda seda pilti."
    }
  ]
}

Omadused

  • Tüüp on input_image (mitte image_url)
  • URL või Data URI läheb otte image_url väljale (pesastatud objekti pole)
  • detail asub samal tasemel kui image_url
  • Tekst kasutab tüüpi input_text
  • Massiiv input asendab Chat Completionsi massiivi messages

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": "Kirjelda seda pilti."
        }
    ],
    store=False
)

print(response.output_text)

Chat Completions API: image_url (pärandvara)

Chat Completions API on pärandvara lõpppunkt, mida hallatakse ühilduvuse tagamiseks olemasolevate OpenAI SDK-dega. Kui migreerid OpenAI jaoks kirjutatud koodi, hõlbustab see API üleminekut.

Süntaks

{
  "model": "grok-4.5",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "https://exemple.com/photo.jpg",
            "detail": "high"
          }
        },
        {
          "type": "text",
          "text": "Kirjelda seda pilti."
        }
      ]
    }
  ]
}

Omadused

  • Tüüp on image_url (mitte input_image)
  • URL asub pesastatud objektis image_url.url (topeltpesastus)
  • detail asub objekti image_url sees
  • Tekst kasutab tüüpi text (mitte input_text)
  • Sõnumitel on roll (system, user, assistant)

Python koos OpenAI SDK-ga

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": "Kirjelda seda pilti."
            }
        ]
    }]
)

print(response.choices[0].message.content)

Võrdlustabel

Aspekt API Responses Chat Completions
Olek Peamine (soovitatav) Pärandvara (ühilduvus)
Pildi tüüp input_image image_url
Teksti tüüp input_text text
Pildi URL image_url: "..." image_url.url: "..."
Oleku haldus Olekuga (previous_response_id) Olekuta (saada kõik uuesti)
Salvestamine store: true/false Ei (olekuta)
Serveri tööriistad web_search, x_search, code_interpreter Piiratud

Levinud süntaksivead

Viga 1: Vormingute segamine

# VALE — Chat Completionsi süntaks Responses API-s
input=[
    {"type": "image_url", "image_url": {"url": "..."}}  # Ei!
]

# ÕIGE — Responses API süntaks
input=[
    {"type": "input_image", "image_url": "..."}  # Jah!
]

Viga 2: Pesastatud struktuuri unustamine Chat Completionsis

# VALE — Otse URL Chat Completionsis
{"type": "image_url", "image_url": "https://..."}  # Ei!

# ÕIGE — Pesastatud objekt
{"type": "image_url", "image_url": {"url": "https://..."}}  # Jah!

Viga 3: “text” kasutamine “input_text” asemel

# VALE — tüüp "text" Responses API-s
input=[
    {"type": "text", "text": "Kirjelda."}  # Ei!
]

# ÕIGE
input=[
    {"type": "input_text", "text": "Kirjelda."}  # Jah!
]

Millal kumb API valida

  • Uus projekt: kasuta Responses API-d. See annab juurdepääsu uusimatele funktsioonidele ja vestluse salvestamisele.
  • Migreerumine OpenAI-st: alusta Chat Completionsist, et minimeerida koodimuudatusi, seejärel migreeru järk-järgult Responses API-le.
  • Tundlikud pildid: Responses API koos parameetriga store: false või Chat Completions API (oma olemuselt olekuta).

Peamised punktid

  • Responses API kasutab input_image + input_text, Chat Completions API kasutab image_url + text
  • URL-i struktuur erineb: Responsesis otsene, Chat Completionsis pesastatud
  • Responses API on soovitatav valik kogu uue arenduse jaoks
  • Ära kunagi sega mõlema API süntakseid samas päringus
  • Kontrolli alati objekti tüüpi (input_image vs image_url), et vältida vaikivaid vigu

Testi oma teadmisi

xAI API nägemus: vormingud, tokenid, süntaksid – kas kõik on paigas?

1. Kuidas saadad pildi API-le?

Vastus: URL-i või Base64 kaudu, segasisulises sõnumis – järgides dokumenteeritud vormingu ja suuruse piiranguid.

2. Mida juhib parameeter detail (auto, low, high)?

Vastus: Analüüsi granulaarsust ja kulu: low säästab tokeneid üldiste kasutusjuhtude jaoks, high maksimeerib täpsust (OCR, peened detailid), auto jätab otsuse API-le.

3. Kuidas arvutatakse pildi hind?

Vastus: Pilditokenites – vahemikus 256 kuni 1792 sõltuvalt eraldusvõimest ja detailist: piltide suuruse ja detailitaseme kohandamine on esimene optimeerimise hoob.

4. Mida võimaldab mitme pildi võrdlus?

Vastus: Mitme pildi saatmist ühes päringus ja nende üle arutlemist – erinevused, arengud, järjepidevus – ilma piiranguta piltide arvule päringu kohta.

5. input_image või image_url: kumb valida?

Vastus: input_image on Responses API kaasaegne süntaks; image_url püsib Chat Completionsi pärandvarana – uue koodi jaoks on kaasaegne süntaks kohustuslik.

Hea vorming, hea detail, hea süntaks: nägemust juhitakse nagu teksti – tokeni täpsusega.