Odeslání obrázku prostřednictvím URL
Na této stránce
Nejjednodušší metoda
Odeslání obrázku prostřednictvím URL je nejpřímější způsob, jak využít Vision API: poskytneš adresu veřejně dostupného obrázku a Mistral si jej stáhne k analýze. Tvůj požadavek zůstává lehký – jen několik set bajtů –, protože přenáší pouze odkaz.
Upřednostni tuto metodu, když jsou tvé obrázky již hostovány na CDN, v cloudovém úložišti nebo na webu, nebo když pracuješ s veřejnými webovými obrázky. Tým, který již ukládá vizuály produktů na CDN, může začít s jejich analýzou bez nutnosti měnit svou infrastrukturu.
Formát zprávy
Multimodální zpráva s URL obrázku má následující strukturu:
message = {
"role": "user",
"content": [
{
"type": "text",
"text": "Your question about the image"
},
{
"type": "image_url",
"image_url": "https://example.com/my-image.jpg"
}
]
}
Pole image_url přijímá jakoukoli adresu HTTP nebo HTTPS směřující na platný soubor obrázku ve formátu JPEG, PNG, GIF nebo WebP.
Kompletní příklad v Pythonu
Zde je kompletní skript připravený ke spuštění, který analyzuje veřejný obrázek z Wikimedia za předpokladu, že máš klíč API nastavený v prostředí:
from mistralai.client import Mistral
import os
# Inicializace klienta
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Veřejný obrázek k analýze
url_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a7/Camponotus_flavomarginatus_ant.jpg/800px-Camponotus_flavomarginatus_ant.jpg"
# Volání Vision API
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)
Všimni si, že klíč předáváme přes os.environ, nikoli jeho přímým zápisem do kódu. Toto je jediný přijatelný přístup, jakmile skript opustí tvůj lokální počítač.
Přidání systémové výzvy (system prompt)
Výše uvedená odpověď bude správná, ale obecná – „černý mravenec na rozmazaném pozadí“. Systémová zpráva změní povahu analýzy tím, že modelu před zobrazením obrázku přidělí roli:
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}
]
}
]
)
Díky tomuto rámci poskytne stejný obrázek taxonomickou identifikaci a morfologický popis. Systémová výzva řídí způsob, jakým model obrázek analyzuje – je to mocný nástroj pro získávání specializovaných odpovědí za cenu pouhých několika desítek tokenů.
Požadavky na URL
API musí být schopno stáhnout obrázek bez jakéhokoli kontextu z tvé relace. To vede ke čtyřem požadavkům: URL musí být veřejně přístupná (žádné stránky za ověřením); musí směřovat přímo na soubor, nikoli na HTML stránku obsahující obrázek; formát musí být podporován (JPEG, PNG, GIF, kde se čte pouze první snímek, nebo WebP); a velikost musí zůstat přiměřená, pod 20 MB.
Nejčastější nejasnosti se týkají odkazů pro sdílení. Odkaz na Google Drive nebo Dropbox „sdílený se všemi“ vrací HTML stránku, nikoli soubor obrázku: volání selže nebo model popíše webové rozhraní. Nejlepší praxí je před odesláním ověřit Content-Type:
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")
Požadavek HEAD je dostatečný: získá hlavičky bez stahování samotného souboru.
Obrázky z cloudového úložiště
Tento požadavek na veřejnou přístupnost se zdá být v rozporu s důvěrnými dokumenty. Řešením jsou předem podepsané URL (pre-signed URLs): pokud jsou tvé obrázky v bucketu S3, Google Cloud Storage nebo Azure Blob, vygeneruješ dočasnou adresu, která uděluje přístup k jedinému objektu na dobu, kterou určíš.
import boto3
s3 = boto3.client("s3")
# Vygenerování předem podepsané URL platné 1 hodinu
presigned_url = s3.generate_presigned_url(
"get_object",
Params={"Bucket": "my-bucket", "Key": "images/invoice.png"},
ExpiresIn=3600
)
# Použití této URL s Vision API
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}
]
}
]
)
Tvůj bucket zůstává soukromý, URL po uplynutí stanovené doby vyprší a zachováš lehkost požadavku. Nastav ExpiresIn co nejkratší: několik minut je pro volání API více než dost.
Zpracování chyb
Volání závislé na vzdáleném stahování může selhat z důvodů, které nemůžeš ovlivnit – obrázek byl smazán, URL vypršela nebo je hostitelský server nedostupný. V produkčním prostředí nikdy nenechej surovou výjimku probublávat až k uživateli:
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}")
Otestuj své zpracování chyb s úmyslně neplatnou URL před nasazením: toto je nejčastější scénář a ten, který se testuje nejméně často.
Klíčové poznatky
- Odeslání prostřednictvím URL je nejjednodušší metoda – stačí ti veřejná URL
- Pole
contentve zprávě je pole obsahující prvkytextaimage_url - URL musí směřovat přímo na přístupný soubor obrázku
- Předem podepsané URL umožňují bezpečné použití soukromých obrázků
- Vždy přidej systémovou výzvu pro nasměrování analýzy modelu