Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Lähetä kuva URL-osoitteen kautta

Oppitunti 4 / 12 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Yksinkertaisin menetelmä
  2. Viestin muoto
  3. Täydellinen Python-esimerkki
  4. Järjestelmäkehotteen lisääminen
  5. URL-vaatimukset
  6. Kuvat pilvitallennustilasta
  7. Virheenkäsittely
  8. Keskeiset asiat

Yksinkertaisin menetelmä

Kuvan lähettäminen URL-osoitteen kautta on suoraviivaisin tapa hyödyntää Vision APIa: annat julkisesti saatavilla olevan kuvan osoitteen, ja Mistral lataa sen analysoitavaksi. Pyyntösi pysyy kevyenä – vain muutaman sadan tavun kokoisena – koska se sisältää ainoastaan linkin.

Suosi tätä menetelmää, kun kuvasi ovat jo CDN:ssä, pilvitallennustilassa tai verkkosivustolla, tai kun työskentelet julkisten verkkokuvien kanssa. Tiimi, joka säilyttää tuotekuvansa jo CDN:ssä, voi aloittaa niiden analysoinnin muuttamatta infrastruktuuriaan.

Viestin muoto

Monimodaalinen viesti, jossa on kuvan URL-osoite, noudattaa tätä rakennetta:

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

Kenttä image_url hyväksyy minkä tahansa HTTP- tai HTTPS-URL-osoitteen, joka viittaa kelvolliseen kuvatiedostoon JPEG-, PNG-, GIF- tai WebP-muodossa.

Täydellinen Python-esimerkki

Tässä on täydellinen, ajokelpoinen skripti, joka analysoi julkisen kuvan Wikimediasta olettaen, että API-avaimesi on asetettu ympäristömuuttujaan:

from mistralai.client import Mistral
import os

# Alustetaan asiakasohjelma
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Analysoitava julkinen kuva
url_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a7/Camponotus_flavomarginatus_ant.jpg/800px-Camponotus_flavomarginatus_ant.jpg"

# Kutsutaan Vision APIa
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)

Huomaa, että välitämme avaimen os.environ-muuttujan kautta emmekä kovakoodaa sitä. Tämä on ainoa hyväksyttävä tapa, kun skripti poistuu paikalliselta koneeltasi.

Järjestelmäkehotteen lisääminen

Yllä oleva vastaus on oikea, mutta yleinen – “musta muurahainen sumealla taustalla”. Järjestelmäviesti muuttaa analyysin luonnetta määrittämällä mallille roolin ennen kuin se näkee kuvan:

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

Tällä kehyksellä sama kuva tuottaa taksonomisen tunnistuksen ja morfologisen kuvauksen. Järjestelmäkehote ohjaa sitä, miten malli analysoi kuvaa – tehokas vipu erikoistuneiden vastausten saamiseksi vain muutaman kymmenen tokenin kustannuksella.

URL-vaatimukset

APIn on pystyttävä lataamaan kuva ilman istuntosi kontekstia. Tästä seuraa neljä vaatimusta: URL-osoitteen on oltava julkisesti saatavilla (ei sivuja tunnistautumisen takana); sen on viitattava suoraan tiedostoon, ei HTML-sivuun, joka sisältää kuvan; muodon on oltava tuettu (JPEG, PNG, GIF, jossa luetaan vain ensimmäinen kehys, tai WebP); ja koon on pysyttävä kohtuullisena, alle 20 Mt.

Yleisin sekaannus liittyy jakolinkkeihin. Google Driven tai Dropboxin “kaikille jaettu” linkki palauttaa HTML-sivun, ei kuvatiedostoa: kutsu epäonnistuu, tai malli kuvailee verkkoliittymää. Paras käytäntö on tarkistaa Content-Type ennen lähettämistä:

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-pyyntö riittää: se noutaa otsikkotiedot lataamatta tiedostoa.

Kuvat pilvitallennustilasta

Tämä julkisen saatavuuden vaatimus vaikuttaa ristiriitaiselta luottamuksellisten asiakirjojen kanssa. Ratkaisu löytyy etukäteisallekirjoitetuista URL-osoitteista: jos kuvasi ovat S3-ämpärissä, Google Cloud Storagessa tai Azure Blobissa, voit luoda väliaikaisen osoitteen, joka myöntää pääsyn yksittäiseen objektiin määrittämäksesi ajaksi.

import boto3

s3 = boto3.client("s3")

# Luodaan etukäteisallekirjoitettu URL, joka on voimassa 1 tunnin
presigned_url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "my-bucket", "Key": "images/invoice.png"},
    ExpiresIn=3600
)

# Käytetään tätä URL-osoitetta Vision APIn kanssa
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}
            ]
        }
    ]
)

Ämpärisi pysyy yksityisenä, URL-osoite vanhenee määritetyn viiveen jälkeen, ja pyynnön keveys säilyy. Aseta ExpiresIn mahdollisimman lyhyeksi: muutama minuutti riittää hyvin API-kutsuun.

Virheenkäsittely

Etälatauksesta riippuva kutsu voi epäonnistua syistä, jotka eivät ole hallinnassasi – kuva on poistettu, URL-osoite on vanhentunut tai isäntäpalvelin ei ole saatavilla. Tuotantoympäristössä älä koskaan anna raakapoikkeuksen nousta käyttäjälle asti:

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

Testaa virheenkäsittelysi tarkoituksellisesti virheellisellä URL-osoitteella ennen käyttöönottoa: tämä on yleisin skenaario ja se, jota testataan harvimmin.

Keskeiset asiat

  • Lähettäminen URL-osoitteen kautta on yksinkertaisin menetelmä – tarvitset vain julkisen URL-osoitteen
  • Viestin content-kenttä on taulukko, joka sisältää text- ja image_url-elementtejä
  • URL-osoitteen on viitattava suoraan saatavilla olevaan kuvatiedostoon
  • Etukäteisallekirjoitetut URL-osoitteet mahdollistavat yksityisten kuvien turvallisen käytön
  • Lisää aina järjestelmäkehote ohjaamaan mallin analyysiä