Medienleitfäden

Migration von Seedance von Volcengine

Behalten Sie Ihr Volcengine-Anfrageformat bei und stellen Sie Seedance auf TokenLab um

Wenn Ihre Anwendung bereits die Volcengine Seedance API verwendet, können Sie deren REST-Pfade, den content[]-Body, die Antwortfelder, Callbacks und die PascalCase-Material-Actions beibehalten. Ändern Sie den API-Host und ersetzen Sie die AK/SK-Signierung durch einen TokenLab API-Key.

Was sich ändert

ÄnderungBestehender Volcengine-ClientTokenLab
Basis-URLIhr Volcengine-Endpunkthttps://api.tokenlab.sh/
AuthentifizierungAK/SK-AnfragesignierungAuthorization: Bearer <TOKENLAB_API_KEY>
Task-TransportOffizielle /api/v3/contents/generations/tasks REST-PfadeBeibehalten
Material-/Validierungs-ActionsAction und Version Query-ParameterBeibehalten
Task-BodyVolcengine-Stil content[]Beibehalten
Material-BodyPascalCase-Felder wie GroupId und ProjectNameBeibehalten
Asynchrones ErgebnisVolcengine-Task-LebenszyklusTokenLab cgt-... Task-ID mit Polling und optionalem Callback

Anfragen, die nur mit AK/SK signiert sind, geben 401 AuthenticationError zurück. Jede TokenLab-Anfrage muss Authorization: Bearer <TOKENLAB_API_KEY> enthalten.

Wählen Sie einen Endpunkt

Bestehender ClientTokenLab-Endpunkt
Volcengine REST-Task-Client/api/v3/contents/generations/tasks und dessen Task-Pfade
Material- oder Validierungs-Action-ClientPOST /?Action=...&Version=2024-01-01 oder POST /api/v3?Action=...&Version=2024-01-01

Für Video-Tasks behalten Sie die bestehende REST-Methode, den Pfad und den JSON-Body bei. Material- und Verifizierungsanfragen verwenden weiterhin Action- und Version-Query-Parameter. Der Action-Endpunkt akzeptiert auch die Task-Actions CreateContentsGenerationsTasks, GetContentsGenerationsTask, ListContentsGenerationsTasks und DeleteContentsGenerationsTasks; verwenden Sie für neue Arbeiten die REST-Pfade.

Offizielle Task-Pfade

Methode und PfadZweck
POST /api/v3/contents/generations/tasksErstellen eines Video-Tasks
GET /api/v3/contents/generations/tasks/{id}Lesen eines einzelnen Tasks
GET /api/v3/contents/generations/tasksAuflisten von Tasks
DELETE /api/v3/contents/generations/tasks/{id}Abbrechen eines Tasks, der sich noch in der Warteschlange befindet. Ein Task, der bereits gestartet wurde, gibt 409 task_not_cancellable zurück

REST-Clients können diese äquivalenten Referenzen verwenden:

Regeln für den Request-Body

  • content[] akzeptiert text, image_url, video_url, audio_url und draft_task-Elemente.
  • Lassen Sie bei image_url das Feld role weg oder verwenden Sie first_frame für Image-to-Video. Verwenden Sie last_frame zusammen mit einem ersten Frame oder reference_image für Reference-to-Video.
  • Ein öffentlicher Material-URI wie asset://asset-YYYYMMDDHHMMSS-xxxxx kann verwendet werden, sofern der gewählte Seedance-Workflow diese Medienrolle akzeptiert.
  • Der REST-Body akzeptiert nur offizielle Felder, einschließlich model, content, ratio, duration, resolution, generate_audio, watermark, return_last_frame, seed, execution_expires_after und safety_identifier. Die Standardwerte hängen vom Modell ab: generate_audio ist false für seedance-2.0-Modelle und true für seedance-2.5, und duration ist 5 für seedance-2.0-Modelle und -1 für seedance-2.5. Dieses REST-Format akzeptiert die resolution-Werte 480p, 720p und 1080p (480p und 720p für seedance-2.5), jedoch nicht 4k, was nur die vereinheitlichte /v1/videos/generations API akzeptiert. seedance-2.5 lehnt seed, frames und camera_fixed ab.
  • callback_url akzeptiert einen öffentlichen HTTP(S)-Endpunkt. TokenLab sendet denselben Query-Task-Body für queued, running, succeeded, failed und expired; nur succeeded und failed folgen dem offiziellen Verhalten: ein Timeout von fünf Sekunden und ein erneuter Versuch, wenn Ihr Endpunkt die Benachrichtigung nicht bestätigt.

