Pembuatan Video Seedance — POST /v1/videos

Gunakan POST /v1/videos untuk membuat tugas pembuatan video Seedance secara asinkron. Pantau tugas hingga selesai, lalu unduh video dari URL Flatkey yang dikembalikan. Model yang didukung adalah seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, dan seedance-2.5. Ketersediaan bergantung pada akun Anda; gunakan GET /v1/models untuk mengambil daftar model terkini.

Endpoint

POST https://router.flatkey.ai/v1/videos

Flatkey juga menerima POST /v1/video/generations dan GET /v1/video/generations/{task_id}. Gunakan /v1/videos untuk struktur respons standar dan data usage natif.

Permintaan

Header	Nilai
`Authorization`	`Bearer $FLATKEY_API_KEY`
`Content-Type`	`application/json`

Parameter body

string

wajib

ID model Seedance: "seedance-2.0", "seedance-2.0-fast", "seedance-2.0-mini", atau "seedance-2.5".

array

wajib

Item input multimodal. Sertakan setidaknya satu item teks yang tidak kosong, gambar, video, atau audio. Lihat item content.

string

Resolusi output. Default: "720p".

Model	Nilai yang didukung
`seedance-2.0`	`"480p"`, `"720p"`, `"1080p"`, `"4k"`
`seedance-2.0-fast`, `seedance-2.0-mini`	`"480p"`, `"720p"`
`seedance-2.5`	`"480p"`, `"720p"`, `"1080p"`

string

Rasio aspek output: "16:9", "4:3", "1:1", "3:4", "9:16", "21:9", atau "adaptive". Default: "adaptive". Dengan "adaptive", model memilih rasio berdasarkan gambar atau video input Anda. Untuk seedance-2.5, tugas frame pertama dan frame pertama/terakhir hanya mendukung "adaptive".

integer

Durasi video dalam detik. Default: 5. Model Seedance 2.0 menerima 4 hingga 15; seedance-2.5 menerima 4 hingga 30.

Selalu kirim duration bernilai positif. Flatkey menagih Seedance per detik, sehingga -1 (membiarkan model memilih durasi) ditolak dengan video_price_not_configured. Satu-satunya pengecualian adalah pengeditan video seedance-2.5, yang mewajibkan -1.

boolean

Menambahkan tanda air “AI generated” di pojok kanan bawah. Default: false.

boolean

Menghasilkan trek audio mono yang tersinkronisasi. Default: true. Atur ke false jika Anda hanya membutuhkan video; audio yang dihasilkan sesekali dapat gagal dalam pemeriksaan hak cipta.

boolean

Mengembalikan frame terakhir dari video yang dihasilkan sebagai gambar. Default: false. Jika true, tugas yang telah selesai menyertakan metadata.last_frame_url, yang mengunduh JPEG berdimensi sama dengan video dan tanpa tanda air. Gunakan gambar ini sebagai first_frame untuk tugas berikutnya guna menyambung klip. Seperti metadata.url, URL ini tidak memerlukan header otorisasi; perlakukan sebagai privat.

string

Khusus seedance-2.5. Kontainer video yang dihasilkan: "mp4" atau "mov". Default: "mp4". MOV mempertahankan presisi warna yang lebih tinggi untuk color grading dan compositing (H.264, YUV 4:4:4, audio PCM), tetapi beberapa pemutar tidak dapat membukanya. Endpoint konten mengembalikan video/quicktime untuk hasil MOV.

string

Khusus seedance-2.5, untuk tugas mode referensi. Memberi tahu model tugas yang ingin Anda jalankan: "auto" (default), "reference", "edit", atau "extend". Menetapkannya secara eksplisit memindahkan pemeriksaan jenis tugas ke saat pengiriman, sehingga kombinasi yang tidak valid langsung gagal alih-alih gagal setelah tugas dimulai. "reference", "edit", dan "extend" semuanya memerlukan item referensi di content; permintaan yang hanya berisi teks dengan "reference" akan ditolak. Lihat pengeditan dan perpanjangan video.

integer

Prioritas antrean dari 0 hingga 9. Default: 0. Nilai yang lebih tinggi menempatkan tugas di depan tugas berprioritas lebih rendah yang menunggu model yang sama. Didukung di semua model Seedance 2.0 dan seedance-2.5. Nilai di luar 0–9 ditolak dengan 400.

integer

Jumlah detik tugas boleh menunggu dan berjalan sebelum kedaluwarsa. Default: 172800 (48 jam). Gunakan nilai yang lebih pendek jika hasil yang terlambat tidak berguna bagi Anda.

string

