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
| Änderung | Bestehender Volcengine-Client | TokenLab |
|---|---|---|
| Basis-URL | Ihr Volcengine-Endpunkt | https://api.tokenlab.sh/ |
| Authentifizierung | AK/SK-Anfragesignierung | Authorization: Bearer <TOKENLAB_API_KEY> |
| Task-Transport | Offizielle /api/v3/contents/generations/tasks REST-Pfade | Beibehalten |
| Material-/Validierungs-Actions | Action und Version Query-Parameter | Beibehalten |
| Task-Body | Volcengine-Stil content[] | Beibehalten |
| Material-Body | PascalCase-Felder wie GroupId und ProjectName | Beibehalten |
| Asynchrones Ergebnis | Volcengine-Task-Lebenszyklus | TokenLab 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 Client | TokenLab-Endpunkt |
|---|---|
| Volcengine REST-Task-Client | /api/v3/contents/generations/tasks und dessen Task-Pfade |
| Material- oder Validierungs-Action-Client | POST /?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 Pfad | Zweck |
|---|---|
POST /api/v3/contents/generations/tasks | Erstellen eines Video-Tasks |
GET /api/v3/contents/generations/tasks/{id} | Lesen eines einzelnen Tasks |
GET /api/v3/contents/generations/tasks | Auflisten 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:
- Task erstellen (Volc-kompatibel)
- Task abrufen (Volc-kompatibel)
- Tasks auflisten (Volc-kompatibel)
- Task abbrechen (Volc-kompatibel)
Regeln für den Request-Body
content[]akzeptierttext,image_url,video_url,audio_urlunddraft_task-Elemente.- Lassen Sie bei
image_urldas Feldroleweg oder verwenden Siefirst_framefür Image-to-Video. Verwenden Sielast_framezusammen mit einem ersten Frame oderreference_imagefür Reference-to-Video. - Ein öffentlicher Material-URI wie
asset://asset-YYYYMMDDHHMMSS-xxxxxkann 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_afterundsafety_identifier. Die Standardwerte hängen vom Modell ab:generate_audioistfalsefürseedance-2.0-Modelle undtruefürseedance-2.5, unddurationist5fürseedance-2.0-Modelle und-1fürseedance-2.5. Dieses REST-Format akzeptiert dieresolution-Werte480p,720pund1080p(480pund720pfürseedance-2.5), jedoch nicht4k, was nur die vereinheitlichte/v1/videos/generationsAPI akzeptiert.seedance-2.5lehntseed,framesundcamera_fixedab. callback_urlakzeptiert einen öffentlichen HTTP(S)-Endpunkt. TokenLab sendet denselben Query-Task-Body fürqueued,running,succeeded,failedundexpired; nursucceededundfailedfolgen 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:
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
- Ersetzen Sie den API-Host durch
https://api.tokenlab.sh. - Ersetzen Sie die AK/SK-Signierung durch einen TokenLab Bearer API-Key.
- 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.
- Behalten Sie denselben
ProjectNameüber zusammengehörige Material- und Verifizierungsanfragen hinweg bei. - Speichern Sie die TokenLab-Task-, Gruppen- und Asset-IDs, die von diesen Endpunkten zurückgegeben werden.
- Überprüfen Sie eine Erstellung, ein Polling, eine Auflistung und eine Fehlerantwort, bevor Sie den Produktionsverkehr umstellen.