Trimiterea unei imagini prin URL
Pe această pagină
Metoda cea mai simplă
Trimiterea unei imagini prin URL este cea mai directă modalitate de a utiliza API-ul Vision: furnizați adresa unei imagini accesibile public, iar Mistral o descarcă pentru analiză. Cererea dumneavoastră rămâne ușoară – câțiva sute de octeți – deoarece conține doar un link.
Prioritizați această metodă atunci când imaginile sunt deja găzduite pe un CDN, într-o stocare cloud sau pe un site web, ori când lucrați cu imagini publice de pe internet. O echipă care stochează deja vizualurile produselor pe un CDN poate începe analiza acestora fără a-și modifica infrastructura.
Formatul mesajului
Un mesaj multimodal care conține un URL de imagine urmează această structură:
message = {
"role": "user",
"content": [
{
"type": "text",
"text": "Your question about the image"
},
{
"type": "image_url",
"image_url": "https://example.com/my-image.jpg"
}
]
}
Câmpul image_url acceptă orice URL HTTP sau HTTPS care indică un fișier imagine valid în format JPEG, PNG, GIF sau WebP.
Exemplu complet în Python
Iată un script complet, gata de executare, care analizează o imagine publică de pe Wikimedia, presupunând că cheia API este setată în variabilele de mediu:
from mistralai.client import Mistral
import os
# Inițializarea clientului
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Imagine publică de analizat
url_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a7/Camponotus_flavomarginatus_ant.jpg/800px-Camponotus_flavomarginatus_ant.jpg"
# Apelarea API-ului Vision
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "Describe precisely what you see in this image."
},
{
"type": "image_url",
"image_url": url_image
}
]
}
]
)
print(response.choices[0].message.content)
Rețineți că transmitem cheia prin os.environ în loc să o codificăm direct în script. Aceasta este singura abordare acceptabilă odată ce scriptul părăsește mașina locală.
Adăugarea unui prompt de sistem
Răspunsul de mai sus va fi corect, dar generic – „o furnică neagră pe un fundal neclar“. Un mesaj de sistem schimbă natura analizei atribuirii unui rol modelului înainte ca acesta să vizualizeze imaginea:
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "system",
"content": "You are an entomology expert. Analyze insect images with scientific precision, identifying the species, family, and visible morphological characteristics."
},
{
"role": "user",
"content": [
{"type": "text", "text": "Identify this insect."},
{"type": "image_url", "image_url": url_image}
]
}
]
)
Cu această încadrare, aceeași imagine generează o identificare taxonomică și o descriere morfologică. Promptul de sistem ghidează modul în care modelul analizează imaginea – o pârghie puternică pentru obținerea unor răspunsuri specializate, cu costul a doar câțiva zeci de tokeni.
Cerințe pentru URL
API-ul trebuie să poată descărca imaginea fără niciun context din sesiunea dumneavoastră. Acest lucru implică patru cerințe: URL-ul trebuie să fie accesibil public (fără pagini protejate de autentificare); trebuie să indice direct fișierul, nu o pagină HTML care conține imaginea; formatul trebuie să fie suportat (JPEG, PNG, GIF unde se citește doar primul cadru, sau WebP); iar dimensiunea trebuie să rămână rezonabilă, sub 20 MB.
Cea mai frecventă confuzie privește link-urile de partajare. Un link Google Drive sau Dropbox „partajat cu toată lumea“ returnează o pagină HTML, nu un fișier imagine: apelul eșuează, iar modelul descrie o interfață web. Cea mai bună practică este verificarea Content-Type înainte de trimitere:
import requests
def verify_image_url(url):
"""Verify that a URL points to an accessible image."""
try:
response = requests.head(url, timeout=5, allow_redirects=True)
content_type = response.headers.get("Content-Type", "")
if response.status_code == 200 and "image" in content_type:
size = int(response.headers.get("Content-Length", 0))
print(f"Image accessible: {content_type}, {size / 1024:.0f} KB")
return True
else:
print(f"Issue: status={response.status_code}, type={content_type}")
return False
except requests.RequestException as e:
print(f"Connection error: {e}")
return False
verify_image_url("https://example.com/photo.jpg")
O cerere HEAD este suficientă: aceasta preia anteturile fără a descărca fișierul.
Imagini din stocarea cloud
Această cerință de accesibilitate publică pare incompatibilă cu documentele confidențiale. Soluția constă în URL-urile pre-semnate: dacă imaginile se află într-un bucket S3, în Google Cloud Storage sau în Azure Blob, generați o adresă temporară care acordă acces la un singur obiect pentru o durată specificată de dumneavoastră.
import boto3
s3 = boto3.client("s3")
# Generarea unui URL pre-semnat valabil timp de 1 oră
presigned_url = s3.generate_presigned_url(
"get_object",
Params={"Bucket": "my-bucket", "Key": "images/invoice.png"},
ExpiresIn=3600
)
# Utilizarea acestui URL cu API-ul Vision
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Extract the total amount from this invoice."},
{"type": "image_url", "image_url": presigned_url}
]
}
]
)
Bucket-ul dumneavoastră rămâne privat, URL-ul expiră după durata specificată, iar cererea își păstrează caracterul ușor. Setează ExpiresIn cât mai scurt posibil: câteva minute sunt mai mult decât suficiente pentru un apel API.
Gestionarea erorilor
Un apel care depinde de o descărcare la distanță poate eșua din motive care vă scapă controlului – imaginea a fost ștearsă, URL-ul a expirat sau serverul de găzduire este indisponibil. În producție, nu lăsați niciodată excepția brută să ajungă la utilizator:
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
try:
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Describe this image."},
{"type": "image_url", "image_url": "https://example.com/image.jpg"}
]
}
]
)
print(response.choices[0].message.content)
except Exception as e:
print(f"Error: {e}")
Testați gestionarea erorilor cu un URL deliberat invalid înainte de implementare: acesta este scenariul cel mai frecvent și cel mai puțin testat.
Puncte cheie
- Trimiterea prin URL este metoda cea mai simplă – aveți nevoie doar de un URL public
- Câmpul
contental mesajului este un tablou care conține elementetextșiimage_url - URL-ul trebuie să indice direct către un fișier imagine accesibil
- URL-urile pre-semnate vă permit să utilizați imagini private în siguranță
- Adăugați întotdeauna un prompt de sistem pentru a ghida analiza modelului