URL HTTPS publik yang menerima POST setiap kali status tugas berubah. Lihat Callback tugas. Harus menggunakan https, tidak berisi kredensial pengguna, panjangnya maksimal 2.048 karakter, dan di-resolve ke alamat publik; jika tidak, permintaan ditolak dengan 400.

Item `content`

`type`	Kolom nilai	`role` yang didukung	Batasan
`text`	`text`	—	Teks prompt. Usahakan di bawah sekitar 1.000 kata bahasa Inggris.
`image_url`	`image_url.url`	`first_frame`, `last_frame`, `reference_image`	Hingga 9 gambar referensi (`seedance-2.5`: 30). JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, atau HEIF; di bawah 30 MB; 300–6000 px per sisi; rasio aspek 0,4–2,5.
`video_url`	`video_url.url`	`reference_video`	Hingga 3 video, masing-masing 2–15 detik dan total 15 detik (`seedance-2.5`: 10 video, 30 detik). MP4 atau MOV; di bawah 200 MB; total piksel minimal sekitar 409.600 (misalnya 854×480).
`audio_url`	`audio_url.url`	`reference_audio`	Hingga 3 klip, masing-masing 2–15 detik dan total 15 detik (`seedance-2.5`: 10 klip, 30 detik). WAV atau MP3; di bawah 15 MB. Model Seedance 2.0 memerlukan setidaknya satu gambar atau video yang menyertai audio.

Setiap URL dapat berupa URL HTTPS publik, data URI data:<mime>;base64, (hanya untuk gambar dan audio), atau referensi asset:// dari pustaka aset. Seluruh body permintaan harus di bawah 64 MB. Pilih satu mode input per tugas. Mode-mode ini tidak dapat dicampur:

Mode	Cara menyusun `content`
Frame pertama	Satu gambar dengan `role: "first_frame"`.
Frame pertama dan terakhir	Dua gambar, satu dengan `role: "first_frame"` dan satu dengan `role: "last_frame"`. `last_frame` selalu memerlukan `first_frame`, dan keduanya tidak dapat digabungkan dengan item referensi.
Referensi	Kombinasi apa pun dari item `reference_image`, `reference_video`, dan `reference_audio`.

Pengeditan video

seedance-2.5 dapat mengedit atau memperpanjang video yang sudah ada dalam mode referensi. Jelaskan perubahannya di prompt dan sebut video tersebut sebagai @Video1.

Tugas	Pengaturan wajib	Durasi output
Edit (mengganti subjek, menambah atau menghapus objek, mengubah audio)	Setidaknya satu `reference_video` berdurasi 4–30 detik, `ratio: "adaptive"`, `duration: -1`. Disarankan: `omni_reference_task_type: "edit"`.	Sama dengan video input yang diedit
Perpanjangan (melanjutkan video ke depan atau ke belakang)	Setidaknya satu `reference_video`, `ratio: "adaptive"`, `duration` bernilai positif. Disarankan: `omni_reference_task_type: "extend"`.	`duration`

{
  "model": "seedance-2.5",
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": -1,
  "omni_reference_task_type": "edit",
  "content": [
    { "type": "text", "text": "Edit @Video1: make the ball bright green and keep everything else unchanged." },
    { "type": "video_url", "video_url": { "url": "https://example.com/input.mp4" }, "role": "reference_video" }
  ]
}

Seperti setiap permintaan seedance-2.5 dengan video referensi, pengeditan ditagih dengan tarif dengan video untuk resolusi tersebut selama 30 detik tetap, berapa pun durasi input maupun output-nya.

Mode draf

seedance-2.5 dapat merender draf 480p yang murah terlebih dahulu, sehingga Anda dapat memeriksa adegan, pengambilan gambar, dan gerakan sebelum membayar video final. Diperlukan dua permintaan:

Buat draf. Kirim permintaan biasa dengan "draft": true dan "resolution": "480p". Draf ditagih sebagai video 480p biasa.
Hasilkan video final. Setelah draf selesai, kirim permintaan yang satu-satunya item content-nya adalah draft_task yang merujuk ke ID tugas draf, dengan "resolution": "1080p".

{
  "model": "seedance-2.5",
  "resolution": "1080p",
  "content": [
    { "type": "draft_task", "draft_task": { "id": "task_3f9a00000000000000000000000000e2" } }
  ]
}

Video final menggunakan kembali prompt, media, durasi, rasio aspek, seed, pengaturan audio, dan jenis tugas dari draf. Jangan kirim duration, ratio, frames, seed, generate_audio, omni_reference_task_type, draft, atau item content lain bersama draft_task; permintaan akan ditolak dengan 400. Anda tetap dapat mengatur return_last_frame, output_format, watermark, priority, execution_expires_after, dan callback_url.

