API Seedance

API membolehkan anda menyerahkan tugas penjanaan video Seedance 2.5 dan Seedance 2.0 secara programatik. Seedance 2.5 ialah model yang disyorkan dan menyokong teks-ke-video, imej-ke-video bingkai pertama atau bingkai pertama-dan-terakhir, serta rujukan-ke-video berbilang mod. Penjanaan adalah secara tak segerak (async): cipta tugas, terima ID tugas dengan serta-merta, kemudian dapatkan video yang telah siap dengan membuat pengundian (polling) pada titik akhir tugas atau melalui webhook.

Cipta kunci API dalam papan pemuka dan hantarkannya sebagai token Bearer pada setiap permintaan. Kunci penuh hanya dipaparkan sekali sahaja semasa penciptaan.

Authorization: Bearer sk_live_xxxxxxxx

Serahkan tugas terlebih dahulu. Selepas tugas diterima, pilih satu kaedah penghantaran hasil: buat pengundian pada titik akhir tugas, atau terima hasil akhir melalui webhook.

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

Cipta tugas video dengan POST /v1/videos/generations. Isi permintaan mempunyai model peringkat atas, callback_url pilihan, dan objek input yang mengandungi prom serta tetapan penjanaan.

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 mengawal jenis input media yang diterima dan cara model mentafsirkannya.

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

Nama parameter, nilai enum, laluan titik akhir, dan contoh adalah sebahagian daripada kontrak API. Penerangan di bawah menjelaskan fungsi setiap medan.

Ini ialah respons kejayaan daripada POST /v1/videos/generations. Ini bermakna tugas telah diterima dan kredit telah dikhaskan. Gunakan taskId yang dikembalikan untuk melakukan pengundian GET /v1/tasks/:id atau untuk dipadankan dengan panggilan balik selesai atau gagal.

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

Gunakan GET /v1/tasks/:id untuk mendapatkan keadaan tugas semasa. Lakukan pengundian tidak lebih daripada sekali setiap 10 saat. Untuk sistem pengeluaran, webhook adalah pilihan yang lebih disyorkan.

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

Apabila callback_url disediakan, Seedance akan memanggil titik akhir anda apabila tugas selesai atau gagal, dan menghantar data JSON yang menerangkan hasil akhir. Jika titik akhir anda mengembalikan respons selain 2xx atau tidak bertindak balas dalam masa 15 saat, penghantaran akan dicuba semula sehingga 5 kali. Percubaan semula menggunakan id tugas yang sama, jadi sila lakukan penyahduplikasian berdasarkan id. Kembalikan respons 200 sebaik sahaja anda telah merekodkan data panggilan balik dengan selamat.

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

POST /v1/videos/generations dan GET /v1/tasks/:id mengembalikan bentuk ralat ini apabila permintaan API itu sendiri gagal, seperti parameter tidak sah, kunci API tidak sah, kredit tidak mencukupi, had kadar dipenuhi, atau tugas tidak ditemui. Sesetengah ralat menyertakan medan tambahan seperti required, available, atau retry_after bergantung pada keadaan.

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

Had kadar digunakan bagi setiap kunci API dengan tetingkap gelongsor (sliding window). Penjanaan ditetapkan secara lalai kepada 100 permintaan seminit; pertanyaan status adalah lebih longgar. Respons HTTP 429 menyertakan pengepala Retry-After.

API menggunakan kaedah tempah semasa serah, caj apabila berjaya, dan pulangkan jika gagal. Halaman penggunaan papan pemuka memaparkan sejarah kredit API, log tugas, dan statistik penggunaan mengikut masa.