Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Kép küldése URL-címen keresztül

4. lecke 12 közül Frissítve 2026. november 2. Fejlesztő
Ezen az oldalon
  1. A legegyszerűbb módszer
  2. Üzenetformátum
  3. Teljes Python-példa
  4. Rendszerüzenet (system prompt) hozzáadása
  5. URL-követelmények
  6. Képek felhőtárhelyről
  7. Hibakezelés
  8. Főbb megállapítások

A legegyszerűbb módszer

A kép URL-címen keresztüli küldése a Vision API használatának legközvetlenebb módja: megadod egy nyilvánosan elérhető kép címét, és a Mistral letölti azt elemzésre. A kérésed így könnyű marad – néhány száz bájt –, mivel csak egy hivatkozást tartalmaz.

Akkor részesítsd előnyben ezt a módszert, ha a képeid már CDN-en, felhőtárhelyen vagy weboldalon vannak elhelyezve, illetve ha nyilvános webes képekkel dolgozol. Egy csapat, amely például már CDN-en tárolja a termékvizuálokat, infrastruktúrája módosítása nélkül kezdheti meg azok elemzését.

Üzenetformátum

Egy kép URL-címét tartalmazó multimodális üzenet a következő szerkezetet követi:

message = {
    "role": "user",
    "content": [
        {
            "type": "text",
            "text": "Your question about the image"
        },
        {
            "type": "image_url",
            "image_url": "https://example.com/my-image.jpg"
        }
    ]
}

Az image_url mező bármilyen HTTP vagy HTTPS URL-címet elfogad, amely érvényes képfájlra mutat JPEG, PNG, GIF vagy WebP formátumban.

Teljes Python-példa

Íme egy teljes, futtatható szkript, amely egy nyilvános képet elemez a Wikimédiáról, feltételezve, hogy az API-kulcsod a környezetváltozókban van beállítva:

from mistralai.client import Mistral
import os

# A kliens inicializálása
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# A nyilvános kép, amit elemezni szeretnénk
url_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a7/Camponotus_flavomarginatus_ant.jpg/800px-Camponotus_flavomarginatus_ant.jpg"

# A Vision API meghívása
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)

Vedd észre, hogy a kulcsot az os.environ segítségével adjuk át, nem pedig közvetlenül a kódba írva. Ez az egyetlen elfogadható megközelítés, ha a szkript kikerül a helyi gépedről.

Rendszerüzenet (system prompt) hozzáadása

A fenti válasz helyes lesz, de általános: „egy fekete hangya elmosódott háttér előtt“. Egy rendszerüzenet megváltoztatja az elemzés jellegét azáltal, hogy szerepet assigns a modellnek, még mielőtt az látná a képet:

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}
            ]
        }
    ]
)

Ezzel a keretezéssel ugyanaz a kép taxonómiai azonosítást és morfológiai leírást eredményez. A rendszerüzenet irányítja, hogyan elemzi a modell a képet – ez egy hatalmas eszköz specializált válaszok získálására, mindössze néhány tucat token költségén.

URL-követelmények

Az API-nak képesnek kell lennie a kép letöltésére a munkameneted kontextusa nélkül. Ez négy követelményt von maga után: az URL-nek nyilvánosan elérhetőnek kell lennie (nincs hitelesítés mögött rejtett oldal); közvetlenül a fájlra kell mutatnia, nem pedig egy olyan HTML-oldalra, amely tartalmazza a képet; a formátumnak támogatottnak kell lennie (JPEG, PNG, GIF – ahol csak az első képkockát olvassa be –, vagy WebP); a méretnek pedig ésszerűnek kell maradnia, 20 MB alatt.

A leggyakoribb félreértés a megosztási hivatkozásokkal kapcsolatos. Egy Google Drive vagy Dropbox link, amelyet „mindenkivel megosztottak“, egy HTML-oldalt ad vissza, nem pedig egy képfájlt: a hívás sikertelen, vagy a modell egy webes felületet ír le. A legjobb gyakorlat a Content-Type ellenőrzése küldés előtt:

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")

Egy HEAD kérés elegendő: ez lekéri a fejléceket a fájl letöltése nélkül.

Képek felhőtárhelyről

Ez a nyilvános hozzáférhetőségi követelmény összeférhetetlennek tűnik a bizalmas dokumentumokkal. A megoldás az előjelezett URL-címekben (pre-signed URLs) rejlik: ha a képeid egy S3 vödörben, Google Cloud Storage-ban vagy Azure Blob-ban vannak, generálhatsz egy ideiglenes címet, amely meghatározott időtartamra hozzáférést biztosít egyetlen objektumhoz.

import boto3

s3 = boto3.client("s3")

# Előjelezett URL generálása, amely 1 óráig érvényes
presigned_url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "my-bucket", "Key": "images/invoice.png"},
    ExpiresIn=3600
)

# Az URL használata a Vision API-val
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}
            ]
        }
    ]
)

A vödröd privát marad, az URL a megadott idő után elévül, és a kérés könnyűsége megmarad. Állítsd az ExpiresIn értéket a lehető legrövidebbre: néhány perc több mint elég egy API-híváshoz.

Hibakezelés

Egy távoli letöltéstől függő hívás olyan okok miatt is sikertelen lehet, amelyek rajtad kívül állnak: a képet törölték, az URL elévült, vagy a hoszting szerver nem elérhető. Éles környezetben soha ne engedd, hogy a nyers kivétel (exception) elérjen a felhasználóig:

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}")

Teszteld a hibakezelésedet szándékosan érvénytelen URL-lel, mielőtt telepítenéd: ez a leggyakoribb forgatókönyv, és egyben az, amelyet a legritkábban tesztelnek.

Főbb megállapítások

  • Az URL-en keresztüli küldés a legegyszerűbb módszer – csak egy nyilvános URL-re van szükséged
  • Az üzenet content mezője egy tömb, amely text és image_url elemeket tartalmaz
  • Az URL-nek közvetlenül egy elérhető képfájlra kell mutatnia
  • Az előjelezett URL-ek lehetővé teszik privát képek biztonságos használatát
  • Mindig adj hozzá rendszerüzenetet a modell elemzésének irányításához