Przejdź do głównej treści
Polski— Wybierz język
Menu

Wysyłanie obrazu przez URL

Lekcja 4 z 12 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Najprostsza metoda
  2. Format wiadomości
  3. Kompletny przykład w Pythonie
  4. Dodawanie monitu systemowego
  5. Wymagania dotyczące URL
  6. Obrazy z chmury
  7. Obsługa błędów
  8. Kluczowe wnioski

Najprostsza metoda

Wysyłanie obrazu przez URL to najbardziej bezpośredni sposób korzystania z Vision API: podajesz adres publicznie dostępnego obrazu, a Mistral pobiera go do analizy. Twoje żądanie pozostaje lekkie – liczy zaledwie kilkaset bajtów – ponieważ zawiera tylko link.

Wybierz tę metodę, gdy Twoje obrazy są już hostowane na CDN, w chmurze lub na stronie internetowej, albo gdy pracujesz z publicznie dostępnymi grafikami w sieci. Zespół, który przechowuje wizualizacje produktów na CDN, może zacząć je analizować bez konieczności zmiany swojej infrastruktury.

Format wiadomości

Wiadomość multimodalna zawierająca URL obrazu ma następującą strukturę:

message = {
    "role": "user",
    "content": [
        {
            "type": "text",
            "text": "Twoje pytanie dotyczące obrazu"
        },
        {
            "type": "image_url",
            "image_url": "https://example.com/my-image.jpg"
        }
    ]
}

Pole image_url akceptuje dowolny adres HTTP lub HTTPS wskazujący na prawidłowy plik obrazu w formacie JPEG, PNG, GIF lub WebP.

Kompletny przykład w Pythonie

Oto kompletny skrypt gotowy do uruchomienia, który analizuje publiczny obraz z Wikimedia, przy założeniu, że Twój klucz API jest ustawiony w zmiennych środowiskowych:

from mistralai.client import Mistral
import os

# Inicjalizacja klienta
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Publiczny obraz do analizy
url_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a7/Camponotus_flavomarginatus_ant.jpg/800px-Camponotus_flavomarginatus_ant.jpg"

# Wywołanie Vision API
response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Opisz dokładnie, co widzisz na tym obrazie."
                },
                {
                    "type": "image_url",
                    "image_url": url_image
                }
            ]
        }
    ]
)

print(response.choices[0].message.content)

Zwróć uwagę, że przekazujemy klucz przez os.environ, zamiast hardkodować go w kodzie. To jedyna akceptowalna metoda, gdy skrypt opuszcza Twój komputer lokalny.

Dodawanie monitu systemowego

Odpowiedź z powyższego przykładu będzie poprawna, ale ogólna – „czarna mrówka na rozmytym tle“. Wiadomość systemowa zmienia charakter analizy, przypisując modelowi konkretną rolę, zanim zobaczy on obraz:

response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "system",
            "content": "Jesteś ekspertem od entomologii. Analizuj obrazy owadów z naukową precyzją, identyfikując gatunek, rodzinę oraz widoczne cechy morfologiczne."
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Zidentyfikuj tego owada."},
                {"type": "image_url", "image_url": url_image}
            ]
        }
    ]
)

Dzięki takiemu ukierunkowaniu ten sam obraz pozwoli uzyskać identyfikację taksonomiczną i opis morfologiczny. Monit systemowy steruje sposobem, w jaki model analizuje obraz – to potężne narzędzie do uzyskiwania wyspecjalizowanych odpowiedzi kosztem zaledwie kilkudziesięciu tokenów.

Wymagania dotyczące URL

API musi mieć możliwość pobrania obrazu bez żadnego kontekstu Twojej sesji. Wynika z tego cztery wymagania: URL musi być publicznie dostępny (brak stron za logowaniem); musi wskazywać bezpośrednio na plik, a nie na stronę HTML zawierającą obraz; format musi być obsługiwany (JPEG, PNG, GIF – gdzie odczytywana jest tylko pierwsza klatka – lub WebP); a rozmiar musi być rozsądny, poniżej 20 MB.

Najczęstszym nieporozumieniem są linki udostępniania. Link do Google Drive lub Dropboxa „udostępniony wszystkim“ zwraca stronę HTML, a nie plik obrazu: wywołanie kończy się niepowodzeniem lub model opisuje interfejs sieciowy. Najlepszą praktyką jest weryfikacja nagłówka Content-Type przed wysłaniem żądania:

import requests

def verify_image_url(url):
    """Sprawdź, czy URL wskazuje na dostępny obraz."""
    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"Obraz dostępny: {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"Błąd połączenia: {e}")
        return False

verify_image_url("https://example.com/photo.jpg")

Żądanie HEAD jest wystarczające: pobiera nagłówki bez konieczności ściągania całego pliku.

Obrazy z chmury

Wymóg publicznej dostępności wydaje się niezgodny z poufnymi dokumentami. Rozwiązaniem są URL-e z podpisem czasowym (pre-signed URLs): jeśli Twoje obrazy znajdują się w zasobniku S3, Google Cloud Storage lub Azure Blob, generujesz tymczasowy adres, który przyznaje dostęp do pojedynczego obiektu na określony przez Ciebie czas.

import boto3

s3 = boto3.client("s3")

# Generowanie URL-a z podpisem ważnego przez 1 godzinę
presigned_url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "my-bucket", "Key": "images/invoice.png"},
    ExpiresIn=3600
)

# Użycie tego URL-a z Vision API
response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Wyciągnij całkowitą kwotę z tej faktury."},
                {"type": "image_url", "image_url": presigned_url}
            ]
        }
    ]
)

Twój zasobnik pozostaje prywatny, URL wygasa po określonym czasie, a Ty zachowujesz lekkość żądania. Ustaw ExpiresIn na jak najkrótszy możliwy czas: kilka minut w zupełności wystarczy na wykonanie wywołania API.

Obsługa błędów

Wywołanie zależne od zdalnego pobierania może się nie powieść z przyczyn niezależnych od Ciebie – obraz został usunięty, URL wygasł lub serwer hostingowy jest niedostępny. W środowisku produkcyjnym nigdy nie pozwalaj, aby surowy wyjątek dotarł do użytkownika:

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": "Opisz ten obraz."},
                    {"type": "image_url", "image_url": "https://example.com/image.jpg"}
                ]
            }
        ]
    )
    print(response.choices[0].message.content)
except Exception as e:
    print(f"Błąd: {e}")

Przetestuj swoją obsługę błędów, używając celowo nieprawidłowego URL-a przed wdrożeniem: to najczęstszy scenariusz i ten, który najrzadziej jest testowany.

Kluczowe wnioski

  • Wysyłanie przez URL to najprostsza metoda – wystarczy publiczny adres
  • Pole content wiadomości to tablica zawierająca elementy text i image_url
  • URL musi wskazywać bezpośrednio na dostępny plik obrazu
  • URL-e z podpisem czasowym pozwalają bezpiecznie używać prywatnych obrazów
  • Zawsze dodawaj monit systemowy, aby ukierunkować analizę modelu