Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

input_image vs image_url: dvi sintaksės

Paskaita 12 iš 12 Atnaujinta 2026 m. liepos 30 d. Pradedantisiems
Šiame puslapyje
  1. Dvi API, dvi sintaksės
  2. Responses API: input_image (rekomenduojama)
  3. Chat Completions API: image_url (senoji versija)
  4. Palyginimo lentelė
  5. Dažnos sintaksės klaidos
  6. Kada naudoti kurį API
  7. Svarbiausi punktai
  8. Patikrink savo žinias

Dvi API, dvi sintaksės

xAI siūlo du galinius taškus (endpoints) darbui su „Grok“, ir kiekvienas naudoja skirtingą vaizdų siuntimo sintaksę. Suprasti šiuos skirtumus yra būtina norint rašyti teisingą kodą ir išvengti varginančių klaidų.

Responses API: input_image (rekomenduojama)

Responses API yra naujas pagrindinis xAI galinis taškas. Naujos funkcijos pirmiausia diegiamos čia. Tai API, kurį turėtum pasirinkti bet kokiam naujam projektui.

Sintaksė

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

Charakteristikos

  • Tipas yra input_image (ne image_url)
  • URL arba duomenų URI (Data URI) įrašomas tiesiai į image_url (be įdėto objekto)
  • detail yra tame pačiame lygmenyje kaip ir image_url
  • Tekstui naudojamas input_text tipas
  • Masyvas input pakeičia masyvą messages iš „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 (senoji versija)

„Chat Completions“ API yra senasis galinis taškas, palaikomas dėl suderinamumo su esamais „OpenAI“ SDK. Jei perkeli kodą, parašytą „OpenAI“, šis API palengvina perėjimą.

Sintaksė

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

Charakteristikos

  • Tipas yra image_url (ne input_image)
  • URL yra įdėtame image_url.url objekte (dvigubas įdėjimas)
  • detail yra image_url objekto viduje
  • Tekstui naudojamas text tipas (ne input_text)
  • Žinutės turi role (system, user, assistant)

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

Palyginimo lentelė

Aspektas API Responses Chat Completions
Būsena Pirminė (rekomenduojama) Senoji (suderinamumui)
Vaizdo tipas input_image image_url
Teksto tipas input_text text
Vaizdo URL image_url: "..." image_url.url: "..."
Būsenos valdymas Su būsena (previous_response_id) Be būsenos (siųsti viską iš naujo)
Saugojimas store: true/false Ne (be būsenos)
Serverio įrankiai web_search, x_search, code_interpreter Riboti

Dažnos sintaksės klaidos

1 klaida: Formatų maišymas

# NETEISINGA — Chat Completions sintaksė Responses API
input=[
    {"type": "image_url", "image_url": {"url": "..."}}  # Ne!
]

# TEISINGA — Responses API sintaksė
input=[
    {"type": "input_image", "image_url": "..."}  # Taip!
]

2 klaida: Pamiršta įdėta struktūra „Chat Completions“

# NETEISINGA — Tiesioginis URL „Chat Completions“
{"type": "image_url", "image_url": "https://..."}  # Ne!

# TEISINGA — Įdėtas objektas
{"type": "image_url", "image_url": {"url": "https://..."}}  # Taip!

3 klaida: Naudojamas „text“ vietoj „input_text“

# NETEISINGA — „text“ tipas Responses API
input=[
    {"type": "text", "text": "Describe."}  # Ne!
]

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

Kada naudoti kurį API

  • Naujas projektas: naudok Responses API. Jis suteikia prieigą prie naujausių funkcijų ir pokalbių saugojimo.
  • Perkėlimas iš „OpenAI“: pradėk nuo „Chat Completions“, kad sumažintum kodo pakeitimus, o tada palaipsniui pereik prie Responses API.
  • Jautrūs vaizdai: Responses API su store: false arba „Chat Completions“ API (iš prigimties be būsenos).

Svarbiausi punktai

  • Responses API naudoja input_image + input_text, o „Chat Completions“ API naudoja image_url + text.
  • URL struktūra skiriasi: tiesioginė „Responses“, įdėta – „Chat Completions“.
  • Responses API yra rekomenduojamas pasirinkimas visai naujai kūrybai.
  • Niekada nemaišyk abiejų API sintaksių tame pačiame užklausos prašyme.
  • Visada tikrink objekto tipą (input_image prieš image_url), kad išvengtum paslėptų klaidų.

Patikrink savo žinias

xAI API regėjimas: formatai, tokenai, sintaksės – ar viskas savo vietose?

1. Kaip siunčiamas vaizdas į API?

Atsakymas: Per URL arba Base64, mišraus turinio žinutėje – laikantis dokumentuotų formato ir dydžio apribojimų.

2. Ką kontroliuoja parametras detail (auto, low, high)?

Atsakymas: Analizės granuliariškumą ir kainą: low taupo tokenus bendriems atvejams, high maksimaliai padidina tikslumą (OCR, smulkios detalės), auto leidžia API nuspręsti.

3. Kaip apskaičiuojama vaizdo kaina?

Atsakymas: Vaizdo tokenais – nuo 256 iki 1792, priklausomai nuo skiriamosios gebos ir detalumo lygio: vaizdų dydžio ir detalumo lygio parinkimas yra pirmasis optimizavimo svertas.

4. Ką leidžia daryti kelių vaizdų palyginimas?

Atsakymas: Siųsti kelis vaizdus viename prašyme ir atlikti jų analizę – skirtumus, pokyčius, nuoseklumą – be jokio vaizdų skaičiaus ribojimo viename prašyme.

5. input_image ar image_url: ką pasirinkti?

Atsakymas: input_image yra šiuolaikinė Responses API sintaksė; image_url išlieka kaip „Chat Completions“ palikimas – naujam kodui privaloma naudoti šiuolaikinę sintaksę.

Geras formatas, geras detalumas, gera sintaksė: regėjimas valdomas kaip tekstas – iki pat tokeno.