API-Umstellung

Wir modernisieren den LLM Serving Service und bieten geringere Latenz, höheren Durchsatz und eine einheitlichere API.

Die neue API bringt konsistente Antwortstrukturen, eine strukturierte Fehlerbehandlung und zusätzliche Diagnoseinformationen. Das macht Integrationen leichter wartbar und Fehler leichter auffindbar.

Für einen reibungslosen Übergang bleibt die Legacy-API während der Umstellung verfügbar. So haben Anwendungen Zeit für die Anpassung und können das bisherige API-Verhalten weiter nutzen.

Dieser Abschnitt erklärt den Zeitplan der Umstellung, die nötigen Änderungen und die Kompatibilitätsaspekte für Anwendungen, die von der Legacy-API auf die neue API wechseln.

Überblick über die Umstellung

Die Umstellung läuft in drei Phasen. Die genauen Termine teilen wir Ihnen separat mit.

Endpunkt	Phase 1 (2 Wochen)	Phase 2 (2 Monate)	Phase 3 (dauerhaft)
Bestehend `llm-server.llmhub.t-systems.net`	Bisheriges Format	Neues Format	Abgeschaltet
Legacy `llm-server.legacy.ai.t-systems.net`	Bisheriges Format	Bisheriges Format	Abgeschaltet
Neu `llm-server.ai.t-systems.net`	Noch nicht verfügbar	Neues Format	Neues Format

So läuft die Umstellung ab

Phase 1 — Vorbereitung. Der bestehende Endpunkt verwendet weiterhin das Format der Legacy-API. Anwendungen, die auf die bisherige Antwort- oder Fehlerstruktur angewiesen sind, können auf den eigenen Legacy-Endpunkt https://llm-server.legacy.ai.t-systems.net/v2 wechseln. Dieser Endpunkt ist bereits verfügbar und behält das bisherige API-Verhalten bis Ende Phase 2 bei.

Phase 2 — Migration. Der bestehende Endpunkt wechselt auf das Format der neuen API. Der eigene Legacy-Endpunkt bleibt für Anwendungen verfügbar, die das bisherige Format noch benötigen. Der neue, dauerhafte Endpunkt wird verfügbar: https://llm-server.ai.t-systems.net/v1.

Phase 3 — Neue API. Der bestehende und der Legacy-Endpunkt werden abgeschaltet. Alle Anwendungen sollten den dauerhaften Endpunkt der neuen API verwenden: https://llm-server.ai.t-systems.net/v1.

Was Sie tun müssen

In Phase 1, falls nötig: Ist Ihre Anwendung auf das bisherige Antwort- oder Fehlerformat angewiesen? Dann stellen Sie die Base URL auf https://llm-server.legacy.ai.t-systems.net/v2 um. So läuft Ihre Anwendung bis Ende Phase 2 unverändert weiter. Der Legacy-Endpunkt ist bereits jetzt verfügbar. Sie können die Umstellung also schon vor Beginn von Phase 1 vornehmen.
Bis Ende Phase 2, alle Kunden: Stellen Sie auf den Endpunkt der neuen API https://llm-server.ai.t-systems.net/v1 und das neue Format um.

Die neue API verwendet /v1-Pfade, zum Beispiel /v1/chat/completions statt /v2/chat/completions. Wenn Sie auf die neue API wechseln, ändern Sie die Base URL auf https://llm-server.ai.t-systems.net/v1 und prüfen Sie Ihre Modellbezeichner und die Verarbeitung der Antworten.

Erste Schritte

Die meisten Anwendungen können migrieren, indem sie den Endpunkt ändern und ihre bisherige Authentifizierung und die übliche Anfragestruktur beibehalten.

Verbindungseinstellungen

Einstellung	Legacy-API	Neue API
Empfohlene Base URL	`https://llm-server.legacy.ai.t-systems.net/v2`	`https://llm-server.ai.t-systems.net/v1`
Authentifizierung	API-Schlüssel	API-Schlüssel
Unterstützte Schlüssel	Bestehende und neue API-Schlüssel	Bestehende und neue API-Schlüssel
Modellbezeichner	Bisherige Modellnamen	Bisherige Namen unterstützt; Provider-Präfixe empfohlen
Standardpfade	`/v2/...`	`/v1/...`

Kompatibilität der API-Schlüssel

Bestehende API-Schlüssel werden während der Umstellung weiter unterstützt.

