Send et billede via URL
På denne side
Den enkleste metode
At sende et billede via en URL er den mest direkte måde at bruge Vision API’en på: Du angiver adressen på et offentligt tilgængeligt billede, og Mistral downloader det til analyse. Din anmodning forbliver letvægtig – kun få hundrede bytes – da den kun indeholder et link.
Prioriter denne metode, når dine billeder allerede er hostet på et CDN, i cloud-lager eller på en hjemmeside, eller når du arbejder med offentlige web-billeder. Et team, der allerede gemmer produktvisualiseringer på et CDN, kan begynde at analysere dem uden at ændre deres infrastruktur.
Beskedformat
En multimodal besked med en billede-URL følger denne struktur:
message = {
"role": "user",
"content": [
{
"type": "text",
"text": "Dit spørgsmål om billedet"
},
{
"type": "image_url",
"image_url": "https://example.com/my-image.jpg"
}
]
}
Feltet image_url accepterer enhver HTTP- eller HTTPS-URL, der peger på en gyldig billedfil i formatet JPEG, PNG, GIF eller WebP.
Komplet Python-eksempel
Her er et komplet script, der er klar til kørsel, og som analyserer et offentligt billede fra Wikimedia, under forudsætning af at din API-nøgle er indstillet i miljøvariablen:
from mistralai.client import Mistral
import os
# Initialiser klienten
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Offentligt billede til analyse
url_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a7/Camponotus_flavomarginatus_ant.jpg/800px-Camponotus_flavomarginatus_ant.jpg"
# Kald Vision API'en
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "Beskriv præcist, hvad du ser på dette billede."
},
{
"type": "image_url",
"image_url": url_image
}
]
}
]
)
print(response.choices[0].message.content)
Bemærk, at vi sender nøglen via os.environ i stedet for at hardkode den. Dette er den eneste acceptable fremgangsmåde, når scriptet forlader din lokale maskine.
Tilføjelse af en system-prompt
Svaret ovenfor vil være korrekt, men generisk – „en sort myre på en sløret baggrund”. En systembesked ændrer analysens karakter ved at tildele modellen en rolle, før den ser billedet:
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "system",
"content": "Du er en ekspert i entomologi. Analyser insektbilleder med videnskabelig præcision, identificer arten, familien og de synlige morfologiske egenskaber."
},
{
"role": "user",
"content": [
{"type": "text", "text": "Identificer dette insekt."},
{"type": "image_url", "image_url": url_image}
]
}
]
)
Med denne ramme giver det samme billede anledning til en taksonomisk identifikation og en morfologisk beskrivelse. System-prompten styrer, hvordan modellen analyserer billedet – en kraftfuld løftestang til at opnå specialiserede svar til prisen af blot nogle få dusin tokens.
Krav til URL
API’en skal kunne downloade billedet uden nogen kontekst fra din session. Dette fører til fire krav: URL’en skal være offentligt tilgængelig (ingen sider bag godkendelse); den skal pege direkte på filen, ikke på en HTML-side, der indeholder billedet; formatet skal være understøttet (JPEG, PNG, GIF, hvor kun den første frame læses, eller WebP); og størrelsen skal være rimelig, under 20 MB.
Den mest almindelige forvirring vedrører delingslinks. Et Google Drive- eller Dropbox-link, der er „delt med alle”, returnerer en HTML-side, ikke en billedfil: kaldet fejler, eller modellen beskriver en webgrænseflade. Den bedste praksis er at verificere Content-Type før afsendelse:
import requests
def verify_image_url(url):
"""Verificer, at en URL peger på et tilgængeligt billede."""
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"Billede tilgængeligt: {content_type}, {size / 1024:.0f} KB")
return True
else:
print(f"Problem: status={response.status_code}, type={content_type}")
return False
except requests.RequestException as e:
print(f"Forbindelsesfejl: {e}")
return False
verify_image_url("https://example.com/photo.jpg")
En HEAD-anmodning er tilstrækkelig: den henter headere uden at downloade filen.
Billeder fra cloud-lager
Dette krav om offentlig tilgængelighed ser ud til at være uforeneligt med fortrolige dokumenter. Løsningen ligger i pre-signed URLs: Hvis dine billeder befinder sig i en S3-bucket, Google Cloud Storage eller Azure Blob, genererer du en midlertidig adresse, der giver adgang til et enkelt objekt i en periode, du specificerer.
import boto3
s3 = boto3.client("s3")
# Generer en pre-signed URL gyldig i 1 time
presigned_url = s3.generate_presigned_url(
"get_object",
Params={"Bucket": "my-bucket", "Key": "images/invoice.png"},
ExpiresIn=3600
)
# Brug denne URL med Vision API'en
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Udtræk det samlede beløb fra denne faktura."},
{"type": "image_url", "image_url": presigned_url}
]
}
]
)
Din bucket forbliver privat, URL’en udløber efter den angivne forsinkelse, og du beholder anmodningens letvægtskarakter. Indstil ExpiresIn så kort som muligt: få minutter er mere end nok til et API-kald.
Håndtering af fejl
Et kald, der afhænger af et eksternt download, kan fejle af årsager, du ikke har kontrol over – billedet blev slettet, URL’en udløb, eller hosting-serveren er utilgængelig. Lad aldrig i produktion den rå undtagelse boble op til brugeren:
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": "Beskriv dette billede."},
{"type": "image_url", "image_url": "https://example.com/image.jpg"}
]
}
]
)
print(response.choices[0].message.content)
except Exception as e:
print(f"Fejl: {e}")
Test din fejlhåndtering med en bevidst ugyldig URL før udrulning: Dette er det hyppigste scenarie og det, der testes mindst ofte.
Vigtige pointer
- Afsendelse via URL er den enkleste metode – en offentlig URL er alt, hvad du behøver
- Beskedens felt
contenter en array, der indeholder elementernetextogimage_url - URL’en skal pege direkte på en tilgængelig billedfil
- Pre-signed URLs giver dig mulighed for sikkert at bruge private billeder
- Tilføj altid en system-prompt for at styre modellens analyse