Seedance 2.0 API-Guide: Schritt-für-Schritt-Anleitung zur Videogenerierung

1. Python-Umgebung und SDK einrichten

Um in Python mit der BytePlus Ark API zu verbinden, nutzen wir das offizielle Paket byteplus-python-sdk-v2. 

Am einfachsten richtest du die Abhängigkeiten ein, indem du eine Anaconda-Umgebung erstellst und die requirements.txt-Datei installierst, so:

git clone git@github.com:fran-aubry/seedance2-tutorial.git
conda create --name seedance2 python=3.11
conda activate seedance2
pip install -r requirements.txt

2. BytePlus Ark Python-Client initialisieren

Erstelle ein neues Skript namens text_to_video.py im selben Ordner wie die zuvor angelegte .env-Datei.

Zuerst importieren wir die benötigten Pakete:

import os
from byteplussdkarkruntime import Ark
from dotenv import load_dotenv

Als Nächstes laden wir den API-Schlüssel aus der .env-Datei mit der Funktion load_dotenv():

load_dotenv()
API_KEY = os.getenv("ARK_API_KEY")

Jetzt initialisieren wir den Ark-Client, über den wir Anfragen an die BytePlus Ark API stellen. 

Wir verwenden die os-Bibliothek, um den API-Schlüssel aus den Umgebungsvariablen zu lesen, und setzen die passende Basis-URL für den internationalen API-Zugriff:

client = Ark(
    api_key=os.getenv("ARK_API_KEY"),
    base_url="https://ark.ap-southeast.bytepluses.com/api/v3"
)

Zum Schluss definieren wir einen Prompt und nutzen die Funktion content_generation.tasks.create() des Clients, um das Video zu generieren:

prompt = """
A cinematic close-up of a weary but hopeful female astronaut inside a dimly lit, dusty spaceship cabin. 
Soft blue light illuminates her face. 
She takes a deep breath, showing subtle emotional relief, looks directly into the camera, and says: 
'We finally made it. The atmosphere is stable.' 
The ambient sound of a low, rhythmic spaceship engine hums in the background.
"""
response = client.content_generation.tasks.create(
    model="dreamina-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": prompt,
        }
    ],
    generate_audio=True,
    ratio="16:9",
    duration=8,
    watermark=True,
    resolution="480p",
)
task_id = response.id
print(f"Task successfully submitted! Task ID: {task_id}")

Nach dem Absenden der Anfrage erhalten wir nicht sofort ein Video, da die Generierung etwas Zeit benötigt. 

Das bedeutet, die Variable response enthält nicht das Video selbst. 

Stattdessen ist es ein Objekt mit Informationen zur Videogenerierungsaufgabe. 

Insbesondere enthält es die Task-ID, mit der wir den Fortschritt verfolgen und das Video herunterladen können, sobald die Generierung abgeschlossen ist.

3. Generierungsstatus verfolgen (Task Polling)

Den Status einer Aufgabe rufen wir ab, indem wir die Task-ID an die Funktion content_generation.tasks.get() übergeben, so:

task = client.content_generation.tasks.get(task_id=task_id)
status = task.status
print(f"Status: {status}")

Um das Tracking zu vereinfachen, erstellen wir ein neues Skript utils.py im selben Ordner und fügen diese Funktion hinzu, die anhand des Client-Objekts und der Task-ID den Fortschritt verfolgt:

import time
import requests

def poll_task(client, task_id, poll_interval=5):
    while True:
        try:
            task_status = client.content_generation.tasks.get(task_id=task_id)
            status = getattr(task_status, "status", None) or (task_status.get("status") if isinstance(task_status, dict) else None)
            
            if status == "succeeded":
                print("\nTask completed successfully.")
                return task_status.content.video_url
                
            elif status == "failed":
                error_details = getattr(task_status, "error", "Unknown error occurred during processing.")
                raise RuntimeError(f"Task failed: {error_details}")
                
            print(".", end="", flush=True)
            time.sleep(poll_interval)
        except Exception as e:
            if isinstance(e, RuntimeError):
                raise
            print(f"\nWarning: Error polling task (will retry): {e}")
            time.sleep(poll_interval)

