Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

input_image vs image_url: Dva typy syntaxe

Lekce 12 z 12 Aktualizováno 30. července 2026 Začátečník
Na této stránce
  1. Dvě API, dvě syntaxe
  2. Responses API: input_image (doporučeno)
  3. Chat Completions API: image_url (starší verze)
  4. Srovnávací tabulka
  5. Časté chyby v syntaxi
  6. Kdy použít které API
  7. Klíčové poznatky
  8. Ověř si své znalosti

Dvě API, dvě syntaxe

xAI nabízí dva koncové body pro interakci s modelem Grok a každý z nich používá odlišnou syntaxi pro odesílání obrázků. Pochopení těchto rozdílů je zásadní pro psaní správného kódu a vyhnutí se frustrujícím chybám.

Responses API: input_image (doporučeno)

Responses API je nový hlavní koncový bod od xAI. Nové funkce jsou zde přidávány jako první. Toto je API, které bys měl upřednostnit pro jakýkoli nový projekt.

Syntaxe

{
  "model": "grok-4.5",
  "store": false,
  "input": [
    {
      "type": "input_image",
      "image_url": "https://exemple.com/photo.jpg",
      "detail": "high"
    },
    {
      "type": "input_text",
      "text": "Popiš tento obrázek."
    }
  ]
}

Charakteristiky

  • Typ je input_image (nikoli image_url)
  • URL nebo Data URI jde přímo do image_url (žádný vnořený objekt)
  • detail se nachází na stejné úrovni jako image_url
  • Text používá typ input_text
  • Pole input nahrazuje 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": "Popiš tento obrázek."
        }
    ],
    store=False
)

print(response.output_text)

Chat Completions API: image_url (starší verze)

Chat Completions API je starší koncový bod, udržovaný pro kompatibilitu s existujícími SDK od OpenAI. Pokud migruješ kód napsaný pro OpenAI, toto API usnadní přechod.

Syntaxe

{
  "model": "grok-4.5",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "https://exemple.com/photo.jpg",
            "detail": "high"
          }
        },
        {
          "type": "text",
          "text": "Popiš tento obrázek."
        }
      ]
    }
  ]
}

Charakteristiky

  • Typ je image_url (nikoli input_image)
  • URL se nachází ve vnořeném objektu image_url.url (dvojí vnoření)
  • detail se nachází uvnitř objektu image_url
  • Text používá typ text (nikoli input_text)
  • Zprávy mají role (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": "Popiš tento obrázek."
            }
        ]
    }]
)

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

Srovnávací tabulka

Aspekt API Responses Chat Completions
Stav Hlavní (doporučeno) Starší (kompatibilita)
Typ obrázku input_image image_url
Typ textu input_text text
URL obrázku image_url: "..." image_url.url: "..."
Správa stavu Stavová (previous_response_id) Bezstavová (odeslat vše znovu)
Ukládání store: true/false Ne (bezstavové)
Nástroje na serveru web_search, x_search, code_interpreter Omezené

Časté chyby v syntaxi

Chyba 1: Míchání formátů

# ŠPATNĚ — Syntaxe Chat Completions v Responses API
input=[
    {"type": "image_url", "image_url": {"url": "..."}}  # Ne!
]

# SPRÁVNĚ — Syntaxe Responses API
input=[
    {"type": "input_image", "image_url": "..."}  # Ano!
]

Chyba 2: Zapomenutí vnořené struktury v Chat Completions

# ŠPATNĚ — Přímá URL v Chat Completions
{"type": "image_url", "image_url": "https://..."}  # Ne!

# SPRÁVNĚ — Vnořený objekt
{"type": "image_url", "image_url": {"url": "https://..."}}  # Ano!

Chyba 3: Použití “text” místo “input_text”

# ŠPATNĚ — Typ "text" v Responses API
input=[
    {"type": "text", "text": "Popiš."}  # Ne!
]

# SPRÁVNĚ
input=[
    {"type": "input_text", "text": "Popiš."}  # Ano!
]

Kdy použít které API

  • Nový projekt: použij Responses API. Poskytuje přístup k nejnovějším funkcím a ukládání konverzací.
  • Migrace z OpenAI: začni s Chat Completions, abys minimalizoval změny v kódu, a poté postupně migruj na Responses API.
  • Citlivé obrázky: Responses API s store: false nebo Chat Completions API (přirozeně bezstavové).

Klíčové poznatky

  • Responses API používá input_image + input_text, Chat Completions API používá image_url + text
  • Struktura URL se liší: přímá v Responses, vnořená v Chat Completions
  • Responses API je doporučená volba pro veškerý nový vývoj
  • Nikdy nemíchej syntaxe z obou API v jedné žádosti
  • Vždy zkontroluj typ objektu (input_image vs image_url), abys předešel tichým chybám

Ověř si své znalosti

Vize API xAI: formáty, tokeny, syntaxe – je vše na místě?

1. Jak odešleš obrázek do API?

Odpověď: Prostřednictvím URL nebo Base64, ve zprávě se smíšeným obsahem – při dodržení zdokumentovaných formátových a velikostních omezení.

2. Co řídí parametr detail (auto, low, high)?

Odpověď: Granularitu analýzy a náklady: low šetří tokeny pro hrubé případy použití, high maximalizuje přesnost (OCR, jemné detaily), auto nechá rozhodnutí na API.

3. Jak se počítají náklady na obrázek?

Odpověď: V obrazových tokenech – od 256 do 1792 v závislosti na rozlišení a detailu: změna velikosti obrázků a úrovně detailu je prvním pákou optimalizace.

4. Co umožňuje porovnávání více obrázků?

Odpověď: Odeslání více obrázků v jedné žádosti a uvažování nad nimi – rozdíly, vývoj, konzistence – bez omezení počtu obrázků na žádost.

5. input_image nebo image_url: co vybrat?

Odpověď: input_image je moderní syntaxe Responses API; image_url přetrvává jako starší verze Chat Completions – pro nový kód je moderní syntaxe povinná.

Správný formát, správný detail, správná syntaxe: vize se řídí jako text – až na úroveň tokenu.