Seedance 2.0 API Rehberi: Adım Adım Video Oluşturma Eğitimi

1. Python ortamınızı ve SDK’yı kurma

Python ile BytePlus Ark API’sine bağlanmak için resmi byteplus-python-sdk-v2 paketini kullanacağız. 

Bu proje için bağımlılıkları kurmanın en kolay yolu bir Anaconda ortamı oluşturup requirements.txt dosyasını yüklemektir, şöyle:

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 istemcisini başlatma

Önceden oluşturduğumuz .env dosyasıyla aynı klasörde text_to_video.py adlı yeni bir betik oluşturun.

İlk olarak gerekli paketleri içe aktarmamız gerekiyor:

import os
from byteplussdkarkruntime import Ark
from dotenv import load_dotenv

Sonra, load_dotenv() fonksiyonunu kullanarak API anahtarını .env dosyasından yüklüyoruz:

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

Şimdi BytePlus Ark API’sine istek göndermemizi sağlayan Ark istemcisini başlatıyoruz. 

API anahtarını ortam değişkenlerinden almak ve uluslararası API erişimi için uygun temel URL’yi ayarlamak üzere os kütüphanesini kullanıyoruz:

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

Son olarak bir istem belirliyor ve videoyu üretmek için istemcideki content_generation.tasks.create() fonksiyonunu kullanıyoruz:

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}")

Bir video oluşturma isteği gönderdikten sonra, video oluşturulması biraz zaman aldığından anında bir video alamayız. 

response değişkeninin videonun kendisi olmadığı anlamına gelir. 

Bunun yerine,  video oluşturma görevi hakkında bilgi içeren bir nesnedir. 

Özellikle, videonun oluşturulma ilerlemesini takip etmemizi ve model üretimi tamamladığında videoyu indirmemizi sağlayan görev tanımlayıcısını içerir.

3. Video oluşturma durumunu izleme (Görev yoklama)

Bir görevin durumunu, görev tanımlayıcısını content_generation.tasks.get() fonksiyonuna vererek aşağıdaki gibi alabiliriz:

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

Video ilerlemesini takip etmeyi kolaylaştırmak için aynı klasörde utils.py adında yeni bir betik oluşturuyor ve istemci örneği ile görev tanımlayıcısı verildiğinde video ilerlemesini izleyen bu fonksiyonu ekliyoruz:

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. Python requests ile oluşturulan videoyu indirme

poll_task() fonksiyonu yukarıda uyguladığımız videoyu döndürür 

Artık video oluşturma sürecini takip edebildiğimize göre, ihtiyacımız olan tek şey, oluşturma tamamlandığında onu indirebilmenin bir yoludur. 

BytePlus Ark API, görev yanıtında oluşturulan video dosyasına doğrudan bir URL döndürdüğünden, requests kütüphanesini kullanarak indirebiliriz.

Bunu yapan bir fonksiyon şöyle:

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

Tam Python betiği: Seedance 2 ile metinden videoya

Hepsini bir araya getirerek, Seedance 2 kullanarak bir metin isteminden video üretmek için tam bir betik:

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 çekirdek parametreleri başvuru rehberi

Bir video oluşturma isteğinin çekirdek parametreleri için kabul edilen değerlerin listesi aşağıdadır:

İleri Düzey Rehber: Seedance 2.0 Görüntüden Videoya Yetenekleri

Önceki bölümde, bir metin istemi kullanarak nasıl video oluşturulacağını öğrendik. Seedance 2, görüntü, video ve ses girdilerini de destekler; o hâlde görsellerle başlayalım.

Karakter tutarlılığı için referans görseller kullanma

Görsel girdileri test etmek için, sit-com benzeri bir sahnede kullanmak üzere yapay zekâ ile iki karakter ürettim.

Modeli beslemek için referans görselleri, isteğin content alanına aşağıdaki gibi ekleyebiliriz:

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",
)

Bu video için şu istemi kullandım:

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.

@Image1 ve @Image2 kullanımlarının, görselleri listede verildikleri sırayla referans aldığını unutmayın.

Ne yazık ki bu videoyu oluşturmaya çalıştığımda şu hatayı aldım: 

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

Gerçekçi bir insan içeren referans görsel kullandığımda, hatta yapay zekâ tarafından oluşturulmuş olanlarda bile, Seedance 2’yi kullanmaya çalıştığımda bunun tutarlı biçimde gerçekleştiğini fark ettim. 

Bunu aşmak için karakterleri çizgi filme dönüştürdüm ve tekrar denedim.

Bu kez mükemmel çalıştı ve bence sonuç tam olarak yaratmak istediğim şeydi.

Bu örneğin tam kodunu image_to_video.py dosyasında bulabilirsiniz.

Yönlendirmeli animasyon için ilk ve son kareleri ayarlama

Önceki örnek, istekte ”role”: “reference_image” ayarlanarak görsellerin referans olarak nasıl kullanılacağını gösterdi.

Seedance 2 iki başka görsel rolünü de destekler:

• ”first_frame”: Modele, sağlanan görseli üretilen videonun tam başlangıç karesi olarak kullanmasını söyler. Doğrudan Görüntüden Videoya üretim için standart ayardır.
• ”last_frame”: Modele, üretilen videoyu bu belirli görselle bitirmesini söyler. Not: Bunu yalnızca aynı istekte bir first_frame de sağlıyorsanız kullanabilirsiniz; bu, modelden iki görsel arasında videoyu enterpole etmesini istemek anlamına gelir.

Bunu, doğal yaşamın yok olduğu bir dünyada bitkileri yeniden yaratmaya çalışan bir robot yapay zekâ laboratuvarını gösteren bir dizi başlangıç karesi üreterek denedim. 

