Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Pildi saatmine URL-i kaudu

Õppetund 4 / 12 Värskendatud 2. november 2026 Arendajatele
Sellel lehel
  1. Lihtsaim meetod
  2. Sõnumi vorming
  3. Täielik Pythoni näide
  4. Süsteemikäsulisa lisamine
  5. URL-i nõuded
  6. Pilvesalvestuse pildid
  7. Veakäsitlus
  8. Peamised punktid

Lihtsaim meetod

Pildi saatmine URL-i kaudu on Vision API kasutamise kõige otsesem viis: sisestad avalikult ligipääsetava pildi aadressi ja Mistral laeb selle analüüsimiseks alla. Sinu päring jääb kergeks – vaid mõnisada baiti –, kuna see sisaldab üksnes linki.

Eelista seda meetodit, kui su pildid on juba majutatud CDN-i, pilvesalvestusse või veebisaidile, või kui töötad avalike veebipiltidega. Meeskond, kes hoiab tootevisuaale juba CDN-is, saab neid analüüsima hakata ilma oma taristut muutmata.

Sõnumi vorming

Mitmemodaalne sõnum koos pildi URL-iga järgib seda struktuuri:

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

Väli image_url aktsepteerib mis tahes HTTP või HTTPS URL-i, mis viib kehtivale pildifailile formaadis JPEG, PNG, GIF või WebP.

Täielik Pythoni näide

Siin on täielik, kohe käivitatav skript, mis analüüsib avalikku pilti saidilt Wikimedia, eeldades, et su API võti on keskkonnas määratud:

from mistralai.client import Mistral
import os

# Kliendi lähtestamine
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Analüüsitav avalik pilt
url_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a7/Camponotus_flavomarginatus_ant.jpg/800px-Camponotus_flavomarginatus_ant.jpg"

# Vision API kutsumine
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)

Pane tähele, et edastame võtme kaudu os.environ, mitte ei kodeeri seda otse koodi. See on ainus vastuvõetav lähenemine, kui skript lahkub sinu kohalikust masinast.

Süsteemikäsulisa lisamine

Eelnev vastus on küll õige, kuid üldine – „must sipelgas udusel taustal“. Süsteemsõnum muudab analüüsi olemust, omistades mudelile rolli enne, kui ta pilti näeb:

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

Selle raamistusega annab sama pilt tulemuseks taksonoomilise identifitseerimise ja morfoloogilise kirjelduse. Süsteemikäsulisa juhendab, kuidas mudel pilti analüüsib – võimas hoob spetsialiseerunud vastuste saamiseks vaid mõnekümne tokeni hinnaga.

URL-i nõuded

API peab suutma pildi alla laadida ilma sinu seansi kontekstita. See toob kaasa neli nõuet: URL peab olema avalikult ligipääsetav (lehed autentimise taga ei sobi); see peab viima otse failile, mitte HTML-lehele, mis sisaldab pilti; formaat peab olema toetatud (JPEG, PNG, GIF, kus loetakse ainult esimene kaader, või WebP); ja suurus peab jääma mõistlikuks, alla 20 MB.

Kõige levinum segadus tekib jagamislinkidega. Google Drive’i või Dropboxi link, mis on „jagatud kõigiga“, tagastab HTML-lehe, mitte pildifaili: kõne ebaõnnestub või kirjeldab mudel veebiliidest. Parim tava on enne saatmist kontrollida Content-Type päist:

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 päringust piisab: see toob päised ilma faili alla laadimata.

Pilvesalvestuse pildid

See avaliku ligipääsetavuse nõue tundub konfliktis olevat konfidentsiaalsete dokumentidega. Lahendus peitub eelallkirjastatud URL-ides: kui su pildid on S3 bucket’is, Google Cloud Storage’is või Azure Blob’is, genereerid ajutise aadressi, mis annab juurdepääsu ühele objektile sinu määratud ajaks.

import boto3

s3 = boto3.client("s3")

# Genereeri eelallkirjastatud URL, kehtiv 1 tund
presigned_url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "my-bucket", "Key": "images/invoice.png"},
    ExpiresIn=3600
)

# Kasuta seda URL-i Vision API-ga
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}
            ]
        }
    ]
)

Sinu bucket jääb privaatseks, URL aegub määratud aja möödudes ja säilitad päringu kerguse. Määra ExpiresIn võimalikult lühikeseks: mõni minut on API kõne jaoks enam kui piisav.

Veakäsitlus

Kõne, mis sõltub kauglaadimisest, võib ebaõnnestuda põhjustel, mida sa ei kontrolli – pilt kustutati, URL aegus või hostiv server pole kättesaadav. Tootmiskeskkonnas ära kunagi lase toorel erendil kasutajani jõuda:

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

Testi oma veakäsitlust tahtlikult vigase URL-iga enne kasutuselevõttu: see on kõige sagedasem stsenaarium ja see, mida testitakse kõige harvem.

Peamised punktid

  • Saatmine URL-i kaudu on lihtsaim meetod – vaja on vaid avalikku URL-i
  • Sõnumi väli content on massiiv, mis sisaldab elemente text ja image_url
  • URL peab viima otse ligipääsetavale pildifailile
  • Eelallkirjastatud URL-id võimaldavad turvaliselt kasutada privaatseid pilte
  • Lisa alati süsteemikäsulisa, et juhendada mudeli analüüsi