Aturan	Detail
Model	`model` harus sama dengan model draf.
ID tugas draf	Gunakan ID `task_…` yang dikembalikan Flatkey untuk draf. Tugas tersebut harus milik Anda sendiri dan sudah selesai.
Resolusi	Draf: hanya `480p`. Video final: hanya `1080p`.
Masa berlaku	Draf dapat digunakan selama 7 hari sejak dibuat.
Penagihan	Video final ditagih dengan tarif 1080p untuk durasi draf. Jika draf menggunakan video referensi, tarif dengan video berlaku untuk 30 detik tetap.

Seedance tidak menerima secara langsung gambar atau video yang menampilkan wajah manusia asli. Unggah sebagai aset orang-nyata lalu rujuk dengan asset://.

Contoh permintaan

import os
import requests

response = requests.post(
    "https://router.flatkey.ai/v1/videos",
    headers={
        "Authorization": f"Bearer {os.environ['FLATKEY_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "seedance-2.0",
        "content": [
            {
                "type": "text",
                "text": "An astronaut walking on the moon, cinematic lighting, slow camera push-in",
            }
        ],
        "resolution": "1080p",
        "ratio": "16:9",
        "duration": 5,
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://router.flatkey.ai/v1/videos", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FLATKEY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedance-2.0",
    content: [
      {
        type: "text",
        text: "An astronaut walking on the moon, cinematic lighting, slow camera push-in",
      },
    ],
    resolution: "1080p",
    ratio: "16:9",
    duration: 5,
  }),
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

curl https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "An astronaut walking on the moon, cinematic lighting, slow camera push-in"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'

Input frame pertama dan terakhir

{
  "model": "seedance-2.0",
  "content": [
    { "type": "text", "text": "The camera slowly moves forward" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first.jpg" },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/last.jpg" },
      "role": "last_frame"
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": false
}

Referensi multimodal

{
  "model": "seedance-2.0",
  "content": [
    { "type": "text", "text": "A woman smiles at the camera during a beach sunset" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/reference.jpg" },
      "role": "reference_image"
    }
  ],
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5,
  "watermark": false
}

Respons

{
  "id": "task_3f9a00000000000000000000000000e2",
  "task_id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "model": "seedance-2.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1780306574
}

Kolom respons

string

ID tugas publik yang digunakan untuk memantau tugas dan mengunduh video yang telah selesai. task_id berisi nilai yang sama.

string

Status tugas: queued, in_progress, completed, atau failed.

integer

Kemajuan pembuatan dari 0 hingga 100.

integer

Timestamp Unix untuk pembuatan tugas.

Pantau status tugas

GET https://router.flatkey.ai/v1/videos/{task_id}

curl https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2 \
  -H "Authorization: Bearer $FLATKEY_API_KEY"

Selama pembuatan berlangsung, respons menyertakan kemajuan saat ini:

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "in_progress",
  "progress": 50,
  "model": "seedance-2.0",
  "created_at": 1780306574
}

Ketika tugas selesai, respons menyertakan URL video dan penggunaan token:

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "model": "seedance-2.0",
  "usage": {
    "completion_tokens": 120,
    "total_tokens": 120
  },
  "metadata": {
    "url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content",
    "last_frame_url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/last-frame"
  },
  "created_at": 1780306574,
  "completed_at": 1780306750
}

Tugas yang gagal mengembalikan detail kesalahan beserta respons tugas:

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "failed",
  "error": {
    "message": "The video generation task failed.",
    "code": ""
  }
}

Saldo yang telah dikonsumsi sebelumnya akan dikembalikan secara otomatis.

Nilai status

Status	Arti
`queued`	Tugas sedang menunggu untuk dimulai.
`in_progress`	Video sedang dibuat. `progress` berkisar dari 0 hingga 100.
`completed`	Video siap di `metadata.url`, dan penggunaan token tersedia di `usage`.
`failed`	Pembuatan gagal. Detail tersedia di `error.message`, dan saldo yang telah dikonsumsi sebelumnya akan dikembalikan.

Callback tugas

Atur callback_url untuk menerima perubahan status sebagai pengganti polling, atau sebagai pelengkapnya. Flatkey mengirim POST dengan Content-Type: application/json saat tugas berpindah ke in_progress, completed, atau failed. Body-nya persis sama dengan yang dikembalikan GET /v1/videos/{task_id} pada saat itu, termasuk metadata.url dan metadata.last_frame_url untuk tugas yang telah selesai.

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "model": "seedance-2.0",
  "usage": {
    "completion_tokens": 120,
    "total_tokens": 120
  },
  "metadata": {
    "url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content"
  },
  "created_at": 1780306574,
  "completed_at": 1780306750
}