4. Generiertes Video mit Python requests herunterladen

Die oben implementierte Funktion poll_task() gibt die Video-

Da wir nun den Generierungsprozess verfolgen können, brauchen wir nur noch einen Weg, das Video nach Abschluss herunterzuladen. 

Da die BytePlus Ark API in der Task-Antwort eine direkte URL zur Videodatei liefert, können wir sie mit der requests-Bibliothek herunterladen.

Hier ist eine Funktion dafür:

def download_video(url, output_path = "video.mp4"):
    try:
        print(f"Downloading video from {url} to {output_path}...")
        response = requests.get(url, stream=True)
        response.raise_for_status()
        
        with open(output_path, 'wb') as f:
            for chunk in response.iter_content(chunk_size=8192):
                f.write(chunk)
        print(f"Video successfully downloaded to '{output_path}'")
        return True
    except Exception as e:
        print(f"Error downloading video: {e}")
        return False

Komplettes Python-Skript: Text-zu-Video mit Seedance 2

Alles zusammengeführt ergibt sich dieses vollständige Skript, um aus einem Textprompt mit Seedance 2 ein Video zu erzeugen:

import os
from byteplussdkarkruntime import Ark
from dotenv import load_dotenv
import utils

load_dotenv()
API_KEY = os.getenv("ARK_API_KEY")

client = Ark(
    api_key=os.getenv("ARK_API_KEY"),
    base_url="https://ark.ap-southeast.bytepluses.com/api/v3"
)

prompt = """
A cinematic close-up of a weary but hopeful female astronaut inside a dimly lit, dusty spaceship cabin. 
Soft blue light illuminates her face. 
She takes a deep breath, showing subtle emotional relief, looks directly into the camera, and says: 
'We finally made it. The atmosphere is stable.' 
The ambient sound of a low, rhythmic spaceship engine hums in the background.
"""

response = client.content_generation.tasks.create(
    model="dreamina-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": prompt,
        }
    ],
    generate_audio=True,
    ratio="16:9",
    duration=8,
    watermark=True,
    resolution="480p",
)

task_id = response.id
print(f"Task successfully submitted! Task ID: {task_id}")

# Wait for the video to finish generating
video_url = utils.poll_task(client, task_id)

utils.download_video(video_url, "./videos/space.mp4")

Seedance 2 API: Referenz der Kernparameter

Hier findest du die zulässigen Werte für die wichtigsten Parameter einer Videogenerierungsanfrage:

Advanced Guide: Seedance 2.0 Bild-zu-Video-Funktionen

Im vorherigen Abschnitt haben wir gelernt, wie man mit einem Textprompt ein Video generiert. Seedance 2 unterstützt außerdem Bild-, Video- und Audioeingaben. Starten wir mit Bildern.

Referenzbilder für konsistente Charaktere nutzen

Zum Testen der Bildeingaben habe ich zwei Charaktere mit KI erzeugt, die ich in einer Sitcom-ähnlichen Szene verwenden wollte.

Wir können dem Modell Bildreferenzen bereitstellen, indem wir sie in das content-Feld der Anfrage aufnehmen, zum Beispiel so:

response = client.content_generation.tasks.create(
    model="dreamina-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": prompt,
        },
        {
            "type": "image_url",
            "image_url": {
                "url": utils.load_image("./images/male-character.png")
            },
            "role": "reference_image"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": utils.load_image("./images/female-character.png")
            },
            "role": "reference_image"
        }
    ],
    generate_audio=True,
    ratio="16:9",
    duration=15,
    watermark=True,
    resolution="480p",
)

Für dieses Video habe ich den folgenden Prompt verwendet:

