models.dev: KI-Modelldaten als TOML, ausgeliefert über api.json und catalog.json

Warum models.dev Model ID und Provider ID trennt

Der Ausgangspunkt ist im README klar benannt: Es gibt keine einzelne Datenbank, die alle verfügbaren KI-Modelle abdeckt. models.dev wurde als gemeinschaftlich beigetragenes Projekt gestartet, um diese Lücke zu schließen, und wird nach eigener Aussage intern in opencode verwendet. Die Projektbeschreibung formuliert den Kern der Sache so: Über das Feld Model ID lässt sich jedes Modell nachschlagen, weil es der Bezeichner ist, den das AI SDK verwendet.

Daraus folgt eine Trennung, die das ganze Repository durchzieht. Die Provider ID bezeichnet den Anbieter, also etwa anthropic, openai oder google, während die Model ID das Modell selbst meint. Beide erscheinen in Pfaden, in Dateinamen und in der API. Als Hauptsprache des Repositorys ist TypeScript angegeben, die Lizenz ist MIT. Das Projekt verzeichnet rund 6.600 Sterne und gut 1.550 Forks bei 284 offenen Issues; als Standardzweig ist dev eingetragen, und eine Liste von Veröffentlichungen liegt nicht vor.

api.json, models.json und catalog.json im Vergleich

Der Zugriff läuft über drei JSON-Endpunkte, die sich im Umfang der Antwort unterscheiden. Der vollständige Bestand, also Anbieter samt Endpunkten, liegt unter:

curl https://models.dev/api.json

Wer Fakten über ein Modell unabhängig vom Anbieter braucht, greift zu https://models.dev/models.json. Dort stehen Angaben zum Modell selbst, gleichgültig, wo es betrieben wird. Sollen Anbieterendpunkte und reine Modelldaten in einer einzigen Antwort ankommen, nennt das README https://models.dev/catalog.json.

Hinzu kommt ein vierter Endpunkt für Anbieterlogos als SVG-Dateien: https://models.dev/logos/{provider}.svg, wobei der Platzhalter durch die Provider ID ersetzt wird. Fehlt das Logo eines Anbieters, wird laut README ein Standardlogo ausgeliefert.

Was das README an dieser Stelle verschweigt, ist für den produktiven Einsatz wichtig: Es werden weder Authentifizierung noch Ratenbegrenzung noch die Größe der Antwort angegeben. Wer die Endpunkte in einen Dienst einbaut, kennt damit die Betriebsgrenzen nicht aus der Dokumentation.

models/openai/gpt-5.toml gegen providers/openai/models/gpt-5.toml

Die Daten liegen als TOML-Dateien im Repository, getrennt nach Anbieter und Modell, und sowohl die Webseite als auch die API werden daraus erzeugt. Der Aufbau folgt einer Logik, die man an einem Beispiel aus dem README gut sehen kann. Die Datei models/openai/gpt-5.toml beschreibt das zugrunde liegende GPT-5-Modell, während providers/openai/models/gpt-5.toml die anbieterspezifischen Bereitstellungsdetails hält, insbesondere die Preise.

Für die Modellebene listet das README Felder wie name, family, release_date, last_updated und knowledge, dazu die Merkmale attachment, reasoning, tool_call, structured_output und temperature. Hinzu kommen eine Tabelle [limit] mit context, input und output, eine Tabelle [modalities] sowie die Angaben open_weights, license, links, weights und benchmarks. Im Beispiel stehen release_date und last_updated auf 2025-08-07, die Grenzen auf context 400_000, input 272_000 und output 128_000, die Eingabemodalitäten auf text und image. Benchmark-Einträge führen name, score, metric und source, Gewichte führen label, url und format, im Beispiel mit safetensors.

Die Anbieterdatei hält dagegen eine Tabelle [cost] mit input 1.25, output 10.00 und cache_read 0.125 sowie eine eigene [limit]-Tabelle, die den Kontext auf 200_000 und die Ausgabe auf 32_000 begrenzt. Der Grundsatz lautet: Bei der Erzeugung gewinnen Anbieterfelder gegenüber den Modelldaten.

base_model, base_model_omit und die Override-only-Regel

Damit dieselben Modellfakten nicht mehrfach gepflegt werden müssen, führt das README den Schlüssel base_model ein. Er verweist auf eine TOML-Datei unter models/ im Format Anbieter geteilt durch Modell-ID. Die wichtigste Regel heißt Override-only: Nach base_model stehen ausschließlich anbieterspezifische Felder und Werte, die von der Basis abweichen. Beschreibung, structured_output, modalities, tool_call oder Datumsangaben sollen nicht wiederholt werden.

Feinheiten gibt es bei verschachtelten Tabellen. Wer [cost], [limit] oder [modalities] überschreibt, muss die vollständigen Werte der Tabelle angeben, weil Arrays und einfache Werte ersetzen, während einfache Objekte tief zusammengeführt werden. Für das Entfermen geerbter Felder existiert der optionale Schlüssel base_model_omit, der nach dem Zusammenführen greift und Punktpfade erwartet, etwa base_model_omit mit dem Eintrag limit.input.

Für Wrapper-Anbieter, die ein vorhandenes Modell spiegeln, zeigt das README ein Beispiel mit base_model auf anthropic/claude-opus-4-6. Dort werden reasoning_options mit einer effort-Auswahl aus low, medium, high und max sowie einer Untergrenze von 1_024 budget_tokens gesetzt, die Preise liegen bei input 5.00 und output 25.00. Das README weist außerdem darauf hin, dass veraltete [extends]-Tabellen nicht verwendet werden sollen.