Endpunkt	Bestehende API-Schlüssel	Neue API-Schlüssel
Bestehender Endpunkt	Unterstützt	Nicht unterstützt
Legacy-Endpunkt	Unterstützt	Unterstützt
Neuer Endpunkt	Unterstützt	Unterstützt

Mit der Einführung der neuen Verwaltungsoberfläche können Sie neue API-Schlüssel außerdem selbst erstellen und verwalten.

Bestehende API-Schlüssel werden zugunsten neu ausgestellter Schlüssel als veraltet eingestuft. Das bedeutet nicht, dass bestehende Schlüssel sofort ungültig werden. Eine spätere Stilllegung teilen wir Ihnen separat mit.

Anwendungen mit bestehenden Schlüsseln müssen diese nicht allein für den Zugriff auf die neue API ersetzen.

Modellbezeichner

Die neue API unterstützt Modellbezeichner mit und ohne Provider-Präfix. Sie können zum Beispiel diesen Modellnamen verwenden:

{
  "model": "gpt-6.1-sol"
}

Für eine explizite Wahl des Providers verwenden Sie das Format provider/model-name:

{
  "model": "azure/gpt-6.1-sol"
}

Das Präfix jedes Modells ist in /v1/models angegeben.

Provider-Präfixe sind empfohlen, aber nicht erforderlich. Mit dem Format provider/model-name wird das Routing vorhersehbarer, weil Sie den gewünschten Provider ausdrücklich wählen.

Modellabfrage

Wenn Ihre Anwendung Modellinformationen dynamisch abruft, prüfen Sie die Struktur der Modellliste: Die Legacy-API liefert sie unter GET /v2/models, die neue API unter GET /v1/models. Die neue API kann zusätzliche Modellfähigkeiten und Preisinformationen liefern, während einige Felder der Legacy-API nicht mehr im selben Format verfügbar sind.

Aspekt	Legacy-API	Neue API
Modellbezeichner	`gpt-6.1-sol`	`azure/gpt-6.1-sol`
Modellinhaber	`owned_by`, z. B. `T-Systems International`	Kann leer sein oder fehlen
Modelltyp	`meta_data.model_type`, z. B. `LLM`	Nicht enthalten
`object` auf oberster Ebene	`"list"`	Kann leer sein oder fehlen
`object` des Modelleintrags	`"model"`	Kann `"model"` sein oder fehlen
Kontextlänge	`meta_data.max_sequence_length`	`context_length`
Limit für Ausgabe-Tokens	`meta_data.max_output_length`	`max_output_tokens`
Zusätzliche Informationen	Metadaten zu Deployment und Provider	Kann `alias`, `max_input_tokens` und `pricing` enthalten

Was Sie bei den Modellen prüfen sollten

Wenn Ihre Anwendung Modelle dynamisch abruft, prüfen Sie, ob sie von Folgendem abhängt:

meta_data.model_type, um LLM- und Embedding-Modelle zu unterscheiden.
owned_by oder den object-Feldern der Modelleinträge.
dem Wert object: "list" auf oberster Ebene.
Modellbezeichnern ohne Präfix in der Modellliste.

Anwendungen mit strikter Antwortvalidierung sollten diese Unterschiede berücksichtigen.

Verfügbare Modelle, unterstützte Fähigkeiten und Konfigurationsdetails finden Sie unter Modelle und im Modellvergleich.

Modell-Datenblätter

Neue Datenblatt-Endpunkte unter /v1/datasheet werden in Kürze verfügbar sein. Sie beschreiben die Fähigkeiten und Parameter jedes Modells: welche Endpunkte ein Modell unterstützt, welche Parameter es akzeptiert und welche Werte und Standardwerte dafür gelten.

Das folgende Beispiel zeigt, wie ein Modell beschrieben wird:

{
  "name": "example-model",
  "max_input_tokens": 200000,
  "max_output_tokens": 64000,
  "supported_endpoints": ["/v1/chat/completions", "/v1/responses"],
  "supports_reasoning": true,
  "model_parameters": [
    {
      "id": "temperature",
      "type": "number",
      "default": 1,
      "range": { "min": 0, "max": 2 }
    },
    {
      "id": "reasoning_effort",
      "type": "select",
      "default": "medium",
      "options": ["low", "medium", "high"]
    }
  ]
}

Anfragen

