Seedance ist ein Videogenerierungsmodell von ByteDance. Beim Aufruf der API ist die erste Hürde nicht der Prompt, sondern ein nutzbarer API Key an der richtigen Stelle. Viele 401-Fehler entstehen nicht durch einen falschen Schlüssel, sondern durch Request-Header, Base URL oder den Aktivierungsstatus des Modells.

Dieser Artikel beschreibt die Kette „Registrierung – Erstellung – Konfiguration – Fehlersuche – Rotation“ und erklärt den Unterschied zwischen einem offiziellen Key und einem Gateway-Key.

Hinweis: Seedance, ByteDance, Doubao, Volcano Engine und Volcano Ark sind Namen und Marken ihrer jeweiligen Inhaber. Dieser Artikel dient ausschließlich der technischen Erläuterung und begründet keine Kooperation, Vertretung oder Geschäftsbeziehung. Schnittstellen und Preise richten sich nach der offiziellen Dokumentation oder den Seiten des Anbieters.

1. Zuerst Konto, Modell und Key auseinanderhalten

Der Aufruf von Seedance umfasst drei Ebenen: Plattformkonto, Modellservice und Zugangsnachweis. Das Konto trägt Identitätsprüfung und Abrechnung, das Modell muss auf der Plattform separat aktiviert werden, und der API Key ist lediglich der Identitätsnachweis bei der Anfrage. Alle drei sind nötig und können einander nicht ersetzen.

Ein Key ist kein Kontopasswort. Er dient nicht zur Anmeldung in der Konsole und erst recht nicht als Mitgliedsnachweis auf einer Website. Bei einer Offenlegung können Dritte mit dem Guthaben des Kontos Aufgaben einreichen. Deshalb muss er ab der Erstellung wie ein vertrauliches Datum behandelt werden.

Die Datenebene der offiziellen Schnittstelle verwendet üblicherweise Authorization: Bearer <API_KEY>; Verwaltungsschnittstellen für Keys und Endpoints benötigen in der Regel eine AK/SK-Signatur. Die beiden Nachweisarten haben unterschiedliche Zwecke. AK/SK der Verwaltungsebene gehören nicht in Anfragen der Datenebene.

2. Weg A: offizieller Key über Volcano Ark

Der offizielle Weg eignet sich für Teams, die direkt anbinden und Cloud-Ressourcen sowie Abrechnung selbst verwalten. Die üblichen Schritte:

  1. Ein Volcano-Engine-Konto registrieren und die Identitätsprüfung sowie die erforderlichen Angaben zum Rechtsträger abschließen.
  2. Die Volcano-Ark-Konsole öffnen und das geplante Seedance-Modell aktivieren; ohne Aktivierung liefert ein Aufruf häufig einen Fehler der Art ModelNotOpen.
  3. Die Seite zur API-Key-Verwaltung aufrufen und einen neuen Key anlegen. Der Name sollte Zweck und Umgebung enthalten, zum Beispiel seedance-prod-server.
  4. Den Schlüssel sofort kopieren und speichern. Viele Plattformen zeigen ihn nur einmal bei der Erstellung vollständig an; nach dem Schließen der Seite ist er nicht mehr sichtbar.
  5. Mit einer minimalen Konfiguration eine kurze Aufgabe einreichen und prüfen, ob Authentifizierung, Modellaktivierung, Kontingent und Abrechnung funktionieren.
  6. Den Key in eine serverseitige Umgebungsvariable oder einen Key-Management-Dienst schreiben, nicht in Code, Dokumente oder Chatverläufe.

Die Menübezeichnungen der Konsole können sich mit der Version ändern; maßgeblich ist die Quickstart-Dokumentation. Wenn mehrere Personen dasselbe Konto nutzen, sollte für jedes System ein eigener Key angelegt werden. Das erleichtert Audit und Deaktivierung.

3. Weg B: Key über ein kompatibles Gateway

Wenn das Team bereits ein einheitliches API-Gateway verwendet, muss meist kein separates Cloud-Konto gepflegt werden. Nach der Registrierung bei ZSQH AI Gateway lässt sich in der Konsole ein Key erstellen; anschließend wird in der Modellliste geprüft, ob der Seedance-Videokanal aktiviert ist und welche Modelle und Parameter unterstützt werden.

