Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

input_image proti image_url: dva sintaksi

Lekcija 12 od 12 Posodobljeno 30. julij 2026 Začetnik
Na tej strani
  1. Dva API-ja, dve sintaksi
  2. API za odgovore (Responses API): input_image (priporočeno)
  3. API Chat Completions: image_url (starejši)
  4. Primerjalna tabela
  5. Pogoste sintaktične napake
  6. Kdaj uporabiti kateri API
  7. Ključne ugotovitve
  8. Preveri svoje znanje

Dva API-ja, dve sintaksi

xAI ponuja dve končni točki za interakcijo z Grokom, pri čemer vsaka uporablja drugačno sintakso za pošiljanje slik. Razumevanje teh razlik je ključno za pisanje pravilne kode in izogibanje frustrirajočim napakam.

API za odgovore (Responses API): input_image (priporočeno)

API za odgovore je nova glavna končna točka xAI. Nove funkcije so najprej dodane tukaj. To je API, ki ga moraš dati na prvo mesto pri vsakem novem projektu.

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

Značilnosti

  • Tip je input_image (ne image_url)
  • URL ali Data URI gre neposredno v image_url (brez gnezdenega objekta)
  • detail je na isti ravni kot image_url
  • Besedilo uporablja tip input_text
  • Polje input nadomesti polje messages iz 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)

API Chat Completions: image_url (starejši)

API Chat Completions je starejša končna točka, ki se vzdržuje zaradi združljivosti z obstoječimi SDK-ji OpenAI. Če seliš kodo, napisano za OpenAI, ta API olajša prehod.

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

Značilnosti

  • Tip je image_url (ne input_image)
  • URL se nahaja v gnezdenem objektu image_url.url (dvojno gnezdenje)
  • detail se nahaja znotraj objekta image_url
  • Besedilo uporablja tip text (ne input_text)
  • Sporočila imajo vlogo role (system, user, assistant)

Python z 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)

Primerjalna tabela

Aspekt API Responses Chat Completions
Status Glavni (priporočeno) Starejši (združljivost)
Tip slike input_image image_url
Tip besedila input_text text
URL slike image_url: "..." image_url.url: "..."
Upravljanje stanja Stanjsko (previous_response_id) Brez stanja (ponovno pošlji vse)
Shranjevanje store: true/false Ne (brez stanja)
Orodja na strežniku web_search, x_search, code_interpreter Omejeno

Pogoste sintaktične napake

Napaka 1: Mešanje formatov

# NARARNO — Sintaksa Chat Completions v API-ju Responses
input=[
    {"type": "image_url", "image_url": {"url": "..."}}  # Ne!
]

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

Napaka 2: Pozabljanje gnezdena struktura v Chat Completions

# NARARNO — Neposreden URL v Chat Completions
{"type": "image_url", "image_url": "https://..."}  # Ne!

# PRAVILNO — Gnezden objekt
{"type": "image_url", "image_url": {"url": "https://..."}}  # Da!

Napaka 3: Uporaba “text” namesto “input_text”

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

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

Kdaj uporabiti kateri API

  • Nov projekt: uporabi API za odgovore (Responses API). Omogoča dostop do najnovejših funkcij in shranjevanja pogovorov.
  • Selitev z OpenAI: začni s Chat Completions, da zmanjšaš spremembe v kodi, nato pa postopoma preidi na API za odgovore.
  • Občutljive slike: API za odgovore z store: false ali API Chat Completions (po naravi brez stanja).

Ključne ugotovitve

  • API za odgovore uporablja input_image + input_text, API Chat Completions pa uporablja image_url + text.
  • Struktura URL-ja se razlikuje: neposredna v API-ju Responses, gnezdena v Chat Completions.
  • API za odgovore je priporočena izbira za ves nov razvoj.
  • Nikoli ne mešaj sintaks obeh API-jev v istem zahtevku.
  • Vedno preveri tip objekta (input_image proti image_url), da se izogneš tihih napakam.

Preveri svoje znanje

Vizija API-ja xAI: formati, žetoni, sintakse – je vse na mestu?

1. Kako pošlješ sliko API-ju?

Odgovor: Prek URL-ja ali Base64, v sporočilu z mešano vsebino – ob upoštevanju dokumentiranih omejitev formata in velikosti.

2. Kaj nadzoruje parameter detail (auto, low, high)?

Odgovor: Granularnost analize in stroške: low prihrani žetone za grobe primere uporabe, high maksimira natančnost (OCR, fine podrobnosti), auto pa prepusti odločitev API-ju.

3. Kako se izračuna strošek slike?

Odgovor: V žetonih slike – od 256 do 1792, odvisno od ločljivosti in podrobnosti: prilagajanje velikosti slik in ravni podrobnosti je prvi vzvod za optimizacijo.

4. Kaj omogoča primerjava več slik?

Odgovor: Pošiljanje več slik v enem zahtevku in sklepanje o njih – razlike, evolucije, doslednost – brez omejitve števila slik na zahtevek.

5. input_image ali image_url: kaj izbrati?

Odgovor: input_image je sodobna sintaksa API-ja Responses; image_url ostaja kot dediščina Chat Completions – za novo kodo je sodobna sintaksa obvezna.

Dober format, dobra podrobnost, dobra sintaksa: vizija je vodena kot besedilo – vse do žetona.