Context: A cozy, warmly lit independent coffee shop counter with wooden accents.
Reference: 
- The male barista's face and clothing follow @Image1.
- The female customer's face and styling follow @Image2.

Action & Dialogue (10 Seconds Total):

0:00 - 0:04: 
Medium close-up on the male barista (@Image1) standing behind the counter,
next to the coffee machine. He leans across the counter with a smooth, 
flirtatious smirk, acting like he is making a highly exclusive offer: 
"The WiFi password? It's actually my phone number: five-five-five, zero-one—"

0:04 - 0:07: 
Camera cuts to the female customer (@Image2), instantly interrupting him. 
She holds up her phone screen toward him, entirely unimpressed: 
"Your network is called 'Free_Guest_WiFi' and there is literally no password."

0:07 - 0:08: Quick cut back to the two-shot. 
Flustered, the barista becomes visibly embarrassed, his confident smirk 
instantly vanishing as he nervously breaks eye contact.

0:08 - 0:10: Camera cuts back to a medium shot of the female customer (@Image2). 
She lowers her phone, tapping her fingers lightly on the counter, 
and delivers her order with perfect deadpan clarity: 
"It will be an espresso please. No milk, no sugar, and no phone number."

Framing/Timing: 
Clean cuts to perfectly pace the comedic timing over exactly 10 seconds.

Tone/Audio: 
Lighthearted sitcom vibe. Synchronized voice generation for the dialogue, a subtle low cafe background hum, and the sound of the customer's fingers lightly tapping the wooden counter at the end.

Beachte, dass der Prompt @Image1 und @Image2 verwendet, um auf die Bilder in der Reihenfolge zu verweisen, in der sie in der Liste übergeben wurden.

Leider erhielt ich beim Generieren dieses Videos einen Fehler: 

The request failed because the input image may contain a real person.

Das trat wiederholt auf, sobald ich in Seedance 2 ein Referenzbild mit einer realistisch wirkenden Person verwendete – auch bei KI-generierten Gesichtern. 

Um das zu umgehen, habe ich die Figuren in Cartoon-Varianten umgewandelt und es erneut versucht.

Diesmal hat es einwandfrei funktioniert, und das Ergebnis entsprach genau meiner Zielvorstellung.

Den vollständigen Code für dieses Beispiel findest du in der Datei image_to_video.py.

Erste und letzte Frames für geführte Animation festlegen

Im vorherigen Beispiel haben wir Bilder als Referenzen genutzt, indem wir im Request ”role”: “reference_image” gesetzt haben.

Seedance 2 unterstützt zwei weitere Bildrollen:

• ”first_frame”: Das Modell verwendet das angegebene Bild als exakten Startframe des generierten Videos. Das ist die Standardoption für direkte Bild-zu-Video-Generierung.
• ”last_frame”: Weist das Modell an, das Video mit diesem Bild zu beenden. Hinweis: Das geht nur, wenn im selben Request auch ein first_frame übergeben wird. Das Modell interpoliert dann zwischen beiden Bildern.

Ich habe das getestet, indem ich eine Reihe von Startframes generiert habe, die ein Roboter-KI-Labor zeigen, das in einer Welt ohne natürliche Flora versucht, Pflanzen nachzubilden. 

Für jeden Frame habe ich ein Video erzeugt, das mit diesem Frame startet. So strukturierst du den jeweiligen Request:

response = client.content_generation.tasks.create(
    model="dreamina-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": prompt,
        },
        {
            "type": "image_url",
            "image_url": {
                "url": utils.load_image("./images/robot-lab1.jpeg")
            },
            "role": "first_frame"
        }
    ],
    generate_audio=False,
    ratio="16:9",
    duration=4,
    watermark=True,
    resolution="480p",
)

Ich habe die Videos ohne Ton generiert, weil die Audiospur sonst nicht konsistent wäre, da jedes Video separat erstellt wurde. Hier ist das Ergebnis, wenn man die fünf Clips zusammenfügt:

Das vollständige Skript, um ein Video basierend auf einem Startframe zu erzeugen, findest du hier.

Bildinterpolation mit last_frame

In diesem Beispiel übergeben wir sowohl einen first_frame als auch einen last_frame, um ein Video zwischen beiden zu erzeugen.

Ich habe zwei Bilder desselben Zimmers generiert: eines leer ohne Möbel und eines komplett eingerichtet. Ziel ist ein Video, in dem das Zimmer eingerichtet wird.

Der verwendete Prompt beschreibt, wie die Möbel im Video erscheinen sollen:

A dynamic, fast-paced sequence where furniture pops into existence piece by piece. First, a rug rapidly unfolds itself, then the sofa drops from just above the floor with a heavy, realistic bounce. Lamps, artwork, and plants quickly spring into reality one after another. Vibrant lighting, photorealistic materials, lively and snappy energetic rhythm.

So sieht die Anfrage aus:

response = client.content_generation.tasks.create(
    model="dreamina-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": prompt,
        },
        {
            "type": "image_url",
            "image_url": {
                "url": utils.load_image("./images/room-start.png")
            },
            "role": "first_frame"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": utils.load_image("./images/room-end.png")
            },
            "role": "last_frame"
        }
    ],
    generate_audio=True,
    ratio="16:9",
    duration=8,
    watermark=True,
    resolution="480p",
)

Und so sieht das Ergebnis aus:

Das vollständige Skript findest du hier.

Seedance 2.0 Multimodale Inputs: Audio- und Videoreferenzen hinzufügen

Als multimodales Modell geht Seedance 2 über Text- und Bildeingaben hinaus. Es unterstützt auch Video- und Audioeingaben. Diese können als stilistische Referenzen, zur Bewegungsübernahme oder für Video-Editing genutzt werden.

Dieses Beispiel von der offiziellen Website veranschaulicht das sehr gut. Sie haben eine Kampfszene mit zwei Schauspielern genommen und damit die Action gesteuert, während die Schauspieler durch Referenzbilder ersetzt wurden:

Ein Video als Input übergeben

Wie bei Bildern werden Videoeingaben im Parameter content der Anfrage übergeben. 

Zum Zeitpunkt der Erstellung dieses Artikels unterstützen Videoinputs jedoch nur URLs. Wenn wir also ein lokales Video verwenden möchten, müssen wir es zunächst hosten.

Für dieses Beispiel habe ich dieses frei nutzbare Skate-Video von Marc Espejo verwendet. Die Idee war, mit Seedance 2 einige VFX hinzuzufügen. Hier ist das Ergebnis:

Um dies zu erzeugen, habe ich folgende Anfrage verwendet:

response = client.content_generation.tasks.create(
    model="dreamina-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": prompt,
        },
        {
            "type": "video_url", 
            "video_url": {
                "url": "https://www.pexels.com/download/video/38213009/"
            },
            "role": "reference_video" 
        }
    ],
    generate_audio=True,
    ratio="16:9",
    duration=6,
    watermark=True,
    resolution="480p",
)

Das vollständige Skript findest du hier. Den Prompt, den ich verwendet habe, siehst du hier:

The original skater, environment, and camera movement must remain 
unchanged and untouched. 

Only add gaming-style visual effects: intense glowing sparks and electric arcs 
streaming from the skateboard-rail contact point during the grind, and a 
brilliant energy shockwaves and dust burst at the jump/pop. 

Ein Audio als Input übergeben

Um Audioinputs zu testen, habe ich ein Bild für eine Figur generiert und Fish Audio genutzt, um eine Audiospur mit verschiedenen Emotionen zu erzeugen.

Für die Audiospur wollte ich mehrere Emotionen, um zu sehen, ob Seedance 2 diese bei der Videogenerierung erkennt. 

Fish Audio AI erlaubt es, Emotionen per [emotion] im Prompt zu setzen – ideal für diesen Zweck. Hier ist der verwendete Audioprompt:

[sighing] Nothing much is happening today. [surprised] Wait a minute... what are those on my ears?[laughing] Oh my gosh, I can't believe I got piercings last night! [angry] But hold on, I specifically told you not to let me do it!

Zum Laden der Audiodatei habe ich diese Funktion geschrieben und in utils.py ergänzt:

def load_audio(file_path):
    if not os.path.exists(file_path):
        raise FileNotFoundError(f"Audio file not found at: {file_path}")

    # Guess the mime type (e.g., audio/mpeg for mp3, audio/wav for wav)
    mime_type, _ = mimetypes.guess_type(file_path)
    if mime_type is None:
        mime_type = "audio/mpeg" # Fallback to mp3 just in case

    with open(file_path, "rb") as audio_file:
        encoded_string = base64.b64encode(audio_file.read()).decode('utf-8')
        
    return f"data:{mime_type};base64,{encoded_string}"

Das Bereitstellen des Audios für das Modell funktioniert sehr ähnlich wie bei Bildern. 

Wir laden es als Base64-Data-URI und übergeben es im Parameter contents an das Modell, zum Beispiel so:

response = client.content_generation.tasks.create(
    model="dreamina-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": prompt,
        },
        {
            "type": "image_url",
            "image_url": {
                "url": utils.load_image("./images/cat.png")
            },
            "role": "reference_image"
        },
        {
            "type": "audio_url",
            "audio_url": {
                "url": utils.load_audio("./audio/voice.mp3")
            },
            "role": "reference_audio"
        }
    ],
    ratio="16:9",
    duration=11,
    watermark=True,
    resolution="480p",
)

Das ist das Video, das Seedance 2 generiert hat:

Insgesamt fand ich die Leistung ziemlich gut. 

Gegen Ende beginnt die Figur allerdings zu weinen, was ich bei einer wütenden Emotion nicht erwartet hätte. 

Beachte aber, dass Seedance 2 nicht den Audioprompt erhalten hat, sondern nur die endgültige Audiodatei.

Das vollständige Skript findest du hier.

Seedance 2.0 Projektidee: Ein KI-Videotransition-Tool bauen

Wenn du ein spannendes Projekt suchst, um das Gelernte zu festigen, schreibe ein Python-Skript, das zwei Videos als Input nimmt und:

1. Den letzten Frame des ersten Videos extrahiert.
2. Den ersten Frame des zweiten Videos extrahiert.
3. Mit der hier gezeigten Bildinterpolation eine Überblendung zwischen den beiden Videos erzeugt. 
4. Zum Schluss die drei Videos zu einem einzigen zusammenführt.

Fazit

In diesem Artikel haben wir gezeigt, wie du mit der Seedance 2 API Videos aus Text, Bildern und Audio erzeugst. 

Wir haben die Umgebung eingerichtet, die API-Anbindung hergestellt und die verschiedenen Medieninputs gemanagt, um Ideen zum Leben zu erwecken. Der Prozess ist unkompliziert, und die Kombination der Inputs eröffnet spannende kreative Möglichkeiten.

Insgesamt arbeitet das Modell zuverlässig und liefert gute Ergebnisse. 

Allerdings wirkt es im Vergleich zu anderen aktuellen Videogenerierungsmodellen nicht wie ein Durchbruch oder ein großer Sprung nach vorn. Es erledigt die Aufgabe solide, verändert das Spiel aber nicht unbedingt grundlegend.

Abschließend: So nachvollziehbar die Sicherheitsrichtlinien sind, die den Einsatz realer Gesichter in Eingaben einschränken, so sehr begrenzen sie die praktische Nutzung des Modells. 

Als ich versucht habe, mein eigenes Material zu veredeln, wurden Videos mit meinem Gesicht konsequent abgelehnt. 

Das ist ein Hindernis für Creator, die personalisierte Medien erstellen wollen, und sollte bedacht werden, wenn du das Tool für berufliche oder private Projekte einsetzen möchtest.