Wichtig: Gateway-Key und offizieller Key sind nicht austauschbar. Base URL, Authentifizierungsheader, Aufgabenfelder, Callback-Verfahren und Abrechnungslogik können abweichen. Beim Wechsel von offiziell zu Gateway oder zurück muss die gesamte Konfiguration ersetzt werden. Nur den Key zu tauschen, führt beim Einreichen von Aufgaben häufig zu Fehlern.

Die Registrierung erfolgt über ZSQH AI Gateway, verfügbare Modelle und Abrechnungsarten stehen auf der Seite Modellpreise. Preise können angepasst werden; vor einer Buchung gilt die aktuelle Anzeige auf der Seite.

4. Offizieller Key oder Gateway-Key?

Dimension Offizieller Volcano-Ark-Key Key eines kompatiblen Gateways
Konto und Identitätsprüfung Volcano-Engine-Konto mit Verifizierung erforderlich Registrierung nach Gateway-Vorgaben
Base URL Adresse der offiziellen Datenebene Vom Gateway bereitgestellte Adresse
Berechtigungsumfang Abhängig von Konto, Modellaktivierung und Kontingent Abhängig von Modell- und Guthabenkonfiguration des Gateways
Abrechnung Offizielle Rechnung Gateway-Rechnung, Preise siehe Preisseite
Geeignete Szenarien Direkte Anbindung, eigene Cloud-Verwaltung Einheitlicher Zugang für mehrere Modelle, weniger Kontopflege
Zu beachten Verwaltungsebene benötigt AK/SK Videokanal und Callback-Unterstützung vorab prüfen

Das Auswahlkriterium ist nicht „welcher Weg billiger ist“, sondern ob das Team Kontopflege, Compliance-Prüfung und Fehlersuche tragen kann. Der Preis ist nur ein Faktor; Stabilität und Wechselbarkeit sind ebenso wichtig.

5. Den Key in Umgebungsvariablen ablegen

Ob offizieller Key oder Gateway-Key: Er sollte nie fest im Code stehen. Das folgende Beispiel zeigt eine minimale Anfrage über Umgebungsvariablen:

# .env nur lokal verwenden und in .gitignore aufnehmen
export ARK_API_KEY="your-volcengine-ark-key"
export SEEDANCE_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"

# Smoke-Test: nur Authentifizierung und Aufgabenerstellung prüfen
curl -sS -X POST "$SEEDANCE_BASE_URL/contents/generations/tasks" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-pro-250528",
    "content": [{"type": "text", "text": "Stadtstraße nach dem Regen, langsamer Kameraschwenk, filmische Optik"}],
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p"
  }'

Modell-ID und Parameter dienen nur der Veranschaulichung der Anfrageform; die tatsächlichen Werte stammen aus der Konsole oder der offiziellen Dokumentation. Python liest mit os.environ, Node.js mit process.env; in CI-Umgebungen werden Plattform-Secrets verwendet, in der Produktion ein Key-Management-Dienst. Vor der Protokollausgabe sollte Authorization maskiert werden, damit der Schlüssel nicht über Fehlermeldungen in das Log-System gelangt.

6. Reihenfolge der 401-Fehlersuche

Bei einem 401 nicht sofort wiederholen, sondern in dieser Reihenfolge prüfen:

  • Ist der Header exakt Authorization: Bearer <key>? Nach Bearer steht genau ein Leerzeichen.
  • Enthält der Key Zeilenumbrüche, Anführungszeichen oder führende beziehungsweise nachfolgende Leerzeichen? Das passiert beim Kopieren aus der Konsole besonders häufig.
  • Passt die Base URL zur Plattform des Keys? Ein offizieller Key mit Gateway-Adresse oder ein Gateway-Key mit offizieller Adresse scheitert immer an der Authentifizierung.
  • Wurde der Key deaktiviert, gelöscht oder ist er abgelaufen? Nach Teamwechseln ist häufig der alte Key ungültig, der Code aber noch nicht aktualisiert.
  • Ist das Konto im Rückstand oder der Dienst nicht aktiviert? Solche Fälle liefern teils 403 statt 401 und sollten gemeinsam betrachtet werden.
  • Stimmen Region und Endpoint? Adressen verschiedener Regionen dürfen nicht gemischt werden; bei grenzüberschreitenden Aufrufen kommt die Netzwerkstrecke hinzu.

Ein 401 besagt nur, dass die Identität nicht akzeptiert wurde; blindes Wiederholen löst das Problem nicht. Zuerst den maskierten Header, die Zieladresse und den Response-Body ausgeben, dann Punkt für Punkt abgleichen.

