Video & Materialien

Task erstellen (Volc-kompatibel)

Erstellen Sie eine Seedance-Aufgabe mit der Volc-kompatiblen API.

POST
/api/v3/contents/generations/tasks

Ü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" ohne role oder mit role: "first_frame" wird als erster Frame behandelt.
  • role: "last_frame" muss mit einem ersten Frame gepaart werden.
  • type: "video_url" erfordert role: "reference_video", und type: "audio_url" erfordert role: "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, 1 draft_task). Seedance 2.5 akzeptiert bis zu 51 (1 Text, 30 Bilder, 10 Videos, 10 Audios, 1 draft_task).
  • image_url.url akzeptiert eine öffentliche Bild-URL oder einen Material-URI wie asset://asset-YYYYMMDDHHMMSS-xxxxx. Die role bestimmt, 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_id und material_asset_ids, gibt 400 UnsupportedParameter zurück. Fügen Sie einen TokenLab-Material-URI in image_url.url ein.

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:

ParameterSeedance 2.0Seedance 2.5
duration4–15 / -1 (Standard: 5)4–30 / -1 (Standard: -1)
resolution480p, 720p, 1080p (Standard: 720p)480p, 720p (Standard: 720p)
generate_audioboolean (Standard: false)boolean (Standard: true)
priorityNicht unterstütztinteger: 0–9
seedinteger: -1–4294967295 (Standard: -1)Nicht unterstützt
execution_expires_after3600–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.

  • ratio akzeptiert 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 oder adaptive (Standard: adaptive).
  • watermark und return_last_frame sind Booleans (Standard: false). safety_identifier ist ein String mit bis zu 64 Zeichen.
  • service_tier akzeptiert nur default; flex gibt 400 UnsupportedParameter zurück.
  • tools akzeptiert maximal ein Element, {"type": "web_search"}.
  • draft: true, frames und camera_fixed werden nicht unterstützt. camera_fixed: false wird nur für Seedance 2.0 akzeptiert.
  • callback_url kann 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ügt Idempotency-Replayed: true hinzu.
  • Die Wiederverwendung des Schlüssels mit einem anderen Body gibt 409 mit dem Code idempotency_conflict zurück und erstellt niemals eine zweite Aufgabe.
  • Ein Schlüssel, der länger als 255 Zeichen ist oder Zeilenumbrüche enthält, gibt 400 InvalidParameter zurü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
AuthorizationBearer <token>

API-Key-Authentifizierung. Erstellen oder verwalten Sie API-Keys unter Dashboard > API > API Keys.

Ort: header

Header

X-TokenLab-Delivery-Policy?string

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"
Idempotency-Key?string

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.

Länge1 <= length <= 255

Anfragekörper

application/json

Antwort

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json