Her kare için, o kareyi ilk kare olarak kullanarak bir video oluşturdum. Her isteği şu şekilde yapılandırabilirsiniz:

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",
)

Sesler tutarlı olmayacağından (her video ayrı ayrı üretildiği için) videoları sessiz ürettim. Beş klibi birleştirmenin sonucu şöyle oldu:

Başlangıç karesine dayalı video oluşturmak için kullanılan tam betiği burada bulabilirsiniz.

last_frame ile görüntü enterpolasyonu

Bu örnekte, iki görsel arasında bir video üretmek için hem first_frame hem de last_frame sağlıyoruz.

Aynı odanın iki görselini ürettim; biri mobilyasız boş, diğeri ise tamamen döşenmiş. Amaç, odanın döşenmesini canlandıran bir video üretmek.

Kullandığım istem, mobilyaların videoda nasıl görünmesini istediğimi tarif ediyordu:

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.

İstek şöyle:

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",
)

Ve sonuç şöyle:

Tam betiği burada bulabilirsiniz.

Seedance 2.0 Çok Modlu Girdiler: Ses ve Video Referansları Ekleme

Çok modlu bir model olarak Seedance 2, metin ve görsel girdilerin ötesine geçer. Video ve ses girdilerini de destekler. Bunlar, üslup referansı, hareket yönlendirme veya video düzenleme için kullanılabilir.

Bu örnek resmi web sitelerinde bunu çok iyi gösteriyor. İki aktörün dövüştüğü bir sahneyi alıp, eylemi yönlendirmek için bunu kullandılar ve aktörleri referans görsellerle değiştirdiler:

Video girişi gönderme

Görsellerde olduğu gibi, video girdileri de isteğin content parametresinde sağlanır. 

Ancak, bu yazının yazıldığı sırada video girdileri yalnızca URL’leri destekliyor. Bu da yerel makinemizde bulunan bir videoyu kullanmak istersek, önce onu barındırmamız gerektiği anlamına geliyor.

Bu örnek için Marc Espejo’nun ücretsiz kullanıma açık bu kaykay videosunu kullandım. Fikir, Seedance 2 ile bazı VFX efektleri eklemekti. Sonuç şöyle:

Bunu üretmek için şu isteği kullandım:

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",
)

Tam betiği burada bulabilirsiniz. Kullandığım istem şuydu:

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. 

Ses girişi gönderme

Ses girdilerini test etmek için bir karakter görseli oluşturdum ve farklı duygular içeren bir ses parçası üretmek için Fish Audio kullandım.

Ses için, Seedance 2’nin videoyu oluştururken bunları tespit edip edemeyeceğini görmek üzere birkaç farklı duygu istedim. 

Fish Audio AI, istemde [emotion] kullanarak duyguları belirtmemize imkân veriyor; bu nedenle iş için çok uygundu. Kullandığım ses istemi şöyleydi:

[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!

utils.py’ye eklediğim şu fonksiyonla ses dosyasını yüklüyorum:

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}"

Sesi modele sağlamak, görsellere çok benzer şekilde çalışır. 

Onları base64 veri URI’si olarak yüklüyor ve modele contents parametresinde şu şekilde gönderiyoruz:

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",
)

Seedance 2’nin ürettiği video şöyle:

Genel olarak, oldukça iyi performans gösterdiğini düşünüyorum. 

Nasıl olduysa, sonlara doğru karakter ağlamaya başladı; bu, öfkeli bir duygu için beklediğim bir şey değildi. 

Ancak Seedance 2 ses istemini almadı; yalnızca nihai ses dosyası verildi.

Tam betiği burada bulabilirsiniz.

Seedance 2.0 Proje Fikri: Bir Yapay Zekâ Video Geçiş Aracı Oluşturma

Burada öğrendiklerinizi pekiştirmek için eğlenceli bir proje isterseniz, iki videoyu girdi olarak alan ve şunları yapan bir Python betiği yazmanızı öneririm:

1. İlk videodan son kareyi çıkarır.
2. İkinci videodan ilk kareyi çıkarır.
3. Burada öğrendiğimiz enterpolasyonu kullanarak iki video arasında bir geçiş üretir. 
4. Son olarak betik, üç videoyu tek bir videoda birleştirir.

Sonuç

Bu yazıda, Seedance 2 API’sini kullanarak metin, görsel ve sesten nasıl video üretileceğini inceledik. 

Ortamı kurmayı, API’ye bağlanmayı ve fikirleri hayata geçirmek için gereken çeşitli medya girdilerini yönetmeyi ele aldık. Süreç oldukça yalın ve bu girdileri birleştirme olanağı ilgi çekici yaratıcı ihtimaller sunuyor.

Genel olarak, modelin güvenilir çalıştığını ve sağlam sonuçlar ürettiğini görüyorum. 

Bununla birlikte, piyasadaki diğer video üretim modelleriyle karşılaştırıldığında bir atılım ya da büyük bir sıçrama gibi hissettirmiyor. İşi görüyor, ancak oyunun kurallarını değiştirmiyor.

Son olarak, girdilerde gerçek insan yüzlerinin kullanımını kısıtlayan güvenlik yönergelerinin mantığını tamamen anlasam da, bu kuralların modelin pratik kullanımını önemli ölçüde sınırladığını gördüm. 

Aracı kendi içeriklerimi geliştirmek için kullanmaya çalıştığımda, yüzümün göründüğü videoların tamamı tutarlı biçimde reddedildi. 

Bu durum, kişiselleştirilmiş medya üretmek isteyen içerik üreticileri için bir engel oluşturuyor ve bu aracı profesyonel ya da kişisel projelerinizde kullanmayı düşünüyorsanız göz önünde bulundurmanız gereken bir nokta olarak kalıyor.