provider.toml, logo.svg mit currentColor und die GitHub-Action-Prüfung

Wer einen neuen Anbieter ergänzen will, legt zunächst einen Ordner unter providers/ mit der Provider ID an. Darin entsteht eine provider.toml mit vier Schlüsseln: name für den Anzeigenamen, npm für den Paketnamen des AI SDK, env für die Liste der Umgebungsvariablen zur Authentifizierung und doc für einen Verweis auf die Anbieterdokumentation. Veröffentlicht ein Anbieter kein npm-Paket, stellt aber einen OpenAI-kompatiblen Endpunkt bereit, wird npm auf @ai-sdk/openai-compatible gesetzt und api mit der Basisadresse ergänzt; das README bezeichnet api in diesem Fall als erforderlich.

Ein Logo ist für neue Anbieter Pflicht. Die Datei logo.svg liegt im Anbieterordner, kommt ohne feste Größe und ohne feste Farben daher und verwendet currentColor für Füllungen und Striche. Die Modelldatei selbst liegt im Ordner models/ des Anbieters, ihr Dateiname ist die Model ID. Enthält die Kennung einen Schrägstrich, werden Unterordner verwendet.

Die fachliche Referenz für alle Felder liegt in packages/core/src/schema.ts. Neben den Merkmalsfeldern kennt das Schema Kostenschlüssel für input, output, reasoning, cache_read, cache_write, input_audio und output_audio, Grenzwerte für context, input und output, Modalitäten für Eingabe und Ausgabe sowie ein optionales Feld status mit den Werten alpha, beta oder deprecated. Eingereichte Änderungen prüft eine GitHub Action auf Pflichtfelder, Datentypen, Wertebereiche und TOML-Syntax. Für Verschiebungen von Anbieterfeldern in die Modellebene nennt das README den Befehl bun run compare:migrations, der einen Unterschied der geänderten TOML-Dateien ausgibt.

bun run dev in packages/web und OPENCODE_MODELS_PATH

Für die Arbeit an der Webseite setzt das Projekt auf Bun. Nach bun install im Wurzelverzeichnis folgt der Wechsel nach packages/web, dort startet bun run dev die Oberfläche unter http://localhost:3000. Das README beschreibt diesen Weg als einzigen dokumentierten Entwicklungsbefehl; Angaben zu Bereitstellung, Tests oder weiterer CI-Konfiguration fehlen abgesehen von der erwähnten Prüfaktion.

Spannend ist der zweite Weg, weil er zeigt, wofür die Datenbank gebaut wurde. Wer Änderungen am Datenbestand mit opencode ausprobieren will, baut die Webseite mit bun run build und setzt anschließend OPENCODE_MODELS_PATH auf dist/_api.json. Damit liest das Werkzeug den lokal erzeugten Stand statt der öffentlichen Endpunkte, und jede Ergänzung im TOML-Bestand lässt sich unmittelbar durchspielen. Genau diese Rückkopplung erklärt, warum das README die Pflege der Daten so stark in den Vordergrund rückt und ausdrücklich um Hilfe bei der Aktualisierung bittet.

Keine Ratenbegrenzung dokumentiert: Wann sich eine lokale Kopie lohnt

Die Grenzen des Projekts liegen weniger im Schema als im Betrieb. Das README nennt für keinen der vier Endpunkte eine Authentifizierung, eine Ratenbegrenzung oder eine Antwortgröße. Für einen Prototyp ist das bequem, für einen Dienst mit Last schwer kalkulierbar. Ebenso fehlt eine Liste von Veröffentlichungen, und als Standardzweig dient dev, was bei Automatismen, die auf Tags warten, zu keinem Ergebnis führt. Mit 284 offenen Issues ist zudem sichtbar, dass Korrekturen am Datenbestand Zeit brauchen können.

Die naheliegende Alternative besteht deshalb darin, die Daten nicht zur Laufzeit abzufragen, sondern eine Kopie mitzuführen. Wer den Stand über einen festen Commit einfriert und die TOML-Dateien ins eigene Repository legt, erhält nachvollziehbare Werte und merkt bei einer Aktualisierung sofort, welche Preise oder Kontextgrenzen sich bewegt haben. Der Preis dafür liegt in der Pflege: Neue Modelle erscheinen in der eigenen Kopie erst, wenn jemand sie nachzieht, während https://models.dev/api.json den gemeinschaftlich gepflegten Stand unmittelbar liefert. Für Werkzeuge, die Modellkennungen und Grenzwerte vorschlagen, überwiegt der Vorteil der aktuellen Datenbank; für Abrechnungslogik überwiegt die Kontrolle über eine eigene Kopie.

Redaktionelles Fazit

Geeignet ist models.dev für Werkzeuge, die Modellkennungen, Kontextgrenzen und Preise mehrerer Anbieter an einer Stelle brauchen und dabei die Model-ID aus dem AI-SDK-Umfeld verwenden. Weniger geeignet ist es als einzige Wahrheitsquelle für Abrechnungszwecke, weil das README keine Authentifizierung, keine Ratenbegrenzung und keine Antwortgröße für die Endpunkte nennt und der Datenbestand von Beiträgen abhängt. Vor dem Einstieg sollten Sie prüfen, ob https://models.dev/models.json die Felder liefert, die Ihr Code wirklich liest, ob der Zweig dev als Ausgangspunkt passt, und ob die von Ihnen benötigten Anbieter unter providers/ überhaupt eine provider.toml mit npm- und env-Schlüsseln besitzen.

Offizielle Quellen

1. Official documentation
2. Official README
3. Project repository