Kernleitfäden
Erstellen einer zuverlässigen TokenLab-Integration
Behalten Sie Kosten, Wiederholungsversuche, API-Keys und Anfrageprotokolle unter Kontrolle
Eine gute Integration macht Preis- und Modellentscheidungen transparent, übersteht gewöhnliche Netzwerkfehler und legt niemals einen API-Key im Browser offen. Die folgenden Praktiken gelten für Chat-, Bild-, Video-, Audio- und andere TokenLab-APIs.
Wählen Sie Modelle mit aktuellen Daten
Modellnamen, Funktionen und Preise ändern sich. Lesen Sie die Models API oder die Modellseiten, anstatt eine permanente Liste im Code oder in der Dokumentation zu führen.
Für einen neuen Anwendungsfall:
- Filtern Sie Modelle nach der Funktion, die Ihr Produkt benötigt.
- Vergleichen Sie die aktuellen TokenLab-Preise.
- Testen Sie eine kleine Auswahl mit repräsentativen Benutzeranfragen.
- Halten Sie die Modell-ID in jeder Anfrage explizit fest.
Wechseln Sie Modelle nicht unbemerkt. Ein Austausch kann die Ausgabequalität, den Preis, die Kontextlänge, verfügbare Tools oder die Medienunterstützung verändern.
Setzen Sie eine Obergrenze für Kosten
Begrenzen Sie bei Textmodellen die Ausgabe auf die Länge, die Ihr Produkt tatsächlich verwenden kann. Der Parametername hängt von der API und dem Modell ab; prüfen Sie daher die Modellseite, bevor Sie max_tokens oder max_output_tokens senden.
Kürzere Anweisungen sind nicht automatisch besser, aber duplizierter Kontext und wiederholte Standardtexte erhöhen immer die Input-Tokens. Halten Sie stabile Anweisungen prägnant und senden Sie nur den Verlauf, der für die nächste Antwort erforderlich ist.
Bei Anfragen für Bilder, Videos, Musik, 3D und Worlds hängen die Kosten oft von der Anzahl der Ausgaben, der Dauer, der Auflösung oder anderen Medienoptionen ab. Zeigen Sie die aktuelle Schätzung an, bevor ein Benutzer eine teure Generierung bestätigt, sofern die API eine solche bereitstellen kann.
Streamen Sie lange Textantworten
Streaming zeigt die Antwort an, während sie eintrifft, und verhindert, dass der Benutzer auf die vollständige Antwort warten muss. Es reduziert nicht die Token-Kosten.
Ein vollständiges Beispiel mit Client-Einrichtung und Abschlussprüfungen finden Sie unter Streaming.
Behandeln Sie eine Verbindungsunterbrechung als unvollständige Antwort. Präsentieren Sie keine Teilausgabe als erfolgreich abgeschlossen und wiederholen Sie eine Anfrage nicht automatisch, wenn dies einen zweiten Nebeneffekt oder eine erneute Abrechnung verursachen könnte.
Wiederholen Sie Anfragen nur, wenn es sicher ist
Wiederholen Sie 429-Antworten nach Retry-After oder retry_after. Ein kurzes exponentielles Backoff ist für vorübergehende 5xx-Antworten angemessen. Authentifizierungs-, Validierungs-, Guthaben- und Kontextlängenfehler erfordern eine Änderung durch die Anwendung oder den Benutzer; das erneute Senden derselben Anfrage wird diese nicht beheben.
Siehe Rate Limits für ein Beispiel für eine begrenzte Wiederholung, die Retry-After respektiert und doppelte SDK-Wiederholungen deaktiviert.
Legen Sie ein Wiederholungslimit und ein Gesamtzitlimit fest. Speichern Sie bei der Medienerstellung die zurückgegebene Task-ID. Senden Sie für die unter Retry safely with an idempotency key aufgeführten Anfragen einen Idempotency-Key, damit eine Wiederholung nach einem Timeout nicht dieselbe Anfrage zweimal ausführen oder berechnen kann.
Bewahren Sie API-Keys auf dem Server auf
Betten Sie niemals einen TokenLab API-Key in Browser-JavaScript, ein mobiles Anwendungs-Bundle, ein öffentliches Repository oder ein für den Client sichtbares Protokoll ein.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=30.0,
max_retries=0,
)Verwenden Sie separate API-Keys für Entwicklung, Produktion und unabhängige Anwendungen. Geben Sie jedem Key nur die Modelle und das Ausgabenlimit, das er benötigt. Widerrufen Sie einen Key sofort, wenn er möglicherweise offengelegt wurde.
Führen Sie nützliche Anfrageprotokolle
Speichern Sie die Identifikatoren, mit denen Sie eine Benutzeraktion mit Nutzungs- und Support-Datensätzen verknüpfen können:
request_idfür die API-Anfragetask_idfür asynchrone Generierungbilling_transaction_idsofern zurückgegeben- Modell-ID und Endpunkt
- Ihre eigene Benutzer-, Projekt- oder Job-ID
Protokollieren Sie keine API-Keys, Management-Tokens, vollständigen privaten Prompts, privaten Medien oder signierten URLs. Nutzungsdatensätze in der Console und der Management API sind die Quelle für die abgerechneten Beträge; die Token-Anzahl der Modellantwort allein beschreibt möglicherweise nicht die endgültige Gebühr.
Design für asynchrone Arbeit
Bild-, Video-, Musik-, 3D- und Worlds-APIs können zurückkehren, bevor das Ergebnis fertig ist. Speichern Sie die Task-ID, pollen Sie GET /v1/tasks/{id} und stoppen Sie erst bei completed oder failed. Ein Status-Lookup von failed bedeutet nicht, dass die Generierung selbst fehlgeschlagen ist.
Siehe Asynchrone Jobs und Polling für Informationen zu Abbruch, Timeout und der Handhabung doppelter Anfragen.
Vor dem Start
- Führen Sie repräsentative Anfragen mit dem exakten Modell und API-Format aus, das Sie ausliefern werden.
- Überprüfen Sie sowohl Erfolgs- als auch häufige Fehlermeldungen.
- Bestätigen Sie, dass der in Ihrem Produkt angezeigte Preis mit dem aktuellen TokenLab-Preis übereinstimmt.
- Machen Sie Aktualisierungen, Netzwerk-Timeouts und wiederholte Klicks sicher.
- Ermöglichen Sie es, ein für den Benutzer sichtbares Ergebnis auf seine Request ID zurückzuführen.