DEV Community

Cover image for Seedance 2.0 API 2026 Nasıl Kullanılır?
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

Seedance 2.0 API 2026 Nasıl Kullanılır?

Özet

Seedance 2.0 API, 2 Nisan 2026'da Volcengine Ark aracılığıyla yayınlandı. Bir POST isteğiyle video oluşturma görevi başlatabilir, ardından durum "başarılı" olana kadar bir GET uç noktasını sorgulayabilirsiniz. API; metinden videoya, görselden videoya, ilk/son kare kontrolü, çok modlu referanslar ve yerel ses üretimini destekler. 5 saniyelik 1080p bir video yaklaşık 0,93 dolara mal olur. Videoyu 24 saat içinde indirmeniz gerekir; aksi takdirde URL'nin süresi dolar.

Apidog'u bugün deneyin

Hypereal AI

Hypereal AI

Hypereal AI'yi Deneyin

Giriş

2 Nisan 2026 itibarıyla, ByteDance’in Volcengine Ark platformu resmi Seedance 2.0 API’sini kullanıma açtı. Önceden yalnızca web konsolu üzerinden video üretimi mümkündü. Bu rehber, geliştiricilerin doğrudan API ile entegrasyon süreçlerini kapsar ve programatik kontrol sağlayan uçtan uca uygulama adımlarını sunar.

💡 API asenkron görev modeli kullanır: Görev oluşturmak için POST gönderin, görev kimliğini alın ve iş bitene kadar GET ile sorgulayın. Yayına almadan önce uçtan uca test etmek kritik önem taşır. Apidog’un Test Senaryoları ile POST gönderimini zincirleyin, görev kimliğini çıkarın, GET sorgusunu döngüye alın ve son yanıtta geçerli video URL’si doğrulayın. Alttaki Apidog bölümünde adım adım uygulamayı bulabilirsiniz.

Bu makalede, tüm giriş türlerini, fiyatlama matematiğini ve tipik hata senaryolarının çözümlerini bulacaksınız.

Seedance 2.0 Nedir?

Seedance 2.0, ByteDance tarafından geliştirilen bir video üretim modelidir. Volcengine Ark üzerinde doubao-seedance-2-0-260128 (standart) ve doubao-seedance-2-0-fast-260128 (hızlı, daha düşük kalite) model kimlikleriyle çalışır.

Desteklenen giriş türleri:

  • Metinden videoya
  • Görselden videoya
  • İlk ve son kare kontrolü (başlangıç ve bitiş görselleriyle)
  • Çok modlu referanslar (görsel, video, ses birlikte)
  • Yerel ses üretimi (diyalog, ortam, müzik, 8+ dilde dudak senkronizasyonu)
  • Kamera hareketleri (doğal dil ile kontrol)
  • 2K çözünürlüğe ve 15 saniyeye kadar çıktı

Çıktı videoları 1:1’den 21:9’a kadar en-boy oranlarında ve 24fps olarak üretilir. Çözünürlüğü ve oranı istek sırasında belirtebilirsiniz.

Ne değişti: Kılavuz ve Resmi API

Daha önceki Seedance 2.0 rehberleri web konsolunu anlatıyordu. Artık API ile doğrudan çağrı yapabilir, video oluşturma süreçlerini otomatikleştirebilir, ürünlerinize Seedance’i entegre edebilirsiniz. Bu makale, tamamen API tabanlı entegrasyon içindir.

Önkoşullar

  1. Volcengine hesabı oluşturun: volcengine.com üzerinden ücretsiz hesap alın.
  2. API anahtarınızı alın: 
   https://console.volcengine.com/ark/region:ark+cn-beijing/apikey
Enter fullscreen mode Exit fullscreen mode
  1. Anahtarı ortam değişkeni olarak ayarlayın: 
   export ARK_API_KEY="your-api-key-here"
Enter fullscreen mode Exit fullscreen mode
  1. API çağrılarında Authorization başlığında kullanın: 
   Authorization: Bearer YOUR_ARK_API_KEY
Enter fullscreen mode Exit fullscreen mode

Yeni hesaplar, 1080p’de yaklaşık 8 adet 15 saniyelik video oluşturmanıza yetecek ücretsiz krediyle başlar.

Metinden Videoya: İlk İsteğiniz

Temel URL:

https://ark.cn-beijing.volces.com/api/v3
Enter fullscreen mode Exit fullscreen mode

cURL Örneği 

curl -X POST "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "A golden retriever running through a sunlit wheat field, wide tracking shot, cinematic"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5,
    "watermark": false
  }'
