Bildverständnis
Ein Vision-Modell zu einem oder mehreren Bildern befragen: Formate, Grenzen, Kosten und Fehler.
Wann nutzen
Fotos beschreiben, Text in Screenshots lesen, zwei Bilder vergleichen, Werte aus Diagrammen ziehen oder Bilder klassifizieren. Das Bild steht in einer Chat-Nachricht neben der Frage. Für mehrseitige Dokumente PDFs und Dateien nutzen; Bildgenerierung behandelt dieser Leitfaden nicht.
Minimalbeispiel
Ein Textteil und ein image_url-Teil in einer Nutzernachricht. Das Beispiel bettet ein PNG mit 1 mal 1 Pixel als Data-URL ein und braucht deshalb keinen Bild-Host.
curl
curl --request POST \
--url 'https://api.tokenlane.de/v1/chat/completions' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "deepseek/deepseek-v4.1-flash-1017",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Describe this image."
},
{
"type": "image_url",
"image_url": {
"url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4//8/AAX+Av4N70a4AAAAAElFTkSuQmCC"
}
}
]
}
],
"max_tokens": 400
}'
node
import OpenAI from 'openai';
const client = new OpenAI({ baseURL: "https://api.tokenlane.de/v1", apiKey: process.env.TOKENLANE_API_KEY });
const response = await client.chat.completions.create({
"model": "deepseek/deepseek-v4.1-flash-1017",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Describe this image."
},
{
"type": "image_url",
"image_url": {
"url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4//8/AAX+Av4N70a4AAAAAElFTkSuQmCC"
}
}
]
}
],
"max_tokens": 400
}, {});
console.log(response);
python
import os
import json
from openai import OpenAI
client = OpenAI(base_url="https://api.tokenlane.de/v1", api_key=os.environ["TOKENLANE_API_KEY"])
body = json.loads(r'''{
"model": "deepseek/deepseek-v4.1-flash-1017",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Describe this image."
},
{
"type": "image_url",
"image_url": {
"url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4//8/AAX+Av4N70a4AAAAAElFTkSuQmCC"
}
}
]
}
],
"max_tokens": 400
}''')
response = client.chat.completions.create(
model=body["model"],
messages=body["messages"],
max_tokens=body["max_tokens"]
)
print(response)
vercel
// This operation uses HTTP directly.
const response = await fetch("https://api.tokenlane.de/v1/chat/completions", {
method: "POST",
headers: {
"Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
"Content-Type": "application/json",
},
body: `{
"model": "deepseek/deepseek-v4.1-flash-1017",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Describe this image."
},
{
"type": "image_url",
"image_url": {
"url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4//8/AAX+Av4N70a4AAAAAElFTkSuQmCC"
}
}
]
}
],
"max_tokens": 400
}`,
});
console.log(await response.text());
Anfrageformat
Das URL-Beispiel unten ist ein öffentlich abrufbares JPEG (mit HTTP 200 geprüft). Die Verfügbarkeit kann sich ändern; Inline-Daten bleiben die reproduzierbare Variante.
Bild-Hosts können automatische Abrufe ablehnen. Wikimedia verlangt einen beschreibenden User-Agent mit Kontaktangabe; dass ein Bild im Browser öffnet, belegt keinen Abruf durch Gateway oder Provider. 400 media_fetch_failed kann deshalb einen HTTP-400-Fehler der Quelle melden.
Eine direkt abrufbare Bild-URL oder Inline-Daten verwenden.
Der Bildteil:
{ "type": "image_url", "image_url": { "url": "https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=640&fm=jpg&q=80", "detail": "low" } }
| Feld | Wert |
|---|---|
type | image_url |
image_url.url | Eine http- oder https-URL mit Host, oder eine Base64-Data-URL: data:image/png;base64,<data> |
image_url.detail | Optional: low, high oder auto. Wird unverändert an den Anbieter gereicht; ein Anbieter darf es ignorieren. |
Mehrere Bilder als mehrere Teile in einer Nachricht senden. Das Gateway behält ihre Reihenfolge. Die Form wird vor dem Provider-Aufruf geprüft. Das Gateway kann entfernte URLs abrufen und Medien an die gewählte Route anpassen; für den Abruf gelten Sicherheits- und Größengrenzen. Ein Problem nennt das Feld, zum Beispiel $.messages[0].content[1].image_url.url.
Eine Grenze gilt überall: Der Request-Body darf 50 MiB groß sein, deshalb eingebettete Bilder klein halten.
Alle anderen Grenzen hängen von der Route ab. Jeder Anbieter legt erlaubte Typen, Größe je Bild, Gesamtgröße, Bildanzahl fest und ob er URLs lädt oder nur eingebettete Daten nimmt. Das Gateway prüft das vor dem Aufruf und überspringt eine Route, die nicht passt. Die meisten Routen nehmen nur eingebettete Daten, und PNG und JPEG werden überall akzeptiert. Ein Bild innerhalb dieser Grenzen passt heute zu jeder Route:
| Sicher auf allen Routen | |
|---|---|
| Typ | PNG oder JPEG |
| Größe | höchstens 3.000.000 Bytes dekodiert, 4.000.000 Zeichen als Data-URL |
| Anzahl | höchstens 4 Bilder, zusammen höchstens 3.000.000 Bytes |
| Übertragung | eingebettet als Data-URL |
Routen desselben Modells können sich unterscheiden. Die genauen Grenzen der Route, die eine Anfrage abgelehnt hat, stehen in issues.
Modell wählen
Ein Modell wählen, dessen architecture.input_modalities image enthält. Ein reines Textmodell scheitert mit 404 no_endpoint („No endpoints found that support image input“); remedy_hint listet Modelle, die Bilder annehmen. Ein Modell kann mehrere Routen mit unterschiedlichen Medienregeln haben; wer eine bestimmte braucht, legt sie mit provider.only fest (siehe Routing). Anbieter und Rechtsraum je Route stehen auf der Modellseite im Katalog.
Kosten
Ein Bild wird als Eingabe-Tokens zum Prompt-Preis abgerechnet. Wie viele Tokens es zählt, entscheidet der Anbieter (es hängt von der Pixelgröße ab); deshalb nach dem Aufruf usage.prompt_tokens und usage.prompt_tokens_details.image_tokens lesen. Eine Route mit eigenem Bildpreis weist ihn im Katalog als pricing.image oder pricing.image_token aus.
Bei eingebetteten Bildern mit lesbaren Abmessungen und einer verifizierten Tokenformel im Routenprofil schätzt das Gateway die Prompt-Reservierung aus Text und Bild-Patches, einem gegebenenfalls konfigurierten festen Anteil und einem Sicherheitsfaktor. Es berücksichtigt eine Skalierung nur, wenn das Profil sie ausdrücklich vorsieht.
Beispiel: Ein Bild mit 1.540 × 1.540 Pixeln benötigt bei 28 × 28 Pixeln je Patch und einem Token je Patch 3.025 Bild-Tokens; mit 10 % Sicherheitsaufschlag werden 3.328 reserviert. Die Ausgabemenge wird zusätzlich reserviert.
Abgerechnet wird die tatsächliche Nutzung des Anbieters; ungenutzte Reservierung wird freigegeben, tatsächliche Nutzung kann die Schätzung übersteigen.
Ohne Formel, außerhalb ihrer verifizierten Abmessungen ohne ausdrücklich vorgesehene Verkleinerung, bei unbekannten Abmessungen oder entfernten URLs bleibt die Reservierung des ganzen Kontextfensters bestehen. Ein niedrigeres max_tokens verkleinert nur den Ausgabeanteil. Liegt das Key-Limit oder Organisationsguthaben unter der Reservierung, folgt 402 insufficient_credits; remedy_hint nennt die Methode. Ungültige Bild-Header folgen weiterhin den obigen Validierungsregeln.
Häufige Fehler
| Status, Typ | Ursache und Abhilfe |
|---|---|
404 no_endpoint | Das Modell hat keine Bildeingabe. Abhilfe: Ein Modell aus remedy_hint nehmen. |
400 invalid_parameter, Issue invalid_url | Keine http(s)-URL mit Host und keine Base64-Data-URL. Abhilfe: Eine vollständige URL oder data:<type>;base64,<data> senden. |
400 invalid_parameter, Issue invalid_base64 | Die Data-URL enthält kein gültiges Base64. Abhilfe: Die Dateibytes ohne Zeilenumbrüche kodieren. |
400 invalid_parameter, failed_routing_step „Filter by Media Limits“ | Jede Route lehnt die Medien ab. Issue-Codes je Route: unsupported_media_type, media_type_mismatch (Bytes passen nicht zum angegebenen Typ), media_too_large, too_many_media, unsupported_media_transport (URL oder eingebettete Daten nicht akzeptiert, oder HTTPS verlangt). Abhilfe: Das Bild umwandeln oder verkleinern, eingebettet senden oder ein anderes Modell wählen. |
413 payload_too_large | Body über 50 MiB. Abhilfe: Die Bilder verkleinern. |
402 insufficient_credits | Die geschätzte Bildmenge oder ersatzweise das Kontextfenster übersteigt Key-Limit oder Guthaben. Abhilfe: remedy_hint lesen; Guthaben aufladen, Limit erhöhen oder eine passende Route wählen. |
400 media_fetch_failed | Das Gateway konnte das entfernte Bild nicht sicher abrufen, etwa weil die Quelle HTTP 400 liefert. Abhilfe: Direkt abrufbare URL oder Inline-Daten verwenden und Bot-Regeln des Hosts prüfen. |
400 invalid_parameter oder 502 provider_error | Der Provider hat das Bild abgelehnt oder konnte es nicht abrufen. Provider-Text wird nicht durchgereicht. Abhilfe: Bild inline senden, Typ und Größe prüfen. |
Bewährte Praxis
- Vor dem Senden verkleinern: Die meisten Modelle skalieren große Bilder herunter, zusätzliche Pixel kosten also Bandbreite und Tokens, ohne Details zu liefern. Eine längste Seite von etwa 1.500 bis 2.000 Pixeln genügt, sofern kein Kleingedrucktes nötig ist.
- PNG für Screenshots und Text, JPEG für Fotos.
- Private oder lokale Bilder eingebettet senden. URLs müssen für den Anbieter ohne Zugangsdaten erreichbar sein; nie Geheimnisse in eine URL schreiben, und signierte URLs laufen ab.
- Eine klare Frage je Bildgruppe stellen und sagen, was zurückkommen soll (Liste, Zahl, JSON).
- Text im Bild ist nicht vertrauenswürdig. Er kann Anweisungen enthalten; die Antwort nicht ohne eigene Prüfung Aktionen auslösen lassen.
- Für Vorschaubilder ein niedriges
detailverwenden, wenn der Anbieter es unterstützt.
Für KI-Agenten
- Endpunkt: [
POST /chat/completions](https://tokenlane.de/docs/gateway/post-L2NoYXQvY29tcGxldGlvbnM.md?lang=de); das Bild steht inmessages[].content[]. - Teil:
{"type":"image_url","image_url":{"url":"<https-URL oder data:image/png;base64,...>","detail":"low|high|auto"}}. - Pflicht: ein Modell mit
imageinarchitecture.input_modalities(ID ausGET /v1/modelskopieren). - Grenzen: Body 50 MiB; sicher auf allen Routen sind PNG oder JPEG, eingebettet, bis zu 4 Bilder, je und insgesamt 3.000.000 Bytes dekodiert.
- Kosten: tatsächliche Eingabe-Tokens (
usage.prompt_tokens_details.image_tokens). Reservierung: verifizierte Profilformel mit Abmessungen und Sicherheit; sonst das ganze Kontextfenster. - Fehler: 404
no_endpoint(keine Bildeingabe), 400invalid_parametermit den Issue-Codesinvalid_url,invalid_base64,unsupported_media_type,media_type_mismatch,media_too_large,too_many_media,unsupported_media_transport, 402insufficient_credits.