# 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](https://tokenlane.de/docs/guides/files.md?lang=de) 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
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

```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

```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

```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](https://foundation.wikimedia.org/wiki/Policy:Wikimedia_Foundation_User-Agent_Policy); 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:

```json
{ "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](https://tokenlane.de/docs/guides/routing-and-fallbacks.md?lang=de)). Anbieter und Rechtsraum je Route stehen auf der Modellseite im [Katalog](https://tokenlane.de/models).

## 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 `detail` verwenden, 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 in `messages[].content[]`.
- Teil: `{"type":"image_url","image_url":{"url":"<https-URL oder data:image/png;base64,...>","detail":"low|high|auto"}}`.
- Pflicht: ein Modell mit `image` in `architecture.input_modalities` (ID aus `GET /v1/models` kopieren).
- 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), 400 `invalid_parameter` mit den Issue-Codes `invalid_url`, `invalid_base64`, `unsupported_media_type`, `media_type_mismatch`, `media_too_large`, `too_many_media`, `unsupported_media_transport`, 402 `insufficient_credits`.
