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 meliputi seedance-2.0 dan seedance-2.0-fast. 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. Gunakan "seedance-2.0" atau "seedance-2.0-fast".

array

wajib

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

string

Resolusi output: "480p", "720p", atau "1080p".

string

Rasio aspek output: "16:9", "4:3", "1:1", "3:4", "9:16", "21:9", atau "adaptive".

integer

Durasi video dari 4 hingga 15 detik. Gunakan -1 untuk membiarkan model memilih.

integer

Seed acak. Hilangkan untuk menggunakan seed acak.

boolean

Apakah akan menambahkan tanda air. Default: false.

boolean

Apakah akan menghasilkan audio yang tersinkronisasi.

Item `content`

`type`	Kolom nilai	`role` yang didukung	Tujuan
`text`	`text`	—	Prompt teks. Beberapa item teks digabungkan secara berurutan.
`image_url`	`image_url.url`	`first_frame`, `last_frame`, `reference_image`	Gambar input atau referensi. Hingga 9 gambar.
`video_url`	`video_url.url`	`reference_video`	Video referensi. Hingga 3 video.
`audio_url`	`audio_url.url`	`reference_audio`	Audio referensi. Hingga 3 klip.

Jika sebuah gambar menggunakan peran first_frame atau last_frame, API menggunakan mode frame pertama/terakhir. Gambar lainnya diperlakukan sebagai referensi.

Parameter lanjutan

string

Mode input eksplisit: "reference" atau "first_last_frame". Hilangkan untuk menyimpulkan mode dari content.

boolean

Aktifkan augmentasi pencarian web untuk tugas tersebut.

object

Tingkatkan resolusi video yang dihasilkan sambil mempertahankan ID tugas publik yang sama.

Tampilkan kolom super_resolution_config

string

Resolusi target: "720p", "1080p", "2k", atau "4k". Harus melebihi resolusi asli dan tidak dapat digabungkan dengan resolution_limit.

integer

Batas piksel sisi pendek kustom dari 64 hingga 2160. Tidak dapat digabungkan dengan resolution.

string

Skenario peningkatan resolusi: "aigc", "short_series", "ugc", atau "old_film".

string

Mode peningkatan resolusi: "standard" (default) atau "professional".

integer

Frame rate output dari 1 hingga 120. Nilai di atas frame rate sumber mengaktifkan interpolasi frame.

camera_fixed, frames, callback_url, dan return_last_frame diterima untuk kompatibilitas tetapi saat ini tidak memiliki efek.

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
}

Referensi multimodal dengan peningkatan resolusi

{
  "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,
  "super_resolution_config": {
    "resolution": "4k",
    "scene": "aigc",
    "tool_version": "professional",
    "fps": 60
  }
}

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"
  },
  "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": "video_generation_failed"
  }
}

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.

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. 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.
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

​Parameter lanjutan

​Contoh permintaan

​Input frame pertama dan terakhir

​Referensi multimodal dengan peningkatan resolusi

​Respons

​Kolom respons

​Pantau status tugas

​Nilai status

​Unduh video

​Kesalahan

​Contoh menyeluruh

Endpoint

Permintaan

Header

Parameter body

Item `content`

Parameter lanjutan

Contoh permintaan

Input frame pertama dan terakhir

Referensi multimodal dengan peningkatan resolusi

Respons

Kolom respons

Pantau status tugas

Nilai status

Unduh video

Kesalahan

Contoh menyeluruh