Seedance API

API, Seedance 2.5 ve Seedance 2.0 video oluşturma görevlerini programatik olarak göndermenizi sağlar. Önerilen model olan Seedance 2.5; metinden videoya, ilk kare veya ilk ve son kare görselden videoya ve çoklu mod referanslı video oluşturma özelliklerini destekler. Video oluşturma işlemi eşzamansız (asynchronous) olarak yürütülür: Bir görev oluşturduğunuzda hemen bir görev kimliği (task ID) alırsınız; ardından görev uç noktasını yoklayarak (polling) veya bir webhook aracılığıyla tamamlanan videoya erişebilirsiniz.

Kullanıcı panelinden bir API anahtarı oluşturun ve her istekte bunu Bearer token olarak gönderin. API anahtarının tamamı yalnızca oluşturulduğu an bir kez gösterilir.

Authorization: Bearer sk_live_xxxxxxxx

Öncelikle bir görev gönderin. Görev kabul edildikten sonra sonuç teslim yöntemlerinden birini seçin: Görev uç noktasını belirli aralıklarla sorgulayabilir veya sonucu bir webhook üzerinden doğrudan alabilirsiniz.

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cat surfing on a neon wave, cinematic lighting",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false
    }
  }'

curl https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer sk_live_xxx"

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrl = callbackData.data.results[0];
    // Save the video URL or update your own task record here.
  }

  if (callbackData.status === "failed") {
    const errorMessage = callbackData.data.failed_reason;
    // Mark your own task record as failed here.
  }

  return new Response(null, { status: 200 });
}

POST /v1/videos/generations uç noktasıyla bir video görevi oluşturun. İstek gövdesi; üst düzey bir model parametresi, isteğe bağlı bir callback_url ve istem ile oluşturma ayarlarını barındıran bir input nesnesinden oluşur.

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cat surfing on a neon wave, cinematic lighting",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false
    }
  }'

generation_type parametresi, hangi medya girdilerinin kabul edileceğini ve modelin bunları nasıl yorumlayacağını belirler.

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cinematic drone shot over a futuristic coastal city at sunrise",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false
    }
  }'

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "input": {
      "prompt": "the subject turns toward camera, soft studio motion",
      "generation_type": "image-to-video",
      "image_urls": ["https://your.cdn.com/first-frame.jpg"],
      "duration": 5,
      "resolution": "720p"
    }
  }'

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "input": {
      "prompt": "use the product from image 1 and the camera motion from the reference video",
      "generation_type": "reference-to-video",
      "image_urls": ["https://your.cdn.com/product.jpg"],
      "video_urls": ["https://your.cdn.com/camera-motion.mp4"],
      "audio_urls": [],
      "duration": 8,
      "resolution": "720p"
    }
  }'

Parametre adları, enum değerleri, uç nokta yolları ve örnekler API protokolünün bir parçasıdır. Aşağıdaki açıklamalar her bir alanın nasıl çalıştığını açıklamaktadır.

Bu yanıt, POST /v1/videos/generations isteğinin başarıyla tamamlandığını gösterir. Görevin kabul edildiği ve kredilerin rezerve edildiği anlamına gelir. GET /v1/tasks/:id uç noktasını sorgulamak veya gelen geri çağrı bildirimini eşleştirmek için dönen taskId değerini kullanın.

{
  "taskId": "3f2aK9mR...",
  "credits": 100
}

Mevcut görev durumunu sorgulamak için GET /v1/tasks/:id uç noktasını kullanın. Sorgulamayı 10 saniyede birden daha sık yapmayın. Canlı sistemler için webhook kullanımı önerilir.

curl https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer sk_live_xxx"

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "billing_status": "charged",
  "credits": 100,
  "failed_reason": null,
  "data": {
    "results": ["https://cdn.seevio.ai/.../x.mp4"],
    "video_expires_at": "2026-06-13T10:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

{
  "id": "3f2aK9mR...",
  "status": "failed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "billing_status": "refunded",
  "credits": 100,
  "failed_reason": "provider_failed"
}

callback_url tanımlandığında, Seedance görev başarıyla tamamlandığında veya başarısız olduğunda uç noktanızı çağırır ve nihai sonucu açıklayan bir JSON verisi gönderir. Uç noktanız 2xx dışında bir yanıt döndürürse veya 15 saniye içinde yanıt vermezse, gönderim en fazla 5 kez yeniden denenir. Yeniden denemelerde aynı görev kimliği (task id) kullanılır, bu nedenle mükerrer kayıtları engellemek için id bazlı tekilleştirme yapın. Webhook verisini güvenli bir şekilde kaydeder kaydetmez anında bir 200 yanıtı döndürün.

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "data": {
    "results": ["https://cdn.seevio.ai/.../x.mp4"],
    "video_expires_at": "2026-06-13T10:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

{
  "id": "3f2aK9mR...",
  "status": "failed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "data": {
    "failed_reason": "provider_failed",
    "credits_refunded": 100
  }
}

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrl = callbackData.data.results[0];
    // Save the video URL or update your own task record here.
  }

  if (callbackData.status === "failed") {
    const errorMessage = callbackData.data.failed_reason;
    // Mark your own task record as failed here.
  }

  return new Response(null, { status: 200 });
}

Geçersiz parametreler, geçersiz API anahtarı, yetersiz bakiye, istek sınırı aşımı veya görevin bulunamaması gibi API isteğinin kendisinin başarısız olduğu durumlarda POST /v1/videos/generations ve GET /v1/tasks/:id uç noktaları bu hata formatını döndürür. Bazı hatalar duruma bağlı olarak required, available veya retry_after gibi ek alanlar içerebilir.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this task.",
    "required": 100,
    "available": 12
  }
}

İstek sınırları, hareketli zaman penceresi (sliding window) yöntemiyle API anahtarı başına uygulanır. Video oluşturma sınırı varsayılan olarak dakikada 100 istektir; durum sorgulama limitleri ise daha esnektir. HTTP 429 yanıtları Retry-After üstbilgisini içerir.

API; istek gönderildiğinde rezerve etme, işlem başarılı olduğunda tahsil etme ve hata durumunda iade etme modelini kullanır. Yönetici panelindeki kullanım sayfaları; API kredi geçmişini, görev günlüklerini ve zamana dayalı kullanım istatistiklerini görüntüler.