Formate de imagine: URL și Base64
Pe această pagină
Actualizat la 3 noiembrie 2026. Odată cu API-ul Responses, obiectele
input_imageșiinput_textse plasează în câmpulcontental unui mesaj de tip{"role": "user", ...}, nu direct îninput. Exemplul Python anterior apelaclient.responses.create()pe clientulxai-sdk, metodă care nu există, și scria cheia API direct în cod: acum folosește funcțiileuser(...)șiimage(...)din SDK, iar cheia este citită din variabilele de mediu. S-a adăugat avertismentul xAI privind stocarea istoricului. Cod verificat cuxai-sdk1.21.0. Sursă: Image Understanding.
Trimiterea imaginilor către Grok
Modelele Grok, începând cu versiunea grok-4.5, includ capacități de viziune. Puteți trimite una sau mai multe imagini în cererile API, iar modelul le va analiza pentru a răspunde întrebărilor dumneavoastră. Această funcționalitate se numește înțelegerea imaginilor sau viziune multimodală.
Înainte de a explora cazurile de utilizare, este esențial să stăpâniți cele două formate de trimitere a imaginilor suportate de API-ul xAI.
URL Direct
Cea mai simplă metodă constă în furnizarea URL-ului public al unei imagini. Modelul o va descărca și analiza automat.
Cu API-ul Responses (endpoint-ul principal):
{
"model": "grok-4.5",
"input": [
{
"role": "user",
"content": [
{
"type": "input_image",
"image_url": "https://exemple.com/photo-produit.jpg"
},
{
"type": "input_text",
"text": "Descrieți această imagine în detaliu."
}
]
}
]
}
xAI recomandă ca, atunci când trimiteți imagini, să nu stocați istoricul cererilor și răspunsurilor pe serverele lor, altfel cererea poate eșua: cu API-ul Responses, transmiteți "store": false.
Cu API-ul Chat Completions (vechi, compatibil OpenAI):
{
"model": "grok-4.5",
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://exemple.com/photo-produit.jpg"
}
},
{
"type": "text",
"text": "Descrieți această imagine în detaliu."
}
]
}
]
}
URL-ul trebuie să indice un fișier imagine accesibil public. Dacă imaginea este protejată prin autentificare sau se află pe un CDN privat, utilizați în schimb formatul Base64.
Codificat Base64 (Data URI)
Al doilea format implică codificarea imaginii direct în cerere sub formă de șir Base64, precedat de un prefix MIME. Aceasta este metoda ideală atunci când lucrați cu imagini locale, capturi de ecran sau fișiere generate dinamic.
{
"type": "input_image",
"image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}
Prefixul data:image/jpeg;base64, indică modelului tipul MIME al imaginii. Ajustați-l în funcție de format:
data:image/jpeg;base64,pentru fișiere JPG/JPEGdata:image/png;base64,pentru fișiere PNG
Codificarea unei imagini în Python
import base64
with open("photo.jpg", "rb") as f:
image_data = base64.standard_b64encode(f.read()).decode("utf-8")
image_url = f"data:image/jpeg;base64,{image_data}"
Codificarea în JavaScript/Node.js
import { readFileSync } from 'fs';
const imageData = readFileSync('photo.jpg').toString('base64');
const imageUrl = `data:image/jpeg;base64,${imageData}`;
Diferențe cheie între URL și Base64
| Criteriu | URL | Base64 |
|---|---|---|
| Dimensiunea cererii | Ușoară (doar URL-ul) | Grea (+33% față de fișierul original) |
| Accesibilitate | Necesită imagine publică | Funcționează cu orice fișier local |
| Latență | Descărcare de pe server | Date direct în cerere |
| Caz de utilizare tipic | Imagini web, CDN, stocare în cloud | Fișiere locale, capturi de ecran, încărcări |
Combinarea textului și a imaginilor
Câmpul content al unui mesaj acceptă un tablou mixt de obiecte input_image și input_text, în orice ordine: puteți alterna liber textul și imaginile. Cu SDK-ul nativ xAI, același mesaj se construiește cu user(), care acceptă text și imagini create de image() în secvență:
from xai_sdk import Client
from xai_sdk.chat import image, user
client = Client() # cheia citită din XAI_API_KEY
chat = client.chat.create(model="grok-4.5")
chat.append(
user(
"Comparați aceste două fotografii:",
image(image_url="https://exemple.com/photo1.jpg", detail="high"),
image(image_url="https://exemple.com/photo2.jpg", detail="high"),
"Care sunt diferențele principale?",
)
)
response = chat.sample()
print(response.content)
Funcția image() acceptă un URL public sau un Data URI Base64.
Puncte cheie
- Sunt suportate două formate de imagine: URL Direct și Base64 (Data URI)
- Formatele acceptate sunt exclusiv JPG, JPEG și PNG
- Fiecare imagine nu trebuie să depășească 20 MiB
- Numărul de imagini per cerere este nelimitat
- API-ul Responses plasează
input_imageîn câmpulcontental unui mesaj; Chat Completions folosește părți de tipimage_url; SDK-ul xAI foloseșteimage()în interiorul luiuser() - Preferați URL-ul pentru imaginile publice și Base64 pentru fișierele locale