Video & Materialien
Task erstellen (Volc-kompatibel)
Erstellen Sie eine Seedance-Aufgabe mit der Volc-kompatiblen API.
Übersicht
Bestehende Seedance-Clients im Volc-Stil können TokenLab nutzen, indem sie die API-Adresse und den Schlüssel ändern.
Die Beispiele verwenden Seedance 2.0. Dieser Endpunkt unterstützt auch Seedance 2.5 mit den unten aufgeführten modellspezifischen Unterschieden. Die Beispiele für wiederverwendbare TokenLab-Material-URIs auf dieser Seite gelten für Seedance 2.0.
Siehe auch Seedance 2.0 Videomodelle und Videoerstellung.
Authentifizierung und Endpunkte
- Verwenden Sie
Authorization: Bearer <TOKENLAB_API_KEY>. - Volc AK/SK-Signierung wird nicht akzeptiert. Anfragen müssen einen TokenLab Bearer-Schlüssel enthalten.
- Verwenden Sie den offiziellen Aufgabenpfad:
POST /api/v3/contents/generations/tasks.
Inhaltsregeln
type: "text"ist der Prompt-Text.type: "image_url"ohneroleoder mitrole: "first_frame"wird als erster Frame behandelt.role: "last_frame"muss mit einem ersten Frame gepaart werden.type: "video_url"erfordertrole: "reference_video", undtype: "audio_url"erfordertrole: "reference_audio".role: "reference_image"markiert ein Referenzbild.- Elementbegrenzungen: Seedance 2.0 akzeptiert bis zu 16
content-Elemente (1 Text, 9 Bilder, 3 Videos, 3 Audios, 1draft_task). Seedance 2.5 akzeptiert bis zu 51 (1 Text, 30 Bilder, 10 Videos, 10 Audios, 1draft_task). image_url.urlakzeptiert eine öffentliche Bild-URL oder einen Material-URI wieasset://asset-YYYYMMDDHHMMSS-xxxxx. Dierolebestimmt, ob dieses Material ein erster Frame, ein letzter Frame oder ein Referenzbild ist.- Mischen Sie keine Eingaben für den ersten/letzten Frame mit Referenzmedien in einer einzigen Anfrage.
- Der REST-Body akzeptiert nur die auf dieser Seite aufgeführten Felder. Jedes andere Feld auf oberster Ebene, einschließlich
material_asset_idundmaterial_asset_ids, gibt400 UnsupportedParameterzurück. Fügen Sie einen TokenLab-Material-URI inimage_url.urlein.
Parameterhinweise
model akzeptiert eine TokenLab-Modell-ID wie seedance-2.0 oder seedance-2.5. Bestehende Clients können weiterhin die Volcengine-Modell-ID senden, die sie bereits für diese Modelle verwenden. Die Antwort von get-task gibt den von Ihnen gesendeten model-Wert zurück. Ein nicht erkannter Wert führt zu 400 InvalidParameter.
duration ist eine Ganzzahl in Sekunden; -1 wählt die automatische Dauer. Standards und Grenzwerte unterscheiden sich je nach Modell:
| Parameter | Seedance 2.0 | Seedance 2.5 |
|---|---|---|
duration | 4–15 / -1 (Standard: 5) | 4–30 / -1 (Standard: -1) |
resolution | 480p, 720p, 1080p (Standard: 720p) | 480p, 720p (Standard: 720p) |
generate_audio | boolean (Standard: false) | boolean (Standard: true) |
priority | Nicht unterstützt | integer: 0–9 |
seed | integer: -1–4294967295 (Standard: -1) | Nicht unterstützt |
execution_expires_after | 3600–259200 Sekunden (Standard: 172800) | 3600–259200 Sekunden (Standard: 172800) |
Für Seedance 2.5 erfordern Anfragen für den ersten Frame, erste/letzte Frames, Videoerweiterungen und Video-zu-Video ratio: "adaptive"; Video-zu-Video erfordert zudem duration: -1. output_format akzeptiert nur mp4 oder mov für Seedance 2.5.
ratioakzeptiert16:9,4:3,1:1,3:4,9:16,21:9oderadaptive(Standard:adaptive).watermarkundreturn_last_framesind Booleans (Standard:false).safety_identifierist ein String mit bis zu 64 Zeichen.service_tierakzeptiert nurdefault;flexgibt400 UnsupportedParameterzurück.toolsakzeptiert maximal ein Element,{"type": "web_search"}.draft: true,framesundcamera_fixedwerden nicht unterstützt.camera_fixed: falsewird nur für Seedance 2.0 akzeptiert.callback_urlkann auf einen öffentlichen HTTP(S)-Endpunkt mit bis zu 2.048 Zeichen verweisen.
Callback-Zustellung
Wenn callback_url vorhanden ist, sendet TokenLab einen HTTP POST, wenn sich der Aufgabenstatus ändert. Callback-Status sind queued, running, succeeded, failed und expired. Der JSON-Body entspricht der Antwort von get-task.
Eine 2xx-Antwort bestätigt die Zustellung. Bei succeeded und failed wird eine Zustellung, die nicht innerhalb von fünf Sekunden erfolgreich ist, bis zu dreimal wiederholt. Der Callback enthält nur den Standard-JSON-Content-Header und keine TokenLab-spezifischen Zustellungs-Header. Weiterleitungen werden nicht gefolgt, und private oder reservierte Netzwerkziele werden abgelehnt.
Speichern Sie die Aufgaben-ID. Wenn ein Callback nicht zugestellt wird, können Sie das Ergebnis dennoch mit dem get-task-Endpunkt abrufen.
Bildvorbereitung
Öffentliche HTTP(S)-Bild-URLs und unterstützte Daten-URLs werden wie bereitgestellt verwendet; sie werden nicht automatisch als wiederverwendbare Materialien gespeichert. Explizite asset://asset-...-Referenzen verwenden bestehende TokenLab-Materialien. TokenLab prüft vor der Generierung Eigentum und Verfügbarkeit. Wenn ein referenziertes Material noch vorbereitet wird, warten Sie, bis es bereit ist, und versuchen Sie es erneut; untersuchen Sie error.code und error.message, wenn die Erstellung fehlschlägt.
Verwenden Sie für bestehende Materialien die öffentliche asset-YYYYMMDDHHMMSS-xxxxx-ID anstelle einer ursprünglichen Asset-ID, die von einem anderen System zurückgegeben wurde. TokenLab überprüft das Materialeigentum vor der Generierung.
Erstellungsantwort
{
"id": "cgt-20260102030405-a1b2c"
}Die Erstellungsantwort enthält nur die Aufgaben-ID. Speichern Sie diese, damit Sie jederzeit Status und Ergebnisse abrufen können.
Doppelte Aufgaben verhindern
Senden Sie einen eindeutigen Idempotency-Key (1–255 Zeichen, keine Zeilenumbrüche) mit Erstellungsanfragen. Wenn die Verbindung vor Eintreffen der Antwort getrennt wird, versuchen Sie es erneut mit demselben API-Schlüssel, Idempotency-Key und Request-Body:
- Wenn die ursprüngliche Aufgabe erstellt wurde, gibt TokenLab dieselbe
cgt-...-ID zurück und fügtIdempotency-Replayed: truehinzu. - Die Wiederverwendung des Schlüssels mit einem anderen Body gibt
409mit dem Codeidempotency_conflictzurück und erstellt niemals eine zweite Aufgabe. - Ein Schlüssel, der länger als 255 Zeichen ist oder Zeilenumbrüche enthält, gibt
400 InvalidParameterzurück.
Der Schlüssel ändert nicht die Form der JSON-Antwort. TokenLab leitet Duplikate nicht aus X-Request-ID oder identischen Request-Bodys ohne Schlüssel ab.
Beispiel
REST-Erstellung
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.0",
"content": [
{"type": "text", "text": "A cinematic forest at sunset"},
{"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/ref.png"}}
],
"ratio": "16:9",
"duration": 5,
"resolution": "720p",
"generate_audio": false,
"callback_url": "https://example.com/webhooks/seedance"
}'Für bestehende Materialien fügen Sie jeden URI in das offizielle content[]-Element ein und deklarieren dessen Rolle:
[
{
"type": "image_url",
"role": "first_frame",
"image_url": {"url": "asset://asset-20260720123458-start"}
},
{
"type": "image_url",
"role": "last_frame",
"image_url": {"url": "asset://asset-20260720123459-end01"}
}
]Fehler
REST-Fehler verwenden {"error": {"code", "message", "param", "type"}}. Anfrageprobleme geben 400 mit InvalidParameter oder UnsupportedParameter zurück, und ein fehlender Bearer-Schlüssel gibt 401 AuthenticationError zurück. Fehler bei der Videogenerierung, wie unzureichendes Guthaben (402) oder ein Rate-Limit (429), behalten ihren HTTP-Status bei.
Dieselben Operationen sind auch als Actions CreateContentsGenerationsTasks, GetContentsGenerationsTask, ListContentsGenerationsTasks und DeleteContentsGenerationsTasks unter POST /api/v3?Version=2024-01-01 verfügbar. Neue Integrationen sollten die oben genannten REST-Pfade verwenden.
Nächster Schritt
Verwenden Sie die zurückgegebene cgt-...-ID mit Aufgabe abrufen (Volc-kompatibel), bis die Aufgabe einen Endstatus erreicht.
curl -X POST "https://example.com/api/v3/contents/generations/tasks" \ -H "Content-Type: application/json" \ -d '{ "model": "seedance-2.0", "content": [ { "type": "text", "text": "A cinematic forest at sunset" }, { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://example.com/ref.png" } } ], "ratio": "16:9", "duration": 5, "resolution": "720p", "generate_audio": false }'{ "id": "string"}Autorisierung
BearerAuth API-Key-Authentifizierung. Erstellen oder verwalten Sie API-Keys unter Dashboard > API > API Keys.
Ort: header
Header
Zustellungsrichtlinie pro Anfrage. Überschreibt die API-Key- und Workspace-Standardeinstellungen. Versucht automatisch zuerst TokenLab Verified und kann vor der Ausgabe, der Annahme der Anfrage oder der Erstellung persistenter Ressourcen einmalig auf Official umstellen.
Zulässige Werte
- "auto"
- "verified"
- "official"
Vom Client generierter Schlüssel für die idempotente REST-Aufgabenerstellung, 1-255 Zeichen ohne Zeilenumbrüche. Unter demselben TokenLab API-Berechtigungsnachweis gibt die Wiederverwendung desselben Schlüssels mit demselben JSON-Body die ursprüngliche cgt-Aufgaben-ID zurück; die Wiederverwendung mit einem anderen Body gibt 409 mit dem Code idempotency_conflict zurück. Ein Schlüssel, der zu lang ist oder Zeilenumbrüche enthält, gibt 400 zurück. Behalten Sie den Berechtigungsnachweis, den Schlüssel und den Request-Body bei, wenn Sie nach einem Timeout oder Verbindungsabbruch einen erneuten Versuch unternehmen.
1 <= length <= 255Anfragekörper
application/json
Antwort
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json