Zum Inhalt springen
Deutsch
API-Schlüssel abrufen
API-Anleitung

Authentifizierung

Als Markdown anzeigen Aktualisiert

Jeder Aufruf, der ein Modell ausführt oder deine Anfragen liest, benötigt einen API-Schlüssel. Der Katalog (GET /models, GET /categories), POST /quote und das OpenAPI-Dokument sind öffentlich.

API-Schlüssel

Erstelle und widerrufe Schlüssel unter https://doitong.com/developers/dashboard#keys. Ein Schlüssel sieht aus wie doitong_, gefolgt von 64 Hexadezimalzeichen, und wird nur einmal angezeigt, wenn du ihn erstellst. Sende ihn im Authorization-Header:

Terminal
curl https://api.doitong.com/v1/account -H "Authorization: Bearer $DOITONG_API_KEY"

X-API-Key: <key> funktioniert ebenfalls.

Eine Anfrage ohne Schlüssel erhält 401 mit dem Code missing_api_key; ein unbekannter, widerrufener oder abgelaufener Schlüssel erhält ebenfalls 401.

Berechtigungsbereiche

Jeder Schlüssel enthält Berechtigungsbereiche. Die Modell-API prüft diese:

Aktion Erforderlicher Berechtigungsbereich
Modell ausführen, Anfrage abbrechen, Dateien einer Anfrage löschen, Speichereinstellung ändern models:run (Schlüssel mit dem älteren images:create oder videos:create funktionieren ebenfalls)
Upload-URL erstellen models:run oder media:upload
Anfragen und Konto lesen models:read (ein Schlüssel, der Modelle ausführen darf, kann auch lesen)

Neue Schlüssel erhalten standardmäßig models:read und models:run. Ein Aufruf ohne den richtigen Berechtigungsbereich erhält 403 mit dem Code insufficient_scope.

Credit-Budgets

Ein Schlüssel kann ein eigenes Budget in API-Credits enthalten (1.000 API-Credits = 1 $), das vom Kontoinhaber festgelegt wird: ein Gesamtbudget, ein tägliches Budget (letzte 24 Stunden) oder beides. Bevor eine Ausführung abgerechnet wird, werden die Kosten mit dem verglichen, was der Schlüssel bereits über diese API ausgegeben hat (abzüglich Erstattungen). Eine Ausführung, die das Budget überschreiten würde, wird mit 402 budget_exceeded abgelehnt, und nichts wird abgerechnet.

Ein Schlüssel ohne Budget kann bis zum API-Guthaben ausgeben. Separat erhält eine Ausführung, die das API-Guthaben nicht decken kann, 402 insufficient_credits mit einer top_up_url.

GET https://api.doitong.com/v1/account zeigt das API-Guthaben und das verbleibende Budget des Schlüssels (beides in API-Credits):

200 OK · Konto
{
  "object": "account",
  "credits": 125000,
  "balance": { "credits": 125000, "usd": "125.00" },
  "top_up_url": "https://doitong.com/developers/dashboard#balance",
  "key": {
    "name": "Production server",
    "prefix": "doitong_3fa9c1e...",
    "scopes": ["models:read", "models:run"],
    "budget_remaining": 50000,
    "rate_limit": 3600,
    "rate_limit_remaining": 3571
  },
  "webhook_signing_secret": "whsec_..."
}

budget_remaining ist null, wenn der Schlüssel kein eigenes Budget hat.

Ratenlimits

Jeder Schlüssel darf 3600 Anfragen pro Stunde stellen, sofern sein Limit nicht anders festgelegt wurde. Jede authentifizierte Antwort enthält den aktuellen Status:

Header Bedeutung
X-RateLimit-Limit Im aktuellen Zeitfenster zulässige Anfragen
X-RateLimit-Remaining Im aktuellen Zeitfenster verbleibende Anfragen
X-RateLimit-Reset Unix-Zeitpunkt, an dem das Zeitfenster zurückgesetzt wird

Bei Überschreitung des Limits erhältst du 429 mit einem Retry-After-Header (Sekunden). Long Polling mit ?wait= zählt als eine Anfrage pro Aufruf, daher ist Warten günstiger als schnelles Polling.

Außerdem gibt es pro Konto ein Limit von 10 laufenden Anfragen (queued oder running). Der Start einer weiteren Anfrage gibt 429 too_many_inflight zurück; starte sie erneut, nachdem eine Anfrage abgeschlossen wurde.