Task erstellen (Volc-kompatibel)

ÜbersichtCopy Anchor Link

Bestehende Volc-kompatible Seedance-Clients können TokenLab nutzen, indem sie die API-Adresse und den Key ändern.

Siehe auch Seedance 2.0 Videomodelle und Videogenerierung.

Authentifizierung und EndpunkteCopy Anchor Link

• Verwenden Sie Authorization: Bearer <TOKENLAB_API_KEY>.
• Volc AK/SK-Signierung wird nicht akzeptiert. Anfragen müssen einen TokenLab Bearer-Key enthalten.
• Verwenden Sie den offiziellen Aufgabenpfad: POST /api/v3/contents/generations/tasks.

InhaltsregelnCopy Anchor Link

• type: "text" ist der Prompt-Text.
• type: "image_url" ohne role oder mit role: "first_frame" wird als erstes Frame behandelt.
• role: "last_frame" muss mit einem ersten Frame kombiniert werden.
• role: "reference_image", reference_video und reference_audio werden als Referenzen verwendet.
• image_url.url akzeptiert eine öffentliche Bild-URL oder einen Material-URI wie asset://asset-YYYYMMDDHHMMSS-xxxxx. Die role bestimmt, ob dieses Material ein erstes Frame, ein letztes Frame oder ein Referenzbild ist.
• Mischen Sie keine Eingaben für erste/letzte Frames mit Referenzmedien in einer Anfrage.
• Die Felder material_asset_id und material_asset_ids auf oberster Ebene werden abgelehnt. Geben Sie eine TokenLab-Material-URI in image_url.url an. priority wird nur für Seedance 2.5 unterstützt.

ParameterhinweiseCopy Anchor Link

duration ist eine ganze Anzahl von Sekunden; -1 wählt die automatische Dauer. Standardwerte und Grenzen hängen vom Modell ab:

Bei Seedance 2.5 erfordern Anfragen mit Anfangsbild, Anfangs- und Endbild, Videoverlängerung sowie Video-zu-Video ratio: "adaptive". Video-zu-Video erfordert außerdem duration: -1. output_format akzeptiert mp4 oder mov nur für Seedance 2.5.

• ratio akzeptiert 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 oder adaptive.
• watermark, return_last_frame, seed, execution_expires_after und safety_identifier werden akzeptiert, sofern sie für das ausgewählte Modell gültig sind.
• callback_url kann auf einen öffentlichen HTTP(S)-Endpunkt verweisen.

Callback-ZustellungCopy Anchor Link

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 weiterhin über den get-task-Endpunkt abrufen.

BildvorbereitungCopy Anchor Link

Öffentliche HTTP(S)-Bild-URLs und unterstützte data-URLs werden wie angegeben verwendet und nicht automatisch als wiederverwendbare Materialien gespeichert. Explizite asset://asset-...-Referenzen verwenden vorhandene TokenLab-Materialien. Vor der Generierung werden Besitz und Bereitschaft geprüft. Warten Sie bei noch nicht bereiten Materialien und versuchen Sie es danach erneut. Bei Fehlern prüfen Sie error.code und error.message.

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 die Materialbesitzrechte vor der Generierung.

Antwort bei ErstellungCopy Anchor Link

{
  "id": "cgt-20260102030405-a1b2c"
}

Die Antwort bei der Erstellung enthält nur die Aufgaben-ID. Speichern Sie diese, damit Sie jederzeit Status und Ergebnisse abrufen können.

Vermeidung doppelter AufgabenCopy Anchor Link

Senden Sie einen eindeutigen Idempotency-Key mit Erstellungsanfragen. Wenn die Verbindung vor Eintreffen der Antwort geschlossen wird, wiederholen Sie den Vorgang mit demselben API-Key, 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.
• Wird die ursprüngliche Anfrage noch registriert, gibt TokenLab 409 IdempotencyRequestInProgress zurück. Versuchen Sie es später mit demselben Key und Body erneut.
• Die Wiederverwendung des Keys mit einem anderen Body führt zu 409 IdempotencyConflict und erstellt niemals eine zweite Aufgabe.

Idempotency gilt für den offiziellen v3 REST-Erstellungspfad. Es ändert nicht die Form der JSON-Antwort und wird nicht aus X-Request-ID oder identischen Request-Bodies ohne Key abgeleitet.

BeispielCopy Anchor Link

REST-ErstellungCopy Anchor Link

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": "doubao-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"}
  }
]

Nächster SchrittCopy Anchor Link

Verwenden Sie die zurückgegebene cgt-... ID mit Task 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": "doubao-seedance-2-0-260128",    "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"}