7. Checkliste für die Key-Sicherheit

  • Ein Key pro Umgebung: Entwicklung, Test und Produktion trennen, damit ein Leck begrenzt bleibt.
  • Minimale Rechte: nur die benötigten Modelle freischalten; für Verwaltungsaufgaben im Unternehmenskonto IAM-Unterbenutzer und AK/SK verwenden.
  • Nicht an das Frontend ausliefern: Der Key bleibt serverseitig; Webseite und App leiten Anfragen über das eigene Backend.
  • Nicht im Klartext speichern: verschlüsselte Ablage im Konfigurationsdienst, die Datenbank enthält keinen vollständigen Key.
  • Anomalien überwachen: Guthabenwarnungen einrichten und auf plötzliche Aufrufspitzen, fremde IP-Adressen und Fehlerraten achten.
  • Auditdaten behalten: festhalten, wer wann welchen Key erstellt und verwendet hat, mindestens für einen Rotationszyklus.

8. Rotation und Reaktion auf eine Offenlegung

Regelmäßige Rotation senkt das Risiko einer langfristigen Offenlegung. Empfohlene Reihenfolge:

  1. Einen neuen Key anlegen und mit Datum benennen, zum Beispiel seedance-prod-202610.
  2. Den neuen Key im Konfigurationsdienst hinterlegen und zunächst auf einer Instanz oder in einer Umgebung erproben.
  3. Die minimale Kette aus Einreichen, Abfragen und Herunterladen testen und Abrechnung sowie Kontingent prüfen.
  4. Nach der vollständigen Umstellung 24 bis 48 Stunden beobachten und bestätigen, dass die Aufrufe mit dem alten Key auf null gehen.
  5. Den alten Key deaktivieren und löschen sowie Protokolle und Rechnungen auf auffällige Aufrufe prüfen.

Bei Verdacht auf eine Offenlegung gilt die umgekehrte Reihenfolge: zuerst den betroffenen Key deaktivieren, dann Aufrufprotokolle und Rechnungen untersuchen, anschließend neu aufbauen und nachbereiten. Nur eine Zeichenkette im Code zu ändern, ohne den alten Key zu widerrufen, lässt das Risiko bestehen.

Häufige Fragen

Sind Seedance API Key und Volcano-Engine-Kontopasswort dasselbe?

Nein. Der Key dient nur der Schnittstellenauthentifizierung und kann nicht zur Konsolenanmeldung verwendet werden; das Kontopasswort gilt für Konsolenanmeldung und Kontoverwaltung. Beide sollten getrennt aufbewahrt und nicht am selben Ort notiert werden.

Der Key ist korrekt, trotzdem kommt 401 – warum?

Häufige Ursachen sind ein falsch formatierter Header, Leerzeichen oder Zeilenumbrüche beim Kopieren, eine nicht zur Key-Plattform passende Base URL, ein deaktivierter Key sowie ein anormaler Konto- oder Dienststatus. Zuerst mit curl eine minimale Anfrage senden, dann die Punkte einzeln ausschließen.

Kann ein Key gleichzeitig Text- und Videomodelle aufrufen?

Das hängt vom Aktivierungsstatus und der Rechtekonfiguration der Plattform ab. Selbst innerhalb eines Kontos müssen verschiedene Modelle separat freigeschaltet werden. Vor dem Aufruf die Verfügbarkeit in der Konsole prüfen; maßgeblich ist die tatsächliche Antwort.

Darf der Key im Frontend einer Webseite oder App liegen?

Davon ist abzuraten und es sollte unterbleiben. Frontend-Code lässt sich auslesen, der Key wäre unmittelbar offen. Richtig ist, dass das eigene Backend den Key hält und Anfragen weiterleitet, ergänzt um Anmeldeprüfung und Ratenbegrenzung.

Wie oft sollte ein Key rotiert werden?

Eine einheitliche Vorgabe gibt es nicht. Üblich sind 90 Tage; bei Personalwechsel, Verdacht auf Offenlegung oder Anbieterwechsel wird sofort rotiert. Vor der Rotation sicherstellen, dass alle Aufrufer des alten Keys migriert sind.

Nächster Schritt

Zuerst entscheiden, ob der offizielle Weg oder ein Gateway infrage kommt, dann einen dedizierten Key anlegen und mit einer kurzen Aufgabe einen Smoke-Test durchführen. Für einen einheitlichen Zugang kann man sich bei ZSQH AI Gateway registrieren und auf der Seite Modellpreise den Seedance-Kanal sowie die Abrechnungsart prüfen.

Weiterlesen: