Authentifizierung

Einen Schlüssel erstellen

API-Schlüssel werden aus einem Workspace auf console.artfical.com ausgestellt, auf der API-Schlüssel-Seite. Einen Schlüssel dort zu erstellen ist der einzige Weg, einen zu bekommen; es gibt keine Möglichkeit, einen Schlüssel über die API selbst zu erzeugen oder zu rotieren, und das ist beabsichtigt: Das Erstellen eines Schlüssels ist eine sensible, selten ausgeführte Aktion, und sie hinter die eigene authentifizierte Sitzung der Konsole zu legen, hält sie außerhalb der Reichweite von allem, das nur Zugriff auf API-Ebene hat.

Ein Schlüssel sieht so aus, immer mit demselben Präfix:

tai-sk-bSL2q4ja-skivx5JVNaJyyDVtKgiBAxuq8yRzsb6-e8

Der vollständige Schlüsselwert wird genau einmal angezeigt, im Moment seiner Erstellung. Danach zeigt die Konsole nur noch eine gekürzte Form zur Identifikation (die ersten paar Zeichen und die letzten paar, die Mitte maskiert). Wenn Sie den vollständigen Wert verlieren, gibt es keine Möglichkeit, ihn wiederherzustellen; die einzige Option ist, diesen Schlüssel zu widerrufen und einen neuen zu erstellen. Behandeln Sie einen Schlüssel genauso, wie Sie ein Datenbankpasswort behandeln würden: speichern Sie ihn in einer Umgebungsvariable oder einem Secrets-Manager, nicht im Quellcode, und niemals in einer clientseitigen Anwendung, wo der Browser eines Endnutzers ihn auslesen könnte.

Den Schlüssel mit einer Anfrage senden

Jede Anfrage an /v1/chat/completions und /v1/models muss den Schlüssel in einem Standard-Authorization-Header enthalten, nach dem Bearer-Schema:

Authorization: Bearer tai-sk-bSL2q4ja-skivx5JVNaJyyDVtKgiBAxuq8yRzsb6-e8

Das ist genau dasselbe Header-Format, das die eigene API von OpenAI verwendet, weshalb es meist eine Änderung von nur einer Zeile ist, einen bestehenden, auf dem openai-SDK basierenden Client auf tAI zeigen zu lassen: setzen Sie base_url auf https://api.artfical.com/v1 und api_key auf Ihren tAI-Schlüssel, und der eigene Request-Code des SDKs muss sich nicht ändern.

# Python, mit dem offiziellen openai-Paket
from openai import OpenAI

client = OpenAI(
    base_url="https://api.artfical.com/v1",
    api_key="tai-sk-...",
)

response = client.chat.completions.create(
    model="tai-4.1",
    messages=[{"role": "user", "content": "Merhaba"}],
)
print(response.choices[0].message.content)

Eine Anfrage, bei der der Header ganz fehlt oder die ihn im falschen Format sendet (kein Bearer -Präfix, ein leerer Wert, ein Schlüssel, der sich nicht parsen lässt), wird genauso abgelehnt wie ein eindeutig ungültiger Schlüssel: mit einem 401 vom Typ authentication_error. Das genaue Format der Antwort finden Sie unter Fehler.

Workspaces und Geltungsbereich

Ein Schlüssel gehört zu genau einem Workspace und kann nur verwendet werden, um Anfragen im Namen dieses Workspace zu stellen. Es gibt kein Konzept eines Schlüssels, der sich über mehrere Workspaces erstreckt, und keine Möglichkeit, einem einzelnen Schlüssel nur teilweisen Zugriff auf bestimmte Modelle oder eine bestimmte Rate-Limit-Stufe zu geben; jeder Schlüssel in einem Workspace hat denselben Zugriff auf jedes Modell, das auf der Seite Modelle aufgeführt ist. Wenn Sie Nutzung oder Abrechnung zwischen zwei verschiedenen Projekten trennen müssen, ist die Antwort darauf, zwei Workspaces mit jeweils eigenen Schlüsseln anzulegen, nicht einen Schlüssel zwischen ihnen zu teilen.

Die Nutzung, die mit einem bestimmten Schlüssel entsteht, Anzahl der Anfragen, Token-Zahlen und geschätzte Kosten, wird diesem Schlüssel zugeordnet und ist auf der Nutzungsseite der Konsole sichtbar, begrenzt auf den Workspace, zu dem der Schlüssel gehört. Das dient ausschließlich der Sichtbarkeit auf Ihrer Seite; es hat keinen Einfluss darauf, wie eine Anfrage verarbeitet wird.

Ablauf

Ein Schlüssel kann optional mit einem Ablaufdatum erstellt werden (in 7, 30 oder 90 Tagen, oder nie, gewählt bei der Erstellung des Schlüssels). Sobald ein Schlüssel sein Ablaufdatum überschreitet, wird jede Anfrage damit mit demselben 401 authentication_error abgelehnt wie bei einem ungültigen Schlüssel, von außen nicht zu unterscheiden. Wenn Anfragen mit einem zuvor funktionierenden Schlüssel plötzlich mit 401 fehlschlagen, ist ein abgelaufener Schlüssel auf der API-Schlüssel-Seite das Erste, was Sie prüfen sollten, bevor Sie annehmen, dass etwas anderes kaputt ist.

Es gibt keine automatische Verlängerung. Ein Schlüssel, dessen Ablaufdatum näher rückt, muss durch einen neu erstellten ersetzt werden; die Konsole verlängert die Lebensdauer eines bestehenden Schlüssels nicht direkt.

Einen Schlüssel widerrufen

Ein Schlüssel kann jederzeit über die API-Schlüssel-Seite widerrufen werden, sofort und unwiderruflich. Ein widerrufener Schlüssel verhält sich aus Sicht der API genau wie ein abgelaufener: jede nachfolgende Anfrage damit erhält 401. Widerruf ist die richtige Reaktion auf einen durchgesickerten Schlüssel; es gibt keine Möglichkeit, den geheimen Wert eines Schlüssels direkt zu rotieren, nur den alten zu widerrufen und einen neuen als Ersatz zu erstellen.

Was ein Schlüssel allein nicht gewährt

Einen gültigen API-Schlüssel zu besitzen reicht aus, um Chat-Completion-Anfragen zu stellen und Modelle aufzulisten. Er gewährt keinen Zugriff auf irgendetwas in der Konsolen-Oberfläche selbst, auf Workspace-Einstellungen, Abrechnungsinformationen oder die Aktivität anderer Mitglieder; diese sind durch die eigene sitzungsbasierte Anmeldung der Konsole abgesichert, vollständig getrennt von API-Schlüsseln. Ein durchgesickerter API-Schlüssel ist ein echtes Problem, da er es jemandem erlaubt, Anfragen im Namen Ihres Workspace zu stellen (und die damit verbundene Nutzung zu verursachen), aber er legt Ihr Konsolen-Konto nicht selbst offen und erlaubt niemandem, sich als Sie anzumelden.