Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

input_image naspram image_url: dvije sintakse

Lekcija 12 od 12 Ažurirano 30. srpnja 2026. Početnik
Na ovoj stranici
  1. Dva API-ja, dvije sintakse
  2. Responses API: input_image (preporučeno)
  3. Chat Completions API: image_url (zastarjelo)
  4. Tablica usporedbe
  5. Uobičajene sintaksne pogreške
  6. Kada koristiti koji API
  7. Ključne točke
  8. Provjeri svoje znanje

Dva API-ja, dvije sintakse

xAI nudi dvije krajnje točke (endpoints) za interakciju s Grokom, a svaka koristi različitu sintaksu za slanje slika. Razumijevanje ovih razlika ključno je za pisanje ispravnog koda i izbjegavanje frustrirajućih pogrešaka.

Responses API: input_image (preporučeno)

Responses API je nova glavna krajnja točka tvrtke xAI. Nove funkcije prvo se dodaju ovdje. Ovo je API koji trebaš prioritizirati za svaki novi projekt.

Sintaksa

{
  "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."
    }
  ]
}

Karakteristike

  • Tip je input_image (ne image_url)
  • URL ili Data URI ide izravno u image_url (bez ugniježđenog objekta)
  • detail se nalazi na istoj razini kao image_url
  • Tekst koristi tip input_text
  • Niz input zamjenjuje niz messages iz Chat Completionsa

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 (zastarjelo)

Chat Completions API je zastarjela krajnja točka, održavana radi kompatibilnosti s postojećim OpenAI SDK-ovima. Ako migriraš kod napisan za OpenAI, ovaj API olakšava prijelaz.

Sintaksa

{
  "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."
        }
      ]
    }
  ]
}

Karakteristike

  • Tip je image_url (ne input_image)
  • URL se nalazi u ugniježđenom objektu image_url.url (dvostruko ugnježđivanje)
  • detail se nalazi unutar objekta image_url
  • Tekst koristi tip text (ne input_text)
  • Poruke imaju role (system, user, assistant)

Python s OpenAI SDK-om

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)

Tablica usporedbe

Aspekt API Responses Chat Completions
Status Glavni (preporučeno) Zastarjeli (kompatibilnost)
Tip slike input_image image_url
Tip teksta input_text text
URL slike image_url: "..." image_url.url: "..."
Upravljanje stanjem Stanje sačuvano (previous_response_id) Bez stanja (ponovno slanje svega)
Pohrana store: true/false Ne (bez stanja)
Alati na poslužitelju web_search, x_search, code_interpreter Ograničeno

Uobičajene sintaksne pogreške

Pogreška 1: Miješanje formata

# KRIVO — Sintaksa Chat Completionsa u Responses API-ju
input=[
    {"type": "image_url", "image_url": {"url": "..."}}  # Ne!
]

# ISPRAVNO — Sintaksa Responses API-ja
input=[
    {"type": "input_image", "image_url": "..."}  # Da!
]

Pogreška 2: Zaboravljanje ugniježđene strukture u Chat Completionsu

# KRIVO — Izravan URL u Chat Completionsu
{"type": "image_url", "image_url": "https://..."}  # Ne!

# ISPRAVNO — Ugniježđeni objekt
{"type": "image_url", "image_url": {"url": "https://..."}}  # Da!

Pogreška 3: Korištenje “text” umjesto “input_text”

# KRIVO — Tip "text" u Responses API-ju
input=[
    {"type": "text", "text": "Describe."}  # Ne!
]

# ISPRAVNO
input=[
    {"type": "input_text", "text": "Describe."}  # Da!
]

Kada koristiti koji API

  • Novi projekt: koristi Responses API. On daje pristup najnovijim funkcijama i pohrani razgovora.
  • Migracija s OpenAI-ja: započni s Chat Completionsom kako bi minimizirao promjene koda, zatim postupno migriraj na Responses API.
  • Osjetljive slike: Responses API s store: false ili Chat Completions API (po prirodi bez stanja).

Ključne točke

  • Responses API koristi input_image + input_text, dok Chat Completions API koristi image_url + text
  • Struktura URL-a se razlikuje: izravna u Responsesu, ugniježđena u Chat Completionsu
  • Responses API je preporučeni izbor za sav novi razvoj
  • Nikada ne miješaj sintakse oba API-ja u istom zahtjevu
  • Uvijek provjeri tip objekta (input_image naspram image_url) kako bi izbjegao tihe pogreške

Provjeri svoje znanje

xAI API vizija: formati, tokeni, sintakse — je li sve na mjestu?

1. Kako šalješ sliku API-ju?

Odgovor: Putem URL-a ili Base64 formata, u poruci mješovitog sadržaja — poštujući dokumentirana ograničenja formata i veličine.

2. Što kontrolira parametar detail (auto, low, high)?

Odgovor: Granularnost analize i trošak: low štedi tokene za grublje slučajeve uporabe, high maksimizira preciznost (OCR, fini detalji), auto prepušta odluku API-ju.

3. Kako se izračunava trošak slike?

Odgovor: U tokenima slike — od 256 do 1792, ovisno o razlučivosti i detalju: prilagodba veličine slika i razine detalja prvi je poluga optimizacije.

4. Što omogućuje usporedba više slika?

Odgovor: Slanje više slika u jednom zahtjevu i rezoniranje nad njima — razlike, evolucije, dosljednost — bez ograničenja broja slika po zahtjevu.

5. input_image ili image_url: što odabrati?

Odgovor: input_image je moderna sintaksa Responses API-ja; image_url ostaje kao naslijeđe Chat Completionsa — za novi kod, moderna sintaksa je obavezna.

Dobar format, dobar detalj, dobra sintaksa: vizija se upravlja poput teksta — sve do tokena.