Minimales REST-Beispiel

curl 'https://api.tokenlab.sh/api/v3/contents/generations/tasks' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Idempotency-Key: $CLIENT_JOB_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "content": [
      {"type":"text","text":"A cinematic product reveal"},
      {"type":"image_url","role":"reference_image","image_url":{"url":"https://example.com/reference.png"}}
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }'

Speichern Sie die zurückgegebene cgt-...-ID. Pollen Sie, bis der status auf succeeded, failed, cancelled oder expired wechselt; behandeln Sie die Erstellungsantwort nicht als abgeschlossenes Video. Wenn Sie eine callback_url angeben, erlauben Sie wiederholte succeeded- oder failed-Benachrichtigungen und behalten Sie das Polling als Wiederherstellungspfad bei.

Halten Sie v1- und v3-Typen getrennt

Verwenden Sie keine /v1/tasks/{id}-Antwortstruktur für diesen Endpunkt wieder. Die vereinheitlichte v1-API meldet pending, processing, completed und failed; die Volc-kompatible v3-API meldet queued, running, succeeded, failed, cancelled und expired. Die offizielle v3-Antwort stellt duration zudem als JSON-String dar und lässt error bei nicht fehlgeschlagenen Tasks weg.

Für eine sichere Wiederherstellung nach einem Erstellungs-Timeout oder Verbindungsabbruch fügen Sie der REST-Erstellungsanfrage einen eindeutigen Idempotency-Key hinzu. Ein erneuter Versuch mit demselben Body und demselben Key gibt die ursprüngliche cgt-...-ID zurück; derselbe Key mit einem anderen Body gibt 409 zurück.

Materialien und Identitätsprüfung (Real-Person Verification)

Derselbe Action-Endpunkt unterstützt auch die 10 Material- und Materialgruppen-Operationen. Siehe Material Actions (Volc-kompatibel) für deren exakte PascalCase-Bodies, Filter, Paging, Antwort-Envelope und 12-Stunden-Material-URLs.

Materialien für die Identitätsprüfung fügen vor dem Upload zwei Actions hinzu:

  1. Visual Validation Session erstellen
  2. Visual Validation Ergebnis abrufen

Die zweite Action gibt die verifizierte GroupId zurück. Verwenden Sie diese ID mit CreateAsset; ein Client kann keine LivenessFace-Gruppe direkt erstellen.

Migrations-Checkliste

  1. Ersetzen Sie den API-Host durch https://api.tokenlab.sh.
  2. Ersetzen Sie die AK/SK-Signierung durch einen TokenLab Bearer API-Key.
  3. Behalten Sie die offizielle REST-Task-Methode, den Pfad und die Request-Body-Schreibweise bei; verwenden Sie Action und Version nur für Material- oder Validierungsoperationen.
  4. Behalten Sie denselben ProjectName über zusammengehörige Material- und Verifizierungsanfragen hinweg bei.
  5. Speichern Sie die TokenLab-Task-, Gruppen- und Asset-IDs, die von diesen Endpunkten zurückgegeben werden.
  6. Überprüfen Sie eine Erstellung, ein Polling, eine Auflistung und eine Fehlerantwort, bevor Sie den Produktionsverkehr umstellen.

Auf dieser Seite