Die neue API (https://llm-server.ai.t-systems.net/v1) unterstützt Standardanfragen für Chat Completions, einschließlich üblicher Parameter wie messages, temperature, top_p, tools und response_format, sofern das gewählte Modell sie unterstützt.

Die meisten Anwendungen können ihre bisherige Anfragestruktur mit nur kleinen Anpassungen weiterverwenden.

curl -X POST "https://llm-server.legacy.ai.t-systems.net/v2/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6.1-sol",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

curl -X POST "https://llm-server.ai.t-systems.net/v1/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "azure/gpt-6.1-sol",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

Das Beispiel für die neue API verwendet ein explizites Provider-Präfix (azure/) für ein vorhersehbares Routing; das Präfix jedes Modells ist in /v1/models angegeben. Ein Modellname ohne Präfix wie gpt-6.1-sol kann ebenfalls verwendet werden, wenn das Modell über die automatische Provider-Auflösung verfügbar ist.

Was sich bei Anfragen ändert

Aspekt	Legacy-API	Neue API
Standardparameter für Chat	Unterstützt	Unterstützt, abhängig von den Modellfähigkeiten
Modellbezeichner	Modellnamen ohne Präfix	Namen mit und ohne Provider-Präfix
Wahl des Providers	Über die bestehende Routing-Konfiguration	Explizite Wahl über Provider-Präfixe möglich
Tool Calling	Unterstützt	Unterstützt über die Standardfelder `tools` und `tool_calls`
Strukturierte Ausgabe	Unterstützt, sofern für das Modell verfügbar	Unterstützt, sofern für das Modell verfügbar
Provider-spezifische Parameter	In der Regel an den Provider weitergeleitet	Können gefiltert oder ignoriert werden, sofern nicht unterstützt
Anfragevalidierung	Validierung durch Gateway und Provider	Überwiegend abhängig vom Provider; einige Parameter können angepasst oder ignoriert werden

Was Sie bei Anfragen prüfen sollten

Für Standardintegrationen: Ändern Sie den Endpunkt. Bisherige Anfragestrukturen und Modellnamen ohne Präfix können weiter funktionieren, sofern das Modell verfügbar ist.

Für ein vorhersehbares Routing der Modelle: Verwenden Sie Modellbezeichner mit Provider-Präfix.

Für fortgeschrittene Integrationen: Wenn Ihre Anwendung Provider-spezifische Parameter, eigene Anfragefelder oder modellspezifische Funktionen nutzt, prüfen Sie, ob das gewählte Modell sie über die neue API unterstützt.

Die Anfragevalidierung hängt vom Modell-Provider und der Verarbeitung der API-Parameter ab. Einige nicht unterstützte Parameter oder Werte außerhalb des zulässigen Bereichs können angepasst oder stillschweigend ignoriert werden, statt abgelehnt zu werden.

Details zu Modellfähigkeiten und unterstützten Parametern finden Sie unter Modelle und im Modellvergleich.

Antworten

Die neue API (https://llm-server.ai.t-systems.net/v1) führt eine einheitliche Antwortstruktur über verschiedene Modell-Provider hinweg ein. Das verbessert die Konsistenz und erhält die zentralen Felder, die Standardintegrationen für Chat Completions nutzen: choices, message, finish_reason und usage bleiben verfügbar.

Beispiel: Erfolgreiche Antwort

Legacy-API
Neue API

{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "model": "gpt-6.1-sol",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 3,
    "total_tokens": 13
  }
}

{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "model": "gpt-6.1-sol",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 3,
    "total_tokens": 13
  },
  "extra_fields": {}
}

Der Wert von response.model kann bei einigen Providern außerdem vom angefragten Modellbezeichner abweichen.

Was sich bei Antworten ändert

Aspekt	Legacy-API	Neue API
Antwortstruktur	Am Provider orientiertes Antwortformat	Einheitliches Chat-Completion-Format
Standardfelder	`choices`, `message`, `usage` usw.	Dieselben zentralen Felder
Token-Nutzung	Ursprüngliche Nutzungsinformationen des Providers	Details können je nach Provider variieren; optionale Felder mit dem Wert `0` können fehlen
Optionale Felder	Können explizite `null`- oder leere Werte enthalten	Einige optionale Felder können fehlen
`model` in der Antwort	In der Regel der angefragte Modellbezeichner	Kann den vom Provider gemeldeten Modellnamen enthalten, der vom angefragten Bezeichner abweichen kann
Provider-spezifische Metadaten	In der Regel erhalten	Können vereinheitlicht werden oder fehlen
Zusätzliche Informationen	Provider-spezifische Felder	Optionale Diagnose-Metadaten, einschließlich Latenzinformationen

Details zur Token-Nutzung

Die Standardfelder zur Token-Nutzung bleiben verfügbar, weitere Details hängen jedoch vom gewählten Modell und Provider ab. Einige Provider liefern zum Beispiel eine detaillierte Aufschlüsselung der Completion-Tokens, andere liefern andere Nutzungsfelder oder lassen optionale Details ganz weg.

Felder wie completion_tokens_details, reasoning_tokens oder Provider-spezifische Token-Kategorien sollten daher als optional behandelt werden. Details mit dem Wert 0 können außerdem fehlen, statt ausdrücklich als 0 zurückgegeben zu werden.

Anwendungen, die den Token-Verbrauch erfassen, sollten diese Unterschiede bei der Verarbeitung der Nutzungsinformationen berücksichtigen.

Zusätzliche Metadaten der Antwort

Die neue API kann zusätzliche Diagnoseinformationen im Objekt extra_fields liefern. Je nach Anfrage und Modell kann dies Folgendes enthalten:

Latenzinformationen — helfen, die Verarbeitungszeit der Anfrage zu verstehen.
Routing-Informationen — liefern weitere Details dazu, wie die Anfrage verarbeitet wurde.
Metadaten der Provider-Antwort — zusätzliche Informationen, sofern verfügbar.

Diese Felder sind optional und sollten nicht als Teil der erforderlichen Standard-Antwortstruktur behandelt werden.

Was Sie bei Antworten prüfen sollten

Für Standardintegrationen: Anwendungen, die vor allem choices, message, finish_reason und die üblichen Felder zur Token-Nutzung verwenden, benötigen in der Regel nur minimale Änderungen bei der Verarbeitung der Antwort.

Für die Erkennung des Modells: Prüfen Sie Code, der davon ausgeht, dass response.model immer dem angefragten Modellnamen entspricht.

Für strikte Antwortvalidierung: Lassen Sie fehlende optionale Felder zu und unterstützen Sie zusätzliche Metadaten der Antwort.

Für die Abrechnung von Tokens: Prüfen Sie Provider-spezifische Nutzungsfelder und gehen Sie nicht davon aus, dass jeder Provider dieselbe Aufschlüsselung der Tokens liefert.

Für Provider-spezifische Integrationen: Prüfen Sie Code, der von nicht standardisierten Antwortfeldern abhängt.

Streaming

Die neue API (https://llm-server.ai.t-systems.net/v1) unterstützt weiterhin Server-Sent Events (SSE). Das meiste Streaming-Verhalten bleibt kompatibel, die Token-Nutzung wird jedoch anders zurückgegeben. Grundlagen zum Streaming finden Sie unter Streaming.

Was sich beim Streaming ändert

Verhalten	Legacy-API	Neue API
Streaming-Protokoll	SSE	SSE
Token-Nutzung	Separater letzter Chunk mit der Nutzung	Im letzten Chunk der Completion enthalten
Nutzung standardmäßig	Ohne ausdrückliche Anforderung enthalten	Ohne ausdrückliche Anforderung enthalten
Abschlusszeichen	`[DONE]`	`[DONE]`
Fehler während des Streamings	Stream kann ohne ausdrückliches Fehlerereignis enden	Strukturierte Fehler können im Stream enthalten sein

Token-Nutzung im Stream

Legacy-Chunk
Neuer Chunk

{
  "choices": [],
  "usage": {
    "total_tokens": 150
  }
}

{
  "choices": [
    {
      "index": 0,
      "delta": {},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "total_tokens": 150
  }
}

Beide APIs liefern die Token-Nutzung bei erfolgreichen Streaming-Antworten standardmäßig mit, auch wenn stream_options.include_usage nicht ausdrücklich angefordert wird. Der wesentliche Unterschied ist, wo diese Information im Stream steht.

Was Sie beim Streaming prüfen sollten

Anwendungen, die SSE-Antworten direkt verarbeiten, sollten die Token-Nutzung aus dem Chunk lesen, der das Feld usage enthält, und sich nicht auf einen separaten Chunk mit leerem choices-Array verlassen.

Gehen Sie nicht davon aus, dass die Details zur Nutzung beim Streaming bei allen Modell-Providern dieselbe Struktur haben.

Fehlerbehandlung

Die neue API (https://llm-server.ai.t-systems.net/v1) führt strukturierte Fehlerantworten ein. Damit können Anwendungen Fehler leichter erkennen und einheitlich behandeln. Standard-HTTP-Statuscodes zeigen weiterhin das Ergebnis einer Anfrage an, für bestimmte Fehlerfälle gibt es nun genauere Statuscodes. Die allgemeine Fehlerreferenz finden Sie unter Fehlercodes.

Was sich bei der Fehlerbehandlung ändert

Szenario	Legacy-API	Neue API
Fehlender API-Schlüssel	403	401
Ungültiger API-Schlüssel	401	401
Gesperrter oder deaktivierter Schlüssel	401	403
Modell nicht gefunden	404	400 bei Fehlern der Modellauflösung
Zugriff auf das Modell verweigert	404	403
Rate-Limit überschritten	429	429
Budget überschritten	429	402
Ungültige Anfrage	400, manchmal als Klartext	400, strukturiertes JSON
Verbindungsfehler zum Provider	500	502
Timeout beim Provider	500	504

Beispiel: Fehlerantwort

Die Legacy-API liefert Fehlerinformationen des Providers in der Regel als String in detail. Die neue API liefert strukturierte Fehlerinformationen.

Legacy-API (HTTP 400)
Neue API (HTTP 400)

{
  "detail": "Error: 400 - Bad Request - {\"error\":{\"message\":\"Invalid request parameter\",\"type\":\"invalid_request_error\"}}"
}

{
  "error": {
    "message": "Invalid request parameter",
    "type": "invalid_request_error",
    "code": "invalid_value",
    "param": "messages[0].role"
  }
}

Mit strukturierten Fehlerfeldern greifen Anwendungen auf Fehlerdetails zu, ohne eine eingebettete Fehlermeldung des Providers auswerten zu müssen.

Was Sie bei der Fehlerbehandlung prüfen sollten

Für die übliche Behandlung von HTTP-Fehlern: Anwendungen können sich weiterhin auf die HTTP-Statuscodes der Antwort verlassen.

Für eigene Fehlerbehandlung: Prüfen Sie Code, der von bestimmten Statuscodes, dem Text von Fehlermeldungen oder dem Feld detail der Legacy-API abhängt.

Verwenden Sie den tatsächlichen HTTP-Status der Antwort als wichtigsten Hinweis und behandeln Sie Fehlerfelder wie type, code und param als optional.

Rate-Limits und Wiederholungen

Die neue API unterscheidet zwischen Rate-Limits des Providers, Rate-Limits des Service und Budgetbeschränkungen.

Szenario	HTTP-Status	Informationen zur Wiederholung
Rate-Limit des Providers	429	Vom Provider gelieferte Informationen zur Wiederholung können verfügbar sein
Rate-Limit des Service	429	Kein `Retry-After`-Header; Informationen zum Zurücksetzen können in der Fehlermeldung stehen
Budget überschritten	402	Kein `Retry-After`-Header; Informationen zum Budget können in der Fehlermeldung stehen

Wenn ein Provider einen Retry-After-Header liefert und dieser in der Antwort weitergegeben wird, sollten Anwendungen ihn beachten. Bei Rate-Limits des Service verwenden Sie eine eigene Backoff-Strategie; siehe Rate-Limits.

Fehler zum Budget sollten gesondert behandelt werden und keine automatischen Wiederholungen auslösen.

Antwortvalidierung

Prüfen Sie den Content-Type der Antwort, bevor Sie den Body auswerten. Einige nicht unterstützte API-Pfade oder Methoden können HTML statt JSON zurückgeben.

Ein erfolgreicher HTTP-Status allein garantiert nicht, dass die Antwort die erwartete API-Struktur enthält.

Fehlersuche

Wenn Sie ein Problem melden, geben Sie den Zeitpunkt der Anfrage, den Endpunkt, den HTTP-Status und eine verfügbare Request- oder Trace-ID an. So kann der Support Anfragen schneller untersuchen.

Zusammenfassung

Die neue API bietet eine besser skalierbare und einheitlichere Grundlage für LLM-Integrationen und bleibt mit den üblichen Funktionen von Chat Completions kompatibel. Prüfen Sie vor der Migration Ihre Modellbezeichner, Anfrageparameter, die Verarbeitung der Antworten, die Auswertung der Token-Nutzung, das Streaming-Verhalten und die Fehlerbehandlung.

Alle Anwendungen sollten bis Ende Phase 2 auf den dauerhaften Endpunkt der neuen API umgestellt sein. Bei Fragen oder für Unterstützung bei der Migration erreichen Sie uns unter AI@t-systems.com.