Header	Nilai
`X-Flatkey-Event-Id`	`<task_id>:<status>`, misalnya `task_3f9a…e2:completed`. Event yang sama dapat dikirim lebih dari sekali; gunakan header ini untuk mengabaikan duplikat.

Balas dengan status 2xx apa pun dalam 5 detik. Jika tidak, Flatkey mencoba ulang dua kali, setelah 2 dan 8 detik, lalu berhenti. Redirect tidak diikuti. Callback tidak ditandatangani, jadi verifikasi hasilnya dengan memantau tugas sebelum menindaklanjutinya, dan tetap jadikan polling sebagai sumber kebenaran jika ada callback yang hilang.

Unduh video

GET https://router.flatkey.ai/v1/videos/{task_id}/content

curl -L "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content" \
  -o output.mp4

Endpoint konten mengalirkan data video/mp4, atau video/quicktime jika tugas menggunakan output_format: "mov". Endpoint ini tidak memerlukan token Bearer dan dapat digunakan langsung sebagai sumber <video>.

Endpoint konten hanya berfungsi setelah tugas selesai dan dibatasi kecepatannya berdasarkan IP klien. Perlakukan URL sebagai informasi sensitif karena siapa pun yang memilikinya dapat mengunduh video.

Kesalahan

Kesalahan pada saat permintaan menggunakan amplop kesalahan standar Flatkey:

{
  "error": {
    "message": "...",
    "type": "...",
    "code": "..."
  }
}

Skenario	Perilaku
`content` kosong	Permintaan ditolak. Sertakan teks yang tidak kosong, gambar, atau video.
Model tidak tersedia	`model` yang diminta tidak diaktifkan untuk rute tersebut.
Saldo tidak mencukupi	Tugas tidak dibuat.
`priority` di luar 0–9	Permintaan mengembalikan `400` dengan `invalid_request`.
`callback_url` tidak valid	Permintaan mengembalikan `400` dengan `invalid_request` jika URL bukan HTTPS, berisi kredensial, lebih dari 2.048 karakter, atau mengarah ke alamat privat atau lokal.
`duration: -1` di luar pengeditan video `seedance-2.5`	Permintaan mengembalikan `400` dengan `video_price_not_configured`.
Input tidak valid untuk model	Permintaan mengembalikan `400` dengan `fail_to_fetch_task`, atau, untuk permintaan yang menggunakan referensi `asset://`, tugas gagal dengan `task preparation failed`. Periksa resolusi, durasi, batasan konten, dan aturan mode input di atas. Anda tidak dikenai biaya.
Kegagalan layanan sementara	Coba lagi nanti menggunakan kebijakan backoff normal Anda.

Contoh menyeluruh

Contoh ini membuat tugas, memantaunya setiap lima detik, dan mengunduh video yang telah selesai. Membutuhkan jq.

#!/usr/bin/env bash
set -euo pipefail

BASE="https://router.flatkey.ai"
: "${FLATKEY_API_KEY:?Set FLATKEY_API_KEY before running this script}"

RESPONSE=$(curl -sS "$BASE/v1/videos" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      { "type": "text", "text": "An astronaut walking on the moon, cinematic lighting" }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }')

TASK_ID=$(echo "$RESPONSE" | jq -r '.id')
echo "task: $TASK_ID"

while true; do
  RESULT=$(curl -sS "$BASE/v1/videos/$TASK_ID" \
    -H "Authorization: Bearer $FLATKEY_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.status')
  echo "status: $STATUS"

  [ "$STATUS" = "completed" ] && break
  if [ "$STATUS" = "failed" ]; then
    echo "failed: $(echo "$RESULT" | jq -r '.error.message')" >&2
    exit 1
  fi
  sleep 5
done

VIDEO_URL=$(echo "$RESULT" | jq -r '.metadata.url')
curl -L "$VIDEO_URL" -o output.mp4
echo "saved -> output.mp4"

​Endpoint

​Permintaan

​Header

​Parameter body

​Item content

​Pengeditan video

​Mode draf

​Contoh permintaan

​Input frame pertama dan terakhir

​Referensi multimodal

​Respons

​Kolom respons

​Pantau status tugas

​Nilai status

​Callback tugas

​Unduh video

​Kesalahan

​Contoh menyeluruh

Endpoint

Permintaan

Header

Parameter body

Item `content`

Pengeditan video

Mode draf

Contoh permintaan

Input frame pertama dan terakhir

Referensi multimodal

Respons

Kolom respons

Pantau status tugas

Nilai status

Callback tugas

Unduh video

Kesalahan

Contoh menyeluruh