API-Integration

Wie andere Systeme (Projekte, Backends, Tools) das interne LLM aufrufen.

Basis

Base-URL	`https://llm.devfader.de`
Authentifizierung	Header `Authorization: Bearer DEIN_KEY`
Content-Type	`application/json`

Jedes aufrufende System bekommt einen eigenen API-Key. So ist im Log nachvollziehbar, wer was nutzt.

Endpunkte

Methode	Pfad	Zweck
GET	`/health`	Erreichbarkeit prüfen (ohne Key)
GET	`/v1/models`	Installierte Modelle auflisten
POST	`/v1/chat`	Text-Chat / Textaufgaben
POST	`/v1/extract`	Bild → Text, Felder aus Bild

POST /v1/chat

Feld	Pflicht	Beschreibung
`messages`	ja	Verlauf aus `{role, content}` — role = system/user/assistant
`model`	nein	Standard: qwen2.5:3b-instruct
`stream`	nein	`true` = Antwort als Server-Sent-Events
`options`	nein	direkt an Ollama, z.B. `{"temperature":0.7}`

curl https://llm.devfader.de/v1/chat \
  -H "Authorization: Bearer DEIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Fasse zusammen: ..."}]}'

POST /v1/extract

Text aus einem Bild lesen. Das Bild Base64-kodiert im Feld image mitschicken.

Feld	Pflicht	Beschreibung
`image`	ja	Bild als Base64
`mode`	nein	`auto` (Standard), `ocr`, `vision`
`instruction`	nein	freie Anweisung zum erkannten Text
`fields`	nein	Liste von Feldnamen → als JSON-Objekt zurück

Antwortfelder

Feld	Beschreibung
`method`	`ocr` oder `vision` — welcher Weg genutzt wurde
`text`	der komplette erkannte Text
`result`	Antwort auf `instruction` (sonst null)
`fields`	extrahierte Felder als Objekt (sonst null)
`ocr_confidence`	OCR-Konfidenz 0–100 (null bei Vision)

Gezielte Felder extrahieren

IMG=$(base64 -w0 rechnung.png)
curl https://llm.devfader.de/v1/extract \
  -H "Authorization: Bearer DEIN_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"image\":\"$IMG\",\"fields\":[\"rechnungsnummer\",\"datum\",\"summe\"]}"

Antwort:

{
  "method": "ocr",
  "fields": {
    "rechnungsnummer": "2024-0815",
    "datum": "12.03.2024",
    "summe": "149,00 EUR"
  },
  "text": "...",
  "duration_ms": 2100
}

Fehlercodes

Code	Bedeutung
401	API-Key fehlt oder ist ungültig
429	Rate-Limit überschritten (30 Anfragen/Minute pro Key)
400	Bild konnte nicht gelesen werden
502	LLM-Backend (Ollama) nicht erreichbar oder Fehler

Beispiel: Node.js

import { readFileSync } from "fs";

const image = readFileSync("rechnung.png").toString("base64");

const res = await fetch("https://llm.devfader.de/v1/extract", {
  method: "POST",
  headers: {
    "Authorization": "Bearer DEIN_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    image,
    mode: "auto",
    fields: ["rechnungsnummer", "datum", "summe"],
  }),
});
const data = await res.json();
console.log(data.fields);

Hinweis: Das System läuft auf CPU — bei Last werden Anfragen in eine Warteschlange gestellt. Chat braucht einige Sekunden, eine Vision-Extraktion bis zu ~1 Minute.