Enter fullscreen mode Exit fullscreen mode

API hemen bir görev kimliği döndürür:

{"id": "cgt-2025xxxxxxxx-xxxx"}
Enter fullscreen mode Exit fullscreen mode

Python Örneği (Resmi SDK)

SDK kurulumu:

pip install volcenginesdkarkruntime
Enter fullscreen mode Exit fullscreen mode

Görev gönderimi:

import os
from volcenginesdkarkruntime import Ark

client = Ark(api_key=os.environ.get("ARK_API_KEY"))

resp = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": "A golden retriever running through a sunlit wheat field, wide tracking shot, cinematic"
        }
    ],
    resolution="1080p",
    ratio="16:9",
    duration=5,
    watermark=False,
)

print(resp.id)
Enter fullscreen mode Exit fullscreen mode

Görev kimliğini sonraki sorgulama adımında kullanacaksınız.

Asenkron Görev Modeli: Gönder, Sorgula, İndir

Seedance çıktısı anlık değildir. 5 saniyelik 1080p video genellikle 60–120 saniyede tamamlanır. İş akışı:

queued -> running -> succeeded
                -> failed
                -> expired
                -> cancelled
Enter fullscreen mode Exit fullscreen mode

Durum queued veya running ise döngüyle sorgulama yapmanız gerekir.

Tam Python Sorgulama Döngüsü 

import os
import time
import requests
from volcenginesdkarkruntime import Ark

client = Ark(api_key=os.environ.get("ARK_API_KEY"))

# Adım 1: Görev gönder
resp = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {"type": "text", "text": "Aerial shot of a mountain lake at sunrise, slow dolly forward"}
    ],
    resolution="1080p",
    ratio="16:9",
    duration=5,
    watermark=False,
)
task_id = resp.id
print(f"Task submitted: {task_id}")

# Adım 2: Üstel gecikme ile sorgula
wait = 10
while True:
    result = client.content_generation.tasks.get(task_id=task_id)
    status = result.status
    print(f"Status: {status}")

    if status == "succeeded":
        video_url = result.content.video_url
        print(f"Video URL: {video_url}")
        break
    elif status in ("failed", "expired", "cancelled"):
        print(f"Task ended with status: {status}")
        break

    time.sleep(wait)
    wait = min(wait * 2, 60)

# Adım 3: Hemen indir
if status == "succeeded":
    response = requests.get(video_url, stream=True)
    with open("output.mp4", "wb") as f:
        for chunk in response.iter_content(chunk_size=8192):
            f.write(chunk)
    print("Downloaded: output.mp4")
Enter fullscreen mode Exit fullscreen mode

Üstel geri çekilme, API limitlerini aşmamayı sağlar. 60 saniyede sınır, pratik sorgulama sıklığı için uygundur.

Görselden Videoya (I2V): Durağan Bir Görseli Canlandırma

Bir görseli canlandırmak için, metin isteminizle birlikte content dizisine bir image_url ekleyin. Görsel, videonun ilk karesi olur.

resp = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": "The woman slowly turns her head and smiles at the camera"
        },
        {
            "type": "image_url",
            "image_url": {"url": "https://example.com/portrait.jpg"}
        }
    ],
    ratio="adaptive",
    duration=5,
    watermark=False,
)
Enter fullscreen mode Exit fullscreen mode

ratio değerini "adaptive" seçmek, giriş görselinin doğal oranını korur. Her görsel 30MB'ın altında olmalı; bir istekte 9 adede kadar görsel ekleyebilirsiniz.

İlk ve Son Kare: Başlangıç ve Bitiş Noktalarını Kontrol Etme

Başlangıç ve bitiş karesi kontrolü için iki görsel ve bir metin istemi gönderin. Model, aradaki hareketi otomatik oluşturur.

resp = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": "The flower blooms from bud to full open, macro lens, soft light"
        },
        {
            "type": "image_url",
            "image_url": {"url": "https://example.com/flower-bud.jpg"}
        },
        {
            "type": "image_url",
            "image_url": {"url": "https://example.com/flower-open.jpg"}
        }
    ],
    ratio="adaptive",
    duration=8,
    watermark=False,
)
Enter fullscreen mode Exit fullscreen mode

Görseller sıralı olmalı: önce ilk kare, sonra son kare. return_last_frame: true ile son kareyi çıktı olarak alabilir, zincirleme kliplerde kullanabilirsiniz.

Çok Modlu Referans: Görsel, Video ve Sesi Birleştirme

Seedance 2.0, görsel, video ve sesi aynı istekte referans olarak kullanmanıza olanak tanır.

Kabul edilen içerik türleri:

  • {"type": "text", "text": "..."}
  • {"type": "image_url", "image_url": {"url": "..."}}
  • {"type": "video_url", "video_url": {"url": "..."}}
  • {"type": "audio_url", "audio_url": {"url": "..."}}

Sınırlar:

  • Max 9 görsel (her biri ≤30MB)
  • Max 3 video (her biri 2–15sn, ≤50MB)
  • Max 3 ses dosyası (MP3, ≤15MB)

Birleşik referans örneği:

resp = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": "Match the visual style of the reference clip and add the provided background audio"
        },
        {
            "type": "image_url",
            "image_url": {"url": "https://example.com/style-reference.jpg"}
        },
        {
            "type": "video_url",
            "video_url": {"url": "https://example.com/motion-reference.mp4"}
        },
        {
            "type": "audio_url",
            "audio_url": {"url": "https://example.com/background-music.mp3"}
        }
    ],
    duration=10,
    ratio="16:9",
    watermark=False,
)
Enter fullscreen mode Exit fullscreen mode

Video referansı eklerseniz faturalandırma V2V oranına düşer (bkz. fiyatlandırma bölümü).

Yerel Ses Üretimi

Videoyla senkronize ses üretmek için generate_audio: true parametresini kullanın.

resp = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": "A street musician plays guitar outside a cafe in Paris, crowds passing by, city sounds"
        }
    ],
    resolution="1080p",
    ratio="16:9",
    duration=10,
    generate_audio=True,
    watermark=False,
)
Enter fullscreen mode Exit fullscreen mode

Ses ile video ortak üretimi, token tüketimini hafifçe artırır. Dudak senkronizasyonu ve çok dilli destek mevcuttur.

Çözünürlük, En Boy Oranı ve Süreyi Kontrol Etme

  • Çözünürlük: "480p", "720p", "1080p", "2K" (varsayılan: "1080p")
  • En boy oranı: "16:9", "9:16", "4:3", "3:4", "21:9", "1:1", "adaptive"
  • Süre: 4–15 saniye (varsayılan: 5)

Hızlı model (doubao-seedance-2-0-fast-260128), düşük kalite ve hızlı üretim için; standart model ise final çıktı için önerilir.

Yanıttan Maliyeti Okuma

Başarılı bir görevde yanıt şöyle döner:

{
  "usage": {
    "completion_tokens": 246840,
    "total_tokens": 246840
  }
}
Enter fullscreen mode Exit fullscreen mode

5 saniyelik 1080p video ≈ 102.960 token, 15 saniyelik 1080p ≈ 308.880 token.

  • T2V/I2V: Milyon token başına 46 yuan (~6,40 $)
  • V2V: Milyon token başına 28 yuan (~3,90 $)

Her yanıtta completion_tokens'ı oranlarla çarparak maliyetinizi hesaplayın.

Önemli: Videoyu 24 Saat İçinde İndirin

Yanıttaki video_url, 24 saat sonra geçerliliğini kaybeder ve 403 hatası verir. Dosyayı hemen indirin. execution_expires_after alanı 48 saatlik görev kaydı penceresini gösterir, ancak video dosyası 24 saat sonra silinir. Görev geçmişi 7 gün tutulur.

Apidog ile Seedance API’sini Test Etme

Asenkron modelde iki bağlı API çağrısı gerekir; klasik testler yetersizdir. Apidog Test Senaryoları ile zincirli akış kurabilirsiniz.

Apidog Test

Adım adım:

  1. Test Senaryosu Oluşturun:

    Testler modülünde “Seedance 2.0 video üretimi” senaryosu açın. {{ARK_API_KEY}} ortam değişkenini ayarlayın.

  2. Gönderme isteğini ekleyin:

    Özel POST isteği adımı ile anahtarınızı authorization başlığına ekleyin. Yanıt gövdesinden $.id ile TASK_ID çıkarın.

  3. Bekleme işlemi ekleyin:

    30 saniyelik gecikme ile ilk sorgulama öncesi işlem süresi verin.

  4. Sorgu adımını For döngüsüne alın:

    Max 20 iterasyon, her GET isteği sonrası 10 saniye bekleme. Döngü çıkış koşulları: $.status == "succeeded" veya $.status == "failed".

  5. Doğrulama ekleyin:

    Döngü sonunda "succeeded" durumu ve boş olmayan video_url kontrolü ekleyin.

Senaryoyu çalıştırdığınızda, adım adım tüm süreci ve hata noktalarını raporlayabilirsiniz. Ayrıca cURL komutlarını doğrudan test senaryosuna aktarabilirsiniz.

Fiyatlandırma Dökümü: 10 Saniyelik Bir Videonun Maliyeti

Seedance API, kullandıkça öde (pay-as-you-go) ile çalışır. Aylık sabit ücret yoktur.

Görev Türü Oran (1M token başına)
1080p'de T2V / I2V 46 yuan (~6,40 $)
V2V (video referanslı) 28 yuan (~3,90 $)
Süre Yaklaşık token Maliyet (T2V/I2V)
5 saniye ~103.000 ~0,66 yuan / ~0,93 $
10 saniye ~206.000 ~9,48 yuan / ~1,32 $
15 saniye ~309.000 ~14,21 yuan / ~1,97 $

Yeni hesaplar ücretsiz deneme kredisi içerir (yaklaşık 8 adet 15 saniyelik deneme). Geliştirmede düşük çözünürlük (örn. 720p) ile başlayıp, üretimde çözünürlüğü yükseltin.

Sık Karşılaşılan Hatalar ve Çözümleri

429 Çok Fazla İstek:

Eşzamanlı görev limitine ulaştınız. Üstel geri çekilme uygulayın (bekleme aralığını artırarak yeniden deneyin).

durum: "failed":

Model videoyu üretemedi. Nedeni: istemde uygunsuz içerik, bozuk/büyük giriş dosyaları veya geçersiz parametre kombinasyonu. Girdileri düzeltip tekrar deneyin.

durum: "expired":

Görev, uzun süre kuyrukta kaldı ve sona erdi. Yeniden başlatmanız gerekir.

video_url üzerinde 403 hatası:

24 saatlik indirme süresi geçti. Aynı parametrelerle yeni görev başlatın.

Tohum tekrarlanabilirliği:

Bir görevden seed değerini kaydedip sonraki istekte kullanırsanız, aynı çıktıyı elde etmeye çalışırsınız (model versiyonu değişmediyse).

Sonuç

Seedance 2.0 API, gelişmiş video üretim iş akışlarına kodla erişim sunar. Asenkron görev modeliyle, otomatik ve modüler süreçler kurabilirsiniz. Çok modlu girişler, yerel ses üretimi ve başlangıç/bitiş karesi kontrolüyle, API üzerinden web konsolunun ötesine geçin.

Üretim öncesi Apidog ile test zinciri kurarak, tüm akışınızı güvence altına alın. Test Senaryoları ile zincirleme, hata noktalarını ve sona erme sorunlarını erken tespit edin.

Sıkça Sorulan Sorular

S: doubao-seedance-2-0-260128 ile doubao-seedance-2-0-fast-260128 arasındaki fark nedir?

C: Standart model daha yüksek kalite sunar ve üretim için uygundur. Hızlı model ise düşük kaliteyle daha kısa sürede sonuç verir; deneme ve iterasyon için hızlı modeli, final için standart modeli kullanın.

S: Seedance 2.0'ı Çin dışında kullanabilir miyim?

C: API Pekin’de barındırılır. Çin dışından kullanılabilir, ancak gecikme artabilir. Bölgesel kısıtlamalar için Volcengine koşullarını kontrol edin.

S: Birden fazla klibi birleştirmek mümkün mü?

C: Her üretimde return_last_frame: true kullanın. Yanıttaki son kareyi bir sonraki isteğin ilk karesi olarak aktarın. Tüm klipleri elde ettikten sonra birleştirin.

S: Yerel ses üretimi daha maliyetli mi?

C: Evet, generate_audio: true ile isteklerde token tüketimi hafifçe artar.

S: Sorgulama yerine webhook kullanabilir miyim?

C: Evet, callback_url parametresi ile durum değişiminde sonuç otomatik POST edilir.

S: 9 görsel sınırını aşarsam ne olur?

C: API 400 doğrulama hatası döndürür. 9 görsel veya daha az ile tekrar deneyin.

S: Tohum parametresi tam tekrarlanabilirlik sağlar mı?

C: Yüksek tekrarlanabilirlik sunar, ancak model versiyonu değişirse tam garanti yoktur.

S: Birden fazla görevde harcamayı nasıl takip ederim?

C: Her yanıttaki completion_tokens ile kendi maliyet takibinizi oluşturun. API'da entegre panel yoktur; veritabanınızda saklayın.

Top comments (0)