Der Key für die Doubao API wird nicht in der Doubao App erzeugt, sondern in der Konsole von Volcano Ark. Viele suchen zuerst am falschen Ort: in den Einstellungen der Chat-App oder im Kostencenter. Wichtig ist die Zuordnung: Doubao ist eine Modellfamilie, Volcano Ark ist die Plattform, die diese Modelle bereitstellt, und der Key gehört zu einem Workspace unter einem Volcano-Engine-Konto.
Dieser Artikel beschreibt den Weg von der Kontoeröffnung über die Key-Erstellung, Rechtebegrenzung und Modellprüfung bis zur 401-Fehleranalyse und Rotation. Preise und Kontingente richten sich nach der Konsole.
Hinweis: Doubao, Volcano Ark, Volcano Engine und ByteDance sind Marken oder Produktnamen von ByteDance und verbundenen Unternehmen. Dieser Artikel dient ausschließlich der technischen Erörterung; es besteht keine Zugehörigkeit, Vertretung oder Unterstützung durch die genannten Unternehmen. Schnittstellen, Berechtigungen und Kontingente können sich ändern; maßgeblich sind die offizielle Dokumentation und die Konsole.
1. Zuerst Konto, Key, Workspace und Modell auseinanderhalten
Key-Probleme entstehen häufig, weil die folgenden vier Objekte nicht zusammenpassen:
| Objekt | Ort | Funktion | Typischer Fehler |
|---|---|---|---|
| Volcano-Engine-Konto | Registrierung, Verifizierung, Kostencenter | Bestimmt Guthaben, Vertrag, Rechnung und Key-Zugehörigkeit | Privatkonto für Firmenlast, später passen Rechnung und Firmenzahlung nicht |
| API Key | Seite zur API-Key-Verwaltung in der Ark-Konsole | Identitätsnachweis beim Aufruf | Beim Kopieren Leerzeichen oder Zeilenumbrüche mitnehmen oder den Key in Frontend-Code schreiben |
| Workspace | Umschalter unten links in der Konsole | Trennt Ressourcen, Mitglieder und Rechte | Key und Endpoint liegen in verschiedenen Workspaces, der Aufruf wird abgelehnt |
| Modell oder Endpoint | Modellliste, Seite für Online-Inferenz | Legt fest, welches Modell tatsächlich aufgerufen wird | Modell-ID und Endpoint-ID mit ep--Präfix werden verwechselt |
Merkhilfe: Das Konto bestimmt, wer zahlt; der Workspace bestimmt, was sichtbar ist; der Key bestimmt, in welcher Identität aufgerufen wird; Modell oder Endpoint bestimmen die Version. Jede Fehlzuordnung kann als 401 oder 404 erscheinen.
2. Volcano Ark aktivieren und API Key erstellen
Am Beispiel der Volcano-Ark-Konsole:
- Volcano-Engine-Konto registrieren und die Verifizierung abschließen. Für Unternehmen empfiehlt sich ein Firmenkonto, damit Vertrag, Zahlung und Rechnungsempfänger übereinstimmen.
- Die Volcano-Ark-Konsole öffnen, die Aktivierung des Dienstes prüfen und die Region wählen, zum Beispiel Nordchina (Peking).
- Unten links den aktuellen Workspace kontrollieren. Neue Konten liegen meist im Standard-Workspace; für Teamprojekte sollte ein eigener Workspace angelegt werden.
- Die Seite zur API-Key-Verwaltung öffnen, „API Key erstellen“ wählen und einen Namen mit Zweck und Umgebung vergeben, etwa
doubao-dev-202610oderdoubao-prod-202610. - Den Key sofort in einen Passwortmanager oder einen serverseitigen Key-Management-Dienst übernehmen; niemals vollständig per Chat oder E-Mail versenden.
- Je einen Key für Test, Vorproduktion und Produktion anlegen, nicht gemeinsam nutzen. Laut aktueller Dokumentation lassen sich standardmäßig bis zu 50 API Keys pro Hauptkonto erstellen.
Ein Detail: Die offizielle Dokumentation weist darauf hin, dass neu erstellte Keys seit dem 17. September 2026 ein neues Klartextformat verwenden, die Authentifizierung aber unverändert bleibt; zuvor erstellte Keys bleiben gültig. Beide Erscheinungsformen sind normal; prüfen Sie zuerst, zu welchem Workspace der Key gehört.
3. Rechtegrenzen des Keys: Workspace, Modell-Whitelist und IP-Sperre
Ein API Key ist kein Generalschlüssel für das gesamte Konto. Laut Dokumentation kann ein Key nur auf Modellservices und Anwendungen des Workspaces zugreifen, in dem er erstellt wurde; workspaceübergreifende Projekte werden nicht unterstützt. Wird ein Endpoint in einen anderen Workspace verschoben, verliert der ursprüngliche Key seine Gültigkeit.
Bei oder nach der Erstellung lassen sich üblicherweise zwei Einschränkungen vornehmen:
- Modelle begrenzen: Der Key darf nur angegebene Modell-IDs oder benutzerdefinierte Endpoints aufrufen, damit er nicht für sämtliche Modelle verwendet werden kann.
- Quell-IP begrenzen: Eine IP-Whitelist senkt das Risiko, dass ein gestohlener Key von einem anderen Standort genutzt wird.
Für die Teamverwaltung empfiehlt es sich, Keys nach „Anwendung plus Umgebung“ statt nach Person zu trennen. Scheidet eine Person aus, werden nur die betroffenen Keys deaktiviert, andere Dienste laufen weiter; zugleich bleiben Aufrufprotokolle erhalten, aus denen hervorgeht, welcher Key wann welches Modell aufgerufen hat. Workspaces eignen sich zur Projektisolierung; Mitgliederrechte und Kontingente richten sich nach der Konsole.
4. Modell-ID und Inferenz-Endpoint-ID nicht verwechseln
Volcano Ark bietet zwei übliche Aufrufarten:
- Vordefinierte Inferenz: Ein Endpoint muss nicht vorab angelegt werden; im Feld
modelsteht direkt die Modell-ID, etwadoubao-seed-2-1-pro-260915. Modell-IDs enthalten meist ein Versionsdatum; das Suffix darf nicht aus dem Gedächtnis weggelassen werden. - Benutzerdefinierter Inferenz-Endpoint: Auf der Seite „Online-Inferenz“ anlegen;
modelenthält die Endpoint-ID, meist mit dem Präfixep-. Das eignet sich für feste Bereitstellungen, feingranulare Verwaltung oder LoRA-feinabgestimmte Modelle. Der Endpoint muss erst von „wird geplant“ auf „gesund“ wechseln, bevor Aufrufe stabil laufen.
Der Unterschied liegt nicht nur im Format. Laut Dokumentation muss bei signierten Aufrufen mit Access Key (AK/SK) im Feld model zwingend die Endpoint-ID stehen; mit einem API Key kann je nach Dokumentation die Modell-ID oder die Endpoint-ID verwendet werden. Bei manchen Modellen oder Konten ist der direkte Aufruf per Modell-ID nicht freigeschaltet; dann erscheint InvalidEndpointOrModel.ModelIDAccessDisabled, und es muss ein benutzerdefinierter Endpoint mit ep--ID angelegt werden.
Beim Erstellen des Keys muss also noch kein Modell gebunden werden. Vor dem Produktivstart ist jedoch zu prüfen: Das Modell ist im aktuellen Konto und in der Region verfügbar, der Key hat Zugriff, und das Feld model passt zur Aufrufart. Die Namenszuordnung richtet sich nach der Konsole und den Modellpreisen.
5. Den Key in Umgebungsvariablen ablegen
Schreiben Sie den Key nicht in Quellcode, Konfigurationsdateien oder Frontend-Bundles. Serverseitig haben sich Umgebungsvariablen bewährt:
# .env nur lokal oder im Key-Management-Dienst ablegen und in .gitignore aufnehmen
export ARK_API_KEY="Ihr Volcano-Ark-API-Key"
export ARK_MODEL_ID="doubao-seed-2-1-pro-260915"
# Bei benutzerdefiniertem Endpoint stattdessen:
# export ARK_ENDPOINT_ID="ep-Ihre-Endpoint-ID"
In Python über os.environ["ARK_API_KEY"] lesen, ohne Standardwert. Container nutzen Secret-Mounts, CI/CD verschlüsselte Variablen; Protokolle enthalten nur Key-Präfix oder Fingerabdruck. Browser, mobile Apps und Mini-Programme dürfen keinen Key halten, sondern müssen über ein Backend proxien.
6. 401, 403, 404 und 429 analysieren
| Symptom | Häufiger Fehlercode | Häufige Ursache | Behandlung |
|---|---|---|---|
| 401 | AuthenticationError |
Key fehlt, ist falsch, deaktiviert, oder der Bearer-Header fehlt |
Key erneut kopieren, Authorization-Header prüfen, gleicher Workspace für Key und Endpoint |
| 403 | AccessDenied |
Key ist auf Modelle oder IPs beschränkt, Konto hat keine Ressourcenrechte | Key-Whitelist, IP-Whitelist und Workspace-Rechte prüfen |
| 404 | InvalidEndpointOrModel.NotFound |
Modell-ID oder Endpoint-ID falsch, Ressource im Workspace nicht vorhanden | Vollständige ID aus der Konsole kopieren, Region und Workspace abgleichen |
| 404 | ModelNotOpen |
Modell im Konto noch nicht freigeschaltet | Modell in der Ark-Konsole aktivieren |
| 404 | InvalidEndpointOrModel.ModelIDAccessDisabled |
Konto darf nicht direkt per Modell-ID aufrufen | Benutzerdefinierten Inferenz-Endpoint anlegen und ep--ID verwenden |
| 429 | RateLimitExceeded.* |
RPM/TPM von Konto, Modell oder Endpoint überschritten | Parallelität senken, exponentiell wiederholen, bei Bedarf Erhöhung beantragen |
| 500/503 | InternalServiceError, ServerOverloaded |
Upstream-Dienst gestört oder überlastet | Kurz warten, erneut versuchen, Ausweichmodell oder -kanal bereithalten |
Reihenfolge der Analyse: zuerst HTTP-Status, dann Fehlercode, zuletzt Request-Body. Bei 401 nicht zuerst das Guthaben verdächtigen; unzureichendes Guthaben entspricht meist 403 mit AccountOverdueError. Bei 404 nicht zuerst den Code ändern, sondern Modell- und Endpoint-ID neu aus der Konsole kopieren.
7. Direkte offizielle Anbindung oder zentrales Gateway
Die direkte Anbindung eignet sich für Teams, die ausschließlich Doubao aufrufen, Verifizierung und Aufladung selbst erledigen können und Vertrag sowie Rechnung von Volcano Engine benötigen. Key und Base URL gehören immer zusammen: Ein offizieller Key funktioniert nur mit https://ark.cn-beijing.volces.com/api/v3, ein Gateway-Key nur mit der Gateway-Adresse. Eine Mischung führt meist direkt zu 401.
Ein zentrales Gateway eignet sich, wenn Doubao, DeepSeek und weitere Modelle parallel genutzt werden oder Rechnungen, Kontingente und Protokolle über einen Zugang laufen sollen. Bei der Auswahl ist zu prüfen: wie Modellnamen zugeordnet werden, ob Streaming und Tool-Aufrufe vollständig unterstützt werden, ob Keys pro Projekt begrenzt werden können, wie Störungen gemeldet werden und ob die Datenklauseln den Anforderungen genügen. Das ZSQH AI Gateway ist ein unabhängiger Drittanbieter-Zugang ohne Zugehörigkeit zu ByteDance; zum Testen lässt sich ein Konto auf der Registrierungsseite anlegen, die Abrechnung steht auf der Seite Modellpreise.
8. Rotation und Umgang mit einem Leck
Ein Key sollte wie ein Passwort einen Lebenszyklus haben und nicht bis zum Fehler benutzt werden:
- Einen neuen Key mit gleichen Rechten anlegen und zunächst nur Test- oder Canary-Instanzen zuweisen.
- Umgebungsvariablen oder den Key-Management-Dienst aktualisieren, den Dienst neu starten und Aufrufe prüfen.
- Fehlerrate, Latenz und Verbrauch 24 bis 72 Stunden beobachten. Erst nach Stabilisierung den alten Key deaktivieren, nicht sofort löschen, damit ein Rollback möglich bleibt.
- Bei Personalwechsel, Code-Leck oder einem Key in einem öffentlichen Repository sofort deaktivieren und neu erstellen; nicht nur das Passwort ändern.
- Die letzten Verbrauchsdetails und Protokolle auf ungewöhnliche Modelle, Zeiten oder Quell-IPs prüfen.
Die offizielle Dokumentation weist ebenfalls darauf hin, dass ein geleakter Key Dritten den Verbrauch Ihres Kontingents ermöglicht. Bei Entdeckung zuerst deaktivieren, um den Schaden zu stoppen, dann die Ursache untersuchen.
Verwandte Artikel:
- OpenAI-kompatible API: vollständiger Leitfaden
- Was ist ein API-Relay?
- DeepSeek API anbinden: Schritt für Schritt
Häufige Fragen
Lässt sich ein Doubao API Key in der Doubao App erzeugen?
Nein. Die Doubao App richtet sich an Endnutzer; API Keys werden auf der Seite zur API-Key-Verwaltung in der Volcano-Ark-Konsole erstellt.
Muss beim Erstellen eines Keys zuerst ein Modell gewählt werden?
In der Regel nicht. Der Key ist ein Aufrufnachweis unter einem Konto oder Workspace; das konkrete Modell wird im Feld model der Anfrage angegeben. Optional lassen sich auf dem Key erlaubte Modelle oder Endpoints einschränken.
Warum liefert derselbe Key gestern 200 und heute 401?
Häufige Ursachen: Der Key wurde deaktiviert oder rotiert, Key und Endpoint liegen in verschiedenen Workspaces, der Endpoint wurde verschoben, der Bearer-Header fehlt oder der Kontostatus ist anomal. Zuerst die Key-Zugehörigkeit prüfen, dann Header und Workspace.
Modell-ID oder Endpoint-ID mit ep--Präfix eintragen?
Bei vordefinierter Inferenz die Modell-ID, bei benutzerdefiniertem Endpoint die ep--ID; bei signierten Aufrufen mit Access Key zwingend die Endpoint-ID. Erscheint ModelIDAccessDisabled, unterstützt das Konto den direkten Modell-ID-Aufruf nicht und es muss ein Endpoint angelegt werden.
Was ist bei einem geleakten Key zuerst zu tun?
Den betroffenen Key sofort deaktivieren oder löschen, einen Ersatz-Key erstellen und die Serverkonfiguration aktualisieren, danach Verbrauch und Protokolle prüfen. Nicht zuerst den Leckpfad untersuchen, damit das Kontingent nicht weiter verbraucht wird.
