Salt la conținutul principal
Română— Alege o limbă
Meniu

input_image vs image_url: Cele două sintaxe

Lecția 12 din 12 Actualizată 30 iulie 2026 Începător
Pe această pagină
  1. Două API-uri, două sintaxe
  2. API-ul Responses: input_image (recomandat)
  3. API-ul Chat Completions: image_url (vechi)
  4. Tabel comparativ
  5. Erori frecvente de sintaxă
  6. Când să utilizați fiecare API
  7. Puncte cheie
  8. Testați-vă cunoștințele

Două API-uri, două sintaxe

xAI oferă două puncte de terminare (endpoints) pentru interacțiunea cu Grok, iar fiecare utilizează o sintaxă diferită pentru trimiterea imaginilor. Înțelegerea acestor diferențe este esențială pentru scrierea unui cod corect și evitarea erorilor frustrante.

API-ul Responses: input_image (recomandat)

API-ul Responses este noul punct de terminare principal al xAI. Noile funcționalități sunt adăugate aici în primul rând. Acesta este API-ul pe care trebuie să îl prioritizați pentru orice proiect nou.

Sintaxă

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

Caracteristici

  • Tipul este input_image (nu image_url)
  • URL-ul sau Data URI merge direct în image_url (fără obiect imbricat)
  • detail se află la același nivel cu image_url
  • Textul folosește tipul input_text
  • Tabloul input înlocuiește tabloul messages din Chat Completions

SDK Python

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-ul Chat Completions: image_url (vechi)

API-ul Chat Completions este punctul de terminare vechi (legacy), menținut pentru compatibilitatea cu SDK-urile OpenAI existente. Dacă migrați cod scris pentru OpenAI, acest API facilitează tranziția.

Sintaxă

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

Caracteristici

  • Tipul este image_url (nu input_image)
  • URL-ul se află într-un obiect imbricat image_url.url (dublă imbricare)
  • detail se află în interiorul obiectului image_url
  • Textul folosește tipul text (nu input_text)
  • Mesajele au un role (system, user, assistant)

Python cu SDK OpenAI

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)

Tabel comparativ

Aspect API Responses Chat Completions
Stare Principal (recomandat) Vechi (compatibilitate)
Tip imagine input_image image_url
Tip text input_text text
URL imagine image_url: "..." image_url.url: "..."
Gestionarea stării Cu stare (previous_response_id) Fără stare (retrimitere totală)
Stocare store: true/false Nu (fără stare)
Instrumente server web_search, x_search, code_interpreter Limitate

Erori frecvente de sintaxă

Eroarea 1: Amestecarea formatelor

# GREȘIT — Sintaxă Chat Completions în API-ul Responses
input=[
    {"type": "image_url", "image_url": {"url": "..."}}  # Nu!
]

# CORECT — Sintaxă API Responses
input=[
    {"type": "input_image", "image_url": "..."}  # Da!
]

Eroarea 2: Omiterea structurii imbricate în Chat Completions

# GREȘIT — URL direct în Chat Completions
{"type": "image_url", "image_url": "https://..."}  # Nu!

# CORECT — Obiect imbricat
{"type": "image_url", "image_url": {"url": "https://..."}}  # Da!

Eroarea 3: Utilizarea „text“ în loc de „input_text“

# GREȘIT — Tipul "text" în API-ul Responses
input=[
    {"type": "text", "text": "Describe."}  # Nu!
]

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

Când să utilizați fiecare API

  • Proiect nou: utilizați API-ul Responses. Acesta oferă acces la cele mai recente funcționalități și la stocarea conversațiilor.
  • Migrare de la OpenAI: începeți cu Chat Completions pentru a minimiza modificările de cod, apoi migrați treptat către API-ul Responses.
  • Imagini sensibile: API-ul Responses cu store: false sau API-ul Chat Completions (fără stare prin natura sa).

Puncte cheie

  • API-ul Responses utilizează input_image + input_text, iar API-ul Chat Completions utilizează image_url + text
  • Structura URL-ului diferă: direct în Responses, imbricat în Chat Completions
  • API-ul Responses este alegerea recomandată pentru orice dezvoltare nouă
  • Nu amestecați niciodată sintaxele ambelor API-uri în aceeași cerere
  • Verificați întotdeauna tipul obiectului (input_image vs image_url) pentru a evita erorile silențioase

Testați-vă cunoștințele

Viziunea API xAI: formate, tokeni, sintaxe – este totul la locul lui?

1. Cum trimiteți o imagine către API?

Răspuns: Prin URL sau Base64, într-un mesaj cu conținut mixt – respectând formatul și constrângerile de dimensiune documentate.

2. Ce controlează parametrul detail (auto, low, high)?

Răspuns: Granularitatea analizei și costul: low economisește tokeni pentru cazuri de utilizare grosiere, high maximizează precizia (OCR, detalii fine), iar auto lasă API-ul să decidă.

3. Cum se calculează costul unei imagini?

Răspuns: În tokeni de imagine – de la 256 la 1792, în funcție de rezoluție și detaliu: dimensionarea imaginilor și nivelul de detaliu reprezintă prima pârghie de optimizare.

4. Ce permite compararea mai multor imagini?

Răspuns: Trimiterea mai multor imagini într-o singură cerere și raționamentul asupra lor – diferențe, evoluții, consistență – fără nicio limită privind numărul de imagini per cerere.

5. input_image sau image_url: pe care să îl alegeți?

Răspuns: input_image este sintaxa modernă a API-ului Responses; image_url persistă ca moștenire Chat Completions – pentru codul nou, sintaxa modernă este obligatorie.

Format bun, detaliu bun, sintaxă bună: viziunea este pilotată ca textul – până la nivel de token.