API pembuatan video
Cara membuat video melalui /videos: mulai tugas, pantau statusnya, unduh file-nya. Field request, file referensi, draf, dan cara video ditagih.
Video
Model video berjalan sebagai tugas. POST /videos memulai tugas dan langsung mengembalikan id-nya; polling GET /videos/{id} setiap beberapa detik hingga status menjadi completed atau failed (biasanya 1 sampai 5 menit), lalu unduh: tugas yang selesai membawa url (tautan ke file, berlaku selama seminggu dan diperbarui setiap kali dibaca; jika kami tidak dapat menyimpan file, url berisi path /v1/videos/{id}/content), dan GET /videos/{id}/content selalu mengambil file tersebut. id dari response apa pun (chatcmpl-…, img_…, video_…) dan request_id dari error apa pun adalah yang perlu Anda sampaikan ke tim dukungan.
| Field | Tipe | |
|---|---|---|
model | string | Wajib. Id model video. |
prompt | string | Wajib (kecuali dengan draft_id). 3 sampai 20.000 karakter. |
seconds | integer | "auto" | Durasi (duration diterima sebagai field yang sama). Seedance 2.5: 4 sampai 30; Seedance 2.0: 4 sampai 15. "auto" membiarkan model memilih; durasi terpanjang dicadangkan dan Anda membayar sesuai yang dihasilkan. Default 5; dengan reference_videos default-nya "auto". |
resolution | string | 480p, 720p (default), 1080p, atau 4k; hanya resolusi yang ditawarkan model (lihat referensi model). |
ratio | string | 16:9 (default), 9:16, 1:1, 4:3, 3:4, 21:9, atau adaptive. Dengan reference_videos default-nya mengikuti video input. |
image | string | Frame pertama: tautan gambar atau data URL (first_frame diterima sebagai field yang sama). |
last_frame | string | Frame terakhir, digunakan bersama image. |
audio | boolean | Hasilkan suara bersama video. Default true. |
seed | integer | -1 untuk seed acak (default), atau bilangan bulat dari 1 sampai 4294967295 untuk mengulang hasil pada model yang sama. Jawaban menampilkan seed yang Anda kirim, atau -1 jika acak. |
camera_fixed | boolean | true membuat kamera tetap diam. |
bitrate_mode | string | standard (default) atau high. high dapat gagal saat model sedang sibuk; dalam hal itu biayanya dikembalikan. |
return_last_frame | boolean | true: frame terakhir disimpan sebagai gambar di GET /videos/{id}/last_frame. |
reference_images | string[] | Tautan gambar atau data URL: hingga 30 pada Seedance 2.5, 9 pada Seedance 2.0 (jpeg, png, webp, bmp, tiff, gif; hingga 30 MB; setiap sisi 300 sampai 6000 px). |
reference_videos | string[] | Tautan MP4/MOV publik: hingga 10 pada Seedance 2.5, 3 pada Seedance 2.0; masing-masing 2 sampai 15 detik, 480p atau 720p, hingga 50 MB. Durasinya juga ditagih. |
reference_audios | string[] | Tautan WAV/MP3 publik: hingga 10 pada Seedance 2.5, 3 pada Seedance 2.0; masing-masing 2 sampai 15 detik, hingga 15 MB. |
task_type | string | Dengan reference_videos: auto, reference, edit, atau extend (Seedance 2.5). edit dan extend mengikuti video input; jangan kirim seconds dan ratio. |
draft | boolean | Seedance 2.5: true membuat pratinjau 480p dengan harga 480p. resolution harus 480p. |
draft_id | string | Menjadikan draf yang sudah selesai sebagai video final 1080p. Kirim hanya model dan draft_id: prompt, referensi, durasi, rasio, audio, dan seed diambil dari draf. Draf berlaku selama 7 hari. |
Referensi diberi nomor per jenis sesuai urutan pengiriman: entri pertama reference_images adalah gambar 1, yang kedua gambar 2, dan begitu pula untuk video dan audio. Sebut dengan cara itu di prompt, seperti yang dilakukan playground dengan [Image 1], [Video 1], dan [Audio 1], misalnya "The woman in [Image 1] walks through the street of [Video 1]". Mengirim lebih banyak file daripada yang diterima model akan ditolak, bukan dipotong.
status bernilai queued, in_progress, completed, atau failed. Tugas yang selesai memiliki usage.video_tokens dan usage.cost_usd; tugas yang gagal tidak ditagih dan memiliki error.code dan error.message: generation_failed (model tidak dapat membuat video), invalid_reference (salah satu file referensi ditolak; pesan menyebutkan yang mana), upstream_rate_limited (semua pemasok sedang sibuk, juga setelah tugas menunggu 30 detik; mulai lagi dalam satu menit) atau timeout.
// GET https://api.apistore.cloud/v1/videos/video_...
{
"id": "video_0123456789abcdef0123456789abcdef",
"object": "video",
"model": "MODEL_NAME",
"status": "completed",
"created_at": 1793984023,
"completed_at": 1793984214,
"prompt": "A red paper boat drifting across a calm lake at sunrise",
"resolution": "720p",
"ratio": "16:9",
"seconds": 5,
"draft": false,
"seed": 49873,
"url": "https://.../video_0123456789abcdef0123456789abcdef.mp4",
"last_frame": null,
"error": null,
"usage": { "video_tokens": 108000, "cost_usd": 1.0978 }
}Draf (Seedance 2.5): buat pratinjau 480p yang murah terlebih dahulu, lalu ubah yang Anda sukai menjadi video final 1080p dengan seed dan pengaturan yang sama.
# 1. the draft: 480p, at the 480p price
curl https://api.apistore.cloud/v1/videos -H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
-d '{"model": "MODEL_NAME", "prompt": "A red paper boat on a lake", "seconds": 5, "resolution": "480p", "draft": true}'
# 2. when it is completed, the final video at 1080p
curl https://api.apistore.cloud/v1/videos -H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
-d '{"model": "MODEL_NAME", "draft_id": "video_..."}'Perkiraan biaya ditahan dari saldo Anda saat tugas dimulai: (detik video input + detik output) dalam token video dengan harga untuk resolusi tersebut. Setelah selesai, Anda membayar token yang benar-benar dihasilkan (sekitar 108K untuk 5 detik pada 720p) dan sisanya dilepaskan; tugas yang gagal tidak dikenai biaya. Di Pengaturan, Anda dapat mengganti penagihan video dari daftar harga token ke "by usd": tagihan pemasok sendiri untuk pekerjaan tersebut dengan harga daftar, dikurangi diskon Anda. Setiap catatan penagihan menunjukkan mana yang diterapkan.
Panduan model
Keunggulan setiap keluarga model video, batasannya, dan cara menulis prompt yang diikuti oleh model.
Seedance 2.5
Model untuk video panjang: hingga 30 detik dalam satu tugas, banyak file referensi, serta pengeditan atau perpanjangan video yang sudah ada. Model ini menulis dan berbicara dalam 11 bahasa, termasuk bahasa Vietnam dan Inggris.
| Sekilas | |
|---|---|
| Durasi | 4 sampai 30 detik, atau "auto" agar model yang memilih |
| Resolusi | 480p, 720p, 1080p |
| Rasio | 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, atau adaptive (mengikuti input) |
| Mode | Teks ke video; frame pertama atau frame pertama dan terakhir; referensi; edit video; perpanjang video |
| Referensi | Hingga 30 gambar, 10 video, dan 10 audio. Audio saja juga diterima |
| Suara | Ucapan, musik, dan efek dihasilkan bersama gambar (audio: true) |
| Draf | Ya: pratinjau 480p terlebih dahulu, lalu video final dari yang Anda sukai |
Menulis prompt
- Mulai dengan satu kalimat. Sebutkan siapa, di mana, apa yang terjadi, gaya, dan kamera dalam satu baris. Lalu tambahkan detailnya di bawahnya.
- Ikat setiap referensi. Sebut setiap file dengan nomornya dan jelaskan fungsinya: "[Image 1] is the lead actress, [Image 2] is the cafe, follow the camera of [Video 1]". Jangan mengandalkan teks yang tertulis di dalam gambar untuk menyatakan siapa seseorang.
- Gunakan timeline untuk video panjang. Bagi cerita menjadi rentang detik bulat tanpa celah ("0-5 s", "5-12 s") atau menjadi shot bernomor, dan beri masing-masing gambar, kamera, aksi, ucapan, dan suaranya. Terlalu sedikit per rentang membuat model berimprovisasi; terlalu banyak membuatnya terlalu sering memotong adegan.
- Batasi jumlah subjek. Satu sampai lima subjek paling konsisten. Beberapa sudut pandang dari subjek yang sama boleh dijadikan referensi hingga lima subjek; lebih dari itu, kirim satu sudut pandang untuk masing-masing.
- Mengedit (task_type: edit). Sebutkan apa yang berubah dan di mana, dari apa menjadi apa, beserta detiknya jika hanya sebagian yang berubah: "In [Video 1], from second 4 to 6 she waves instead of nodding; everything else stays". Hasilnya mempertahankan durasi dan rasio input, jadi jangan kirim seconds dan ratio. Video di bawah 20 detik paling baik untuk diedit.
- Memperpanjang (task_type: extend). Sebutkan arahnya dan apa yang terjadi selanjutnya: "Extend [Video 1] forward: she opens the door and walks into the rain". Rasio mengikuti video input.
- Frame pertama dan terakhir. Kirim sebagai image dan last_frame, dengan proporsi yang sama, agar video dimulai dan berakhir tepat di sana. Gambar referensi yang disebut sebagai "the first frame" di prompt diikuti dengan kurang ketat.
- Storyboard dan keyframe. Lembar storyboard (15 panel atau kurang, gambar garis sederhana, tanpa teks) memandu alur cerita tetapi tidak diikuti panel demi panel. Untuk frame yang ketat, kirim gambar terpisah dan awali dengan "Use Images 1 to 5 in order as keyframes".
- Kamera. Istilah film yang umum berfungsi apa adanya: push in, pan, tracking shot, orbit, handheld, low angle, long take. Jelaskan istilah yang jarang dalam beberapa kata, dan sebutkan kapan transisi terjadi selain bagaimana caranya.
- Apa yang tidak perlu ditulis. Tulis apa yang Anda inginkan, bukan apa yang tidak Anda inginkan. Dua pengecualian yang berfungsi baik: "No subtitles" dan "No background music, only ambient sound".
- Ucapan. Tulis dialog sebagai: nama, suasana hati dalam tanda kurung, lalu kata-katanya. Gunakan satu bahasa per baris. Untuk kata yang harus dieja persis di layar, kirim sebagai gambar.
[Image 1] is the fisherman, [Image 2] is his boat. Documentary style, natural light. 0-6 s: wide shot at water level, the boat drifts through morning mist. Slow push in. 6-14 s: medium shot, he pulls the net in, hand over hand. Water drips from the rope. 14-20 s: close-up on his face as he looks at the catch and smiles. Ambient sound only: water, wood, gulls. No subtitles, no background music.
Seedance 2.0
Tiga model yang menerima request yang sama dan berbeda dalam kualitas, kecepatan, dan harga: Seedance 2.0 untuk gambar terbaik, Seedance 2.0 fast untuk keseimbangan kecepatan dan biaya, Seedance 2.0 mini untuk harga terendah.
| Sekilas | |
|---|---|
| Durasi | 4 sampai 15 detik, atau "auto" |
| Resolusi | Seedance 2.0: 480p, 720p, 1080p, 4K. Fast dan mini: 480p, 720p |
| Rasio | 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 |
| Mode | Teks ke video; frame pertama atau frame pertama dan terakhir; referensi; edit atau perpanjang video melalui prompt |
| Referensi | Hingga 9 gambar, 3 video, dan 3 audio. Audio harus disertai gambar atau video |
| Suara | Ucapan, musik, dan efek dihasilkan bersama gambar (audio: true) |
| Draf | Tidak |
| File 4K | H.265 dengan warna 10-bit. Beberapa pemutar tidak dapat membukanya; VLC, serta Chrome, Edge, dan Safari versi terbaru dapat membukanya |
| Wajah | Gambar dan video referensi yang menampilkan wajah orang sungguhan akan ditolak |
Menulis prompt
- Rumusnya. Subjek, aksi, tempat, cahaya dan warna, kamera, gaya, kualitas, lalu apa yang harus dihindari. Tentukan dulu siapa melakukan apa, lalu di mana, lalu bagaimana pengambilan gambarnya.
- Definisikan setiap subjek sekali. Berikan dua atau tiga ciri tetap (pakaian, rambut, postur) dan sebuah label, lalu gunakan label yang sama setiap kali: "The girl in the red coat from [Image 1]".
- Tulis shot, bukan detik. Beri nomor pada shot: "Shot 1: ... Shot 2: ...", masing-masing dengan kamera, aksi, tempat, dan suaranya. Waktu yang persis seperti "0-3 s" tidak dipatuhi secara andal pada model ini.
- Satu gerakan kamera per shot. Push in, atau pan, atau track. Menggabungkan beberapa gerakan dalam satu shot membuat hasilnya tidak stabil.
- Gambarkan gerakan secara fisik. Sebutkan bagian tubuh, seberapa jauh, seberapa cepat. Gerakan yang lambat dan berkesinambungan paling baik hasilnya. Tunjukkan perasaan melalui tubuh ("lowers her head, eyes reddening") alih-alih menyebutkannya.
- Gunakan sedikit referensi. Empat atau lima sudah cukup: satu atau dua untuk karakter, satu untuk tempat, satu video untuk kamera, satu audio untuk suasana. Lebih dari empat orang sebagai referensi mengurangi stabilitas, dan beberapa sudut pandang dari satu orang tidak disarankan.
- Wajah yang konsisten. Kirim close-up kepala dan gambar seluruh tubuh, lalu sebutkan mana yang untuk wajah dan mana yang untuk pakaian. Letakkan file yang paling penting di urutan pertama.
- Mengedit. Sebut videonya secara langsung dan jelaskan apa yang berubah: "Strictly edit [Video 1]: replace the cat with the lion from [Image 1], keep everything else". Jangan menulis "reference [Video 1]" di sini, karena video itu akan diperlakukan hanya sebagai referensi.
- Memperpanjang. "Extend [Video 1] forward" atau "backward", lalu apa yang terjadi. Dua atau tiga klip dapat digabungkan dengan transisi di antaranya, total 15 detik. Tambahkan "end with [Video 1]" untuk mempertahankan rekaman asli di hasilnya.
- Ucapan dan teks. Letakkan dialog di dalam kurung kurawal dan gunakan satu bahasa di seluruhnya: She says {We are late}. Untuk teks di layar, sebutkan kata-katanya, kapan, di mana, dan bagaimana teks itu muncul. Gunakan karakter yang umum.
- Apa yang harus dihindari. Subtitle dan logo masih dapat muncul. "Keep it subtitle-free" dan "Do not generate a logo or watermark" menguranginya; begitu juga menghapus teks dari file referensi Anda.
[Image 1] is the girl in the red coat, [Image 2] is the night market. Follow the camera of [Video 1].
Shot 1: wide shot, she walks in between the stalls. Slow push in.
Shot 2: medium shot, she stops at a lantern stall and lifts one lantern. Fixed camera.
Shot 3: close-up, warm light on her face. She says {This one}.
Cinematic, warm tones, rich detail. Keep it subtitle-free. Do not generate a logo or watermark.