Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

input_image vs image_url: Dve syntaxe

Lekcia 12 z 12 Aktualizované 30. júla 2026 Začiatočník
Na tejto strane
  1. Dve API, dve syntaxe
  2. Responses API: input_image (odporúčané)
  3. Chat Completions API: image_url (staršie)
  4. Porovnávacia tabuľka
  5. Časté chyby v syntaxi
  6. Kedy použiť ktoré API
  7. Kľúčové poznatky
  8. Otestuj si svoje vedomosti

Dve API, dve syntaxe

xAI ponúka dva koncové body pre interakciu s Grokom a každý z nich používa odlišnú syntax na odosielanie obrázkov. Pochopenie týchto rozdielov je kľúčové pre písanie správneho kódu a vyhnutie sa frustrujúcim chybám.

Responses API: input_image (odporúčané)

Responses API je nový hlavný koncový bod xAI. Nové funkcie sa pridávajú najprv sem. Toto je API, ktoré by si mal uprednostniť pri akomkoľvek novom projekte.

Syntax

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

Charakteristika

  • Typ je input_image (nie image_url)
  • URL alebo Data URI ide priamo do image_url (žiadny vnorený objekt)
  • detail sa nachádza na rovnakej úrovni ako image_url
  • Text používa typ input_text
  • Pole input nahrádza pole messages z 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)

Chat Completions API: image_url (staršie)

Chat Completions API je starší koncový bod, udržiavaný pre kompatibilitu s existujúcimi SDK OpenAI. Ak migruješ kód napísaný pre OpenAI, toto API uľahčí prechod.

Syntax

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

Charakteristika

  • Typ je image_url (nie input_image)
  • URL sa nachádza vo vnorenom objekte image_url.url (dvojité vnorenie)
  • detail sa nachádza vo vnútri objektu image_url
  • Text používa typ text (nie input_text)
  • Správy majú rolu (system, user, assistant)

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

Porovnávacia tabuľka

Aspekt API Responses Chat Completions
Stav Hlavné (odporúčané) Staršie (kompatibilita)
Typ obrázka input_image image_url
Typ textu input_text text
URL obrázka image_url: "..." image_url.url: "..."
Správa stavu Stavové (previous_response_id) Bezstavové (odoslať všetko znova)
Ukladanie store: true/false Nie (bezstavové)
Nástroje na strane servera web_search, x_search, code_interpreter Obmedzené

Časté chyby v syntaxi

Chyba 1: Miešanie formátov

# ZLE — Syntax Chat Completions v Responses API
input=[
    {"type": "image_url", "image_url": {"url": "..."}}  # Nie!
]

# SPRÁVNE — Syntax Responses API
input=[
    {"type": "input_image", "image_url": "..."}  # Áno!
]

Chyba 2: Zabudnutie na vnorenú štruktúru v Chat Completions

# ZLE — Priame URL v Chat Completions
{"type": "image_url", "image_url": "https://..."}  # Nie!

# SPRÁVNE — Vnorený objekt
{"type": "image_url", "image_url": {"url": "https://..."}}  # Áno!

Chyba 3: Použitie “text” namiesto “input_text”

# ZLE — Typ "text" v Responses API
input=[
    {"type": "text", "text": "Describe."}  # Nie!
]

# SPRÁVNE
input=[
    {"type": "input_text", "text": "Describe."}  # Áno!
]

Kedy použiť ktoré API

  • Nový projekt: použi Responses API. Poskytuje prístup k najnovším funkciám a ukladaniu konverzácií.
  • Migrácia z OpenAI: začni s Chat Completions, aby si minimalizoval zmeny v kóde, a následne postupne migruj na Responses API.
  • Citlivé obrázky: Responses API s store: false alebo Chat Completions API (prirodzene bezstavové).

Kľúčové poznatky

  • Responses API používa input_image + input_text, Chat Completions API používa image_url + text
  • Štruktúra URL sa líši: priama v Responses, vnorená v Chat Completions
  • Responses API je odporúčanou voľbou pre všetok nový vývoj
  • Nikdy nemiešaj syntaxe z oboch API v jednej požiadavke
  • Vždy skontroluj typ objektu (input_image vs image_url), aby si sa vyhol tichým chybám

Otestuj si svoje vedomosti

Vízia API xAI: formáty, tokeny, syntaxe – je všetko na mieste?

1. Ako odošleš obrázok do API?

Odpoveď: Prostredníctvom URL alebo Base64, v správe so zmiešaným obsahom – pri dodržaní zdokumentovaných obmedzení formátu a veľkosti.

2. Čo riadi parameter detail (auto, low, high)?

Odpoveď: Granularitu analýzy a náklady: low šetrí tokeny pre hrubšie prípady použitia, high maximalizuje presnosť (OCR, jemné detaily), auto nechá rozhodnúť API.

3. Ako sa vypočítavajú náklady na obrázok?

Odpoveď: V obrazových tokenoch – od 256 do 1792 v závislosti od rozlíšenia a detailu: zmenšovanie veľkosti obrázkov a úroveň detailu je prvým pákou optimalizácie.

4. Čo umožňuje porovnávanie viacerých obrázkov?

Odpoveď: Odoslanie viacerých obrázkov v jednej požiadavke a uvažovanie nad nimi – rozdiely, vývoj, konzistencia – bez obmedzenia počtu obrázkov na požiadavku.

5. input_image alebo image_url: čo si vybrať?

Odpoveď: input_image je moderná syntax Responses API; image_url pretrváva ako staršie riešenie Chat Completions – pre nový kód je moderná syntax povinná.

Správny formát, správny detail, správna syntax: vízia sa riadi ako text – až po token.