Изпращане на изображение чрез URL
На тази страница
Най-простият метод
Изпращането на изображение чрез URL е най-директният начин за използване на Vision API: Вие предоставяте адреса на публично достъпно изображение и Mistral го изтегля за анализ. Вашата заявка остава лека – няколкостотин байта, – тъй като съдържа само връзка.
Приоритизирайте този метод, когато изображенията Ви вече са хоствани на CDN, в облачно хранилище или на уебсайт, или когато работите с публични уеб изображения. Екип, който вече съхранява визуални материали за продукти на CDN, може да започне да ги анализира, без да променя инфраструктурата си.
Формат на съобщението
Мултимодално съобщение с URL на изображение следва тази структура:
message = {
"role": "user",
"content": [
{
"type": "text",
"text": "Your question about the image"
},
{
"type": "image_url",
"image_url": "https://example.com/my-image.jpg"
}
]
}
Полето image_url приема всеки HTTP или HTTPS URL, сочещ към валиден изображение файл във формат JPEG, PNG, GIF или WebP.
Пълен пример на Python
Ето пълен, готов за изпълнение скрипт, който анализира публично изображение от Wikimedia, при условие че Вашият API ключ е зададен в средата:
from mistralai.client import Mistral
import os
# Initialize the client
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Public image to analyze
url_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a7/Camponotus_flavomarginatus_ant.jpg/800px-Camponotus_flavomarginatus_ant.jpg"
# Call the 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)
Обърнете внимание, че предаваме ключа чрез os.environ, вместо да го вграждаме директно в кода. Това е единственият допустим подход, след като скриптът напусне Вашата локална машина.
Добавяне на системен промпт
Горният отговор ще бъде верен, но общ – „черна мравка на размазан фон“. Системното съобщение променя естеството на анализа, като възлага роля на модела, преди той да види изображението:
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}
]
}
]
)
С тази рамка същото изображение води до таксономична идентификация и морфологично описание. Системният промпт насочва начина, по който моделът анализира изображението – мощен лост за получаване на специализирани отговори на цената на само няколко десетки токена.
Изисквания към URL
API трябва да може да изтегли изображението без никакъв контекст от Вашата сесия. Това води до четири изисквания: URL трябва да бъде публично достъпен (без страници зад автентикация); трябва да сочи директно към файла, а не към HTML страница, съдържаща изображението; форматът трябва да се поддържа (JPEG, PNG, GIF, където се чете само първият кадър, или WebP); и размерът трябва да остане разумен, под 20 MB.
Най-честото объркване е свързано с линковете за споделяне. Връзка от Google Drive или Dropbox, „споделена с всички“, връща HTML страница, а не изображение файл: обаждането се проваля или моделът описва уеб интерфейс. Най-добрата практика е да проверите 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")
Заявка HEAD е достатъчна: тя извлича хедърите, без да изтегля файла.
Изображения от облачно хранилище
Това изискване за публична достъпност изглежда несъвместимо с поверителни документи. Решението се крие в предварително подписаните URL адреси: ако изображенията Ви са в S3 bucket, Google Cloud Storage или Azure Blob, генерирате временен адрес, който предоставя достъп до един обект за продължителност, която Вие определяте.
import boto3
s3 = boto3.client("s3")
# Generate a pre-signed URL valid for 1 hour
presigned_url = s3.generate_presigned_url(
"get_object",
Params={"Bucket": "my-bucket", "Key": "images/invoice.png"},
ExpiresIn=3600
)
# Use this URL with the 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}
]
}
]
)
Вашият bucket остава частен, URL адресът изтича след определения период и Вие запазвате лекотата на заявката. Задайте ExpiresIn възможно най-кратко: няколко минути са повече от достатъчни за едно API обаждане.
Обработка на грешки
Обаждане, което зависи от отдалечено изтегляне, може да се провали по причини, извън Вашия контрол – изображението е изтрито, URL адресът е изтекъл или хостинг сървърът е недостъпен. В производствена среда никога не позволявайте на суровото изключение да стигне до потребителя:
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}")
Тествайте обработката на грешки с умишлено невалиден URL преди внедряване: това е най-честият сценарий и този, който най-рядко се тества.
Ключови изводи
- Изпращането чрез URL е най-простият метод – необходим е само публичен URL адрес
- Полето
contentна съобщението е масив, съдържащ елементиtextиimage_url - URL адресът трябва да сочи директно към достъпен файл с изображение
- Предварително подписаните URL адреси позволяват сигурно използване на частни изображения
- Винаги добавяйте системен промпт, за да насочите анализа на модела