Cara Menggunakan API Seedance 2.5: Panduan Cepat

Anda bisa berpindah dari kunci API ke MP4 jadi dalam empat langkah: kirim permintaan POST yang terautentikasi, simpan request_id, poll endpoint hasil setiap 10 hingga 20 detik, dan unduh video sebelum tautannya kedaluwarsa, sering dalam 24 jam.

Jika saya ingin versi singkatnya, inilah yang akan saya ingat:

• Gunakan endpoint yang tepat
  • seedance-2.5-text-to-video untuk prompt teks
  • seedance-2.5-image-to-video untuk menganimasikan URL gambar publik
• Kirim header yang tepat
  • Authorization: Bearer <API_KEY>
  • Content-Type: application/json
• Pilih pengaturan output utama
  • resolution: 480p hingga 4K
  • aspect_ratio: seperti 16:9 atau 9:16
  • duration: hingga 16 detik
  • generate_audio: true untuk suara dan baris ucapan
• Poll alih-alih mengirim ulang
  • Cek predictions/{request_id}/result
  • Perhatikan queued, running, succeeded, atau failed
• Kendalikan biaya
  • Mulai pada 480p atau 720p
  • Pertahankan seed yang sama
  • Jalankan ulang pada 1080p atau 4K hanya saat shot terlihat benar

Saya juga akan mengawasi titik kegagalan paling umum: 401 dari header auth yang buruk, 402 dari tanpa kredit, 429 dari terlalu banyak job aktif, dan 400 dari JSON buruk atau field yang hilang. Di APIMart, kredit dicadangkan saat job dimulai dan dibebankan hanya jika selesai; job yang gagal dikembalikan.

Jika Anda memilih di antara model, Seedance 2.5 adalah opsi kelas atas dalam lineup ini: hingga 16d, hingga 3.840 × 2.160, dan hingga 50 input referensi. Seedance 2.0 berada di tengah, dan Seedance 2 Mini lebih baik untuk draf berbiaya lebih rendah.

Intinya: jika Anda bisa membuat permintaan POST yang valid dan menyimpan satu ID, Anda bisa menjalankan seluruh alur kerja. Sisanya adalah penyetelan prompt, polling yang sabar, dan mengunduh file sebelum URL kehabisan waktu. Untuk pasca-pemrosesan, Anda dapat menggunakan AI Canvas untuk meningkatkan atau mengedit klip yang Anda hasilkan.

Langkah 1: Siapkan Akses APIMart dan Autentikasi Permintaan

Setiap permintaan Seedance 2.5 butuh kunci API yang valid dan header yang tepat. Mulai dari situ. Setelah itu tersedia, Anda dapat beralih ke payload pembuatan video dan pelacakan job.

Buat dan Simpan Kunci API Anda dengan Aman

Buat kunci Anda di dasbor akun di bawah Settings atau API Keys. Lalu simpan di file .env atau variabel lingkungan, bukan di source control ^[6][8].

export APIMART_API_KEY="sk_live_xxxxxx"

Jika kunci hilang, cabut dan buat yang baru ^[3]. Untuk pengujian integrasi, gunakan kunci sk_test_ terpisah agar Anda tidak menyentuh penggunaan produksi ^[3].

Berikutnya, sertakan kunci itu di setiap permintaan dengan header Authorization.

Tambahkan Header Authorization dengan Benar

Kirim permintaan ke https://muapi.ai/api/v1/ dengan header ini:

• Authorization: Bearer sk_live_xxxxxx
• Content-Type: application/json

Satu kesalahan format kecil dapat merusak permintaan. Yang paling umum adalah menghilangkan prefiks Bearer, atau melewatkan spasi sebelum kunci ^[3][7]. Itu biasanya menghasilkan respons 401 Unauthorized. Menghilangkan Content-Type: application/json juga dapat membuat permintaan gagal ^[3][7].

Dengan auth diatur, Anda dapat beralih ke payload permintaan video.

Langkah 2: Bangun Permintaan Pembuatan Video Seedance 2.5

Dengan kunci API Anda tersiapkan, langkah berikutnya adalah membangun body permintaan yang valid. Setiap job Seedance 2.5 dimulai dengan permintaan POST ke salah satu dari dua endpoint, berdasarkan apa yang Anda mulai. Gunakan https://muapi.ai/api/v1/seedance-2.5-text-to-video untuk pembuatan hanya-prompt, atau https://muapi.ai/api/v1/seedance-2.5-image-to-video jika Anda menganimasikan gambar sumber ^[1].

Pilih Mode Input dan Parameter yang Tepat

Mode input Anda menentukan bentuk payload. Text-to-video hanya butuh prompt. Image-to-video juga butuh image_url yang menunjuk ke file JPG, PNG, atau WEBP yang dapat dijangkau publik di bawah 10 MB ^[1].

Dari sana, Anda mengendalikan output dengan beberapa field utama:

• resolution: 480p, 720p, 1080p, atau 4K
• aspect_ratio: 16:9, 9:16, 1:1, 4:3, 3:4, atau 21:9
• duration: hingga 16 detik di Muapi
• generate_audio: boolean yang mengaktifkan suara ambient tersinkron, efek, dan dialog ketika diatur ke true ^[1]

Cara cerdas untuk bekerja adalah mulai pada 480p dengan seed tetap. Jika gerakan, pacing, dan framing terlihat benar, jalankan seed yang sama itu lagi pada 1080p atau 4K untuk versi final.

Untuk prompt, gunakan alur ini: Subject → Action → Camera → Setting → Mood ^[4]. Jaga gerakan, arah kamera, dan mood di dalam prompt itu sendiri, dan biarkan seed tidak berubah selagi Anda menguji variasi. Jika Anda butuh lip-sync, tempatkan baris ucapan dalam tanda kutip ganda tepat di dalam string prompt. Contohnya: she turns and says "We launch at dawn." Dalam kasus itu, pastikan generate_audio diatur ke true ^[1].

Setelah payload terlihat baik, kirim job dan simpan request ID yang dikembalikan. Anda akan membutuhkannya untuk polling.

Contoh Permintaan dalam cURL, Postman, Python, dan JavaScript

Di bawah ini adalah payload text-to-video yang sama ditampilkan dalam empat alat umum.

cURL

curl -X POST https://muapi.ai/api/v1/seedance-2.5-text-to-video \
  -H "Authorization: Bearer $APIMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 8,
    "generate_audio": true,
    "seed": 42
  }'

Postman - Buat permintaan POST baru, tempel URL endpoint, tambahkan Authorization: Bearer <your_key> dan Content-Type: application/json di tab Headers, lalu tempel JSON di atas ke Body → raw → JSON. Klik Send dan simpan request_id dari respons.

Python

import os, requests

payload = {
    "prompt": "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 8,
    "generate_audio": True,
    "seed": 42
}

response = requests.post(
    "https://muapi.ai/api/v1/seedance-2.5-text-to-video",
    headers={
        "Authorization": f"Bearer {os.environ['APIMART_API_KEY']}",
        "Content-Type": "application/json"
    },
    json=payload
)

print(response.json())  # save request_id here

JavaScript (fetch)

const response = await fetch("https://muapi.ai/api/v1/seedance-2.5-text-to-video", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.APIMART_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    aspect_ratio: "16:9",
    resolution: "1080p",
    duration: 8,
    generate_audio: true,
    seed: 42
  })
});

const data = await response.json();
console.log(data.request_id); // use this to poll for results

Beberapa kesalahan dapat menjatuhkan Anda dengan cepat. Jangan kirim image_url yang tidak dapat dijangkau publik. Jangan tumpuk arah kamera yang saling bertentangan dalam prompt yang sama. Dan dalam mode image-to-video, jangan deskripsikan subjek lagi jika gambar sumber sudah mendefinisikannya ^[1].

Setelah pengiriman, poll status job hingga URL MP4 siap.

Kapan Menggunakan Seedance 2.5 dalam Lineup Model Video APIMart

Perbandingan singkat ini membantu Anda memilih model yang tepat sebelum Anda mulai menyetel prompt atau menaikkan resolusi. Seedance 2.5 memberi Anda 4K native, hingga 50 input referensi, dan dukungan klip lebih panjang. Seedance 2 Mini lebih baik untuk draf ringan, sementara Seedance 2.0 berada di tengah sebagai opsi penggunaan umum ^[1][9][4].

Jika proyek adalah pengiriman final - seperti video peluncuran produk, urutan sinematik bermerek, atau apa pun yang menuju siaran - Seedance 2.5 adalah pilihan lebih baik. Untuk proyek yang membutuhkan 高品質音声付きAI動画生成, Veo 3.1 dari Google adalah pesaing kuat lain. Jika Anda masih menguji ide, mulai dengan Mini untuk mengecek gerakan dan mengunci framing dengan biaya lebih rendah, lalu naik ke 2.5 untuk render final.

Langkah 3: Kirim Job, Lacak Status, dan Baca Respons

Setelah Anda mengirim permintaan POST, API mengembalikan request_id. Simpan. Anda akan menggunakan ID itu untuk mengecek job nanti karena pembuatan berjalan secara asinkron.

Tangani Job Async dari Pembuatan hingga Penyelesaian

Setelah Anda mengirim job, langkah berikutnya sederhana: poll hingga video final siap.

Kirim permintaan GET ke https://muapi.ai/api/v1/predictions/{request_id}/result. Tunggu sekitar 10 detik setelah pengiriman sebelum poll pertama, lalu cek lagi setiap 10–20 detik. Jika Anda poll lebih sering dari setiap 5 detik, Anda mungkin terkena batas laju ^[1][3].

Setiap respons mencakup field status. Field itu memberi tahu Anda apa yang terjadi dan apa yang harus Anda lakukan berikutnya:

Setelah job mencapai succeeded, ambil URL output sebelum kedaluwarsa.

Baca Field Output dan Simpan Hasil

Ketika status berubah ke succeeded, baca payload output dan simpan hasilnya.

Respons yang berhasil mencakup video_url. Ia mungkin juga mencakup last_frame_url jika Anda memintanya. Simpan video_url, last_frame_url opsional, dan metadata seperti seed, duration, resolution, aspect_ratio, dan usage. Data itu penting untuk penagihan dan untuk mereproduksi run yang sama nanti ^[11][13].

URL output sering kedaluwarsa dalam 24 jam, jadi unduh file ke penyimpanan Anda sendiri segera ^[11][12][13]. Jika job gagal, catat error.code dan error.message. Dan jika kegagalan terkait dengan pemeriksaan keamanan, jangan coba ulang secara otomatis ^[2][11][12].

Langkah 4: Atasi Error, Kendalikan Biaya, dan Selesaikan

Perbaiki Error Autentikasi, Validasi, dan Batas Laju

Setelah Anda mengirim job dan poll hasil, beberapa pengecekan sederhana dapat menjaga run produksi dari kekacauan. Sebagian besar kegagalan Seedance cenderung muncul dalam segelintir cara yang sama.

Untuk aset referensi, pastikan URL bersifat publik, file adalah JPG, PNG, atau WEBP, dan tetap di bawah batas ukuran yang tercantum ^[12][4].

Pangkas Biaya dan Tingkatkan Keandalan

Setelah penanganan error diatur, langkah berikutnya sederhana: uji murah, lalu render besar.

Mulai prompt Anda pada 480p atau 720p. Itu memberi Anda cara berbiaya rendah untuk mengecek framing, gerakan, dan apakah prompt melakukan apa yang Anda inginkan. Jika shot terlihat benar, jalankan ulang nilai seed yang sama pada 4K untuk output final ^[1][4].

Panjang klip juga penting. Video lebih pendek berbiaya lebih rendah, jadi jaga durasi ke minimum yang tetap menyelesaikan tugas ^[1][10].

Ada juga cara terselubung tim membakar uang: pengiriman duplikat setelah timeout jaringan. Satu perbaikan bersih adalah meng-hash prompt, ID model, dan URL media sebelum setiap permintaan POST. Jika hash itu sudah memetakan ke ID tugas, lewati pengiriman baru sama sekali ^[11]. Dan setelah job mencapai succeeded, simpan file jadi ke penyimpanan tahan lama agar Anda tidak perlu bergantung pada catatan tugas nanti ^[12][11].

Kesimpulan: Dari Dokumen API ke Pembuatan Video yang Bekerja

Dengan auth, payload, polling, dan penanganan error tersedia, Anda kini memiliki alur kerja Seedance 2.5 penuh di APIMart.

FAQ

Berapa lama Seedance 2.5 menyelesaikan sebuah video?

Seedance 2.5 dapat menghasilkan satu klip video kontinu hingga 30 detik panjangnya. Namun, dokumen tidak mencantumkan waktu selesai yang tepat.

API berjalan secara asinkron. Anda mengirim tugas, mendapat ID tugas, lalu baik poll endpoint status atau menunggu webhook untuk mendapatkan video jadi.

Waktu pemrosesan dapat bervariasi berdasarkan hal-hal seperti resolusi dan kompleksitas adegan.

Apa yang harus saya lakukan jika URL video saya kedaluwarsa sebelum saya mengunduhnya?

Jika URL video Anda kedaluwarsa sebelum Anda mengunduhnya, Anda tidak akan bisa mendapatkan file dari tautan itu. Seedance menjaga URL sementara ini aktif selama 24 jam.

Langkah aman itu sederhana: salin video ke penyimpanan objek aman Anda sendiri segera setelah tugas menunjukkan selesai. Karena API berjalan secara asinkron dan tidak menyimpan output selamanya, aplikasi Anda harus mengambil video dan memindahkannya ke penyimpanan jangka panjang segera.

Bagaimana saya bisa menghindari biaya duplikat saat mencoba ulang permintaan yang gagal?

Gunakan penanganan permintaan idempoten yang terikat pada catatan job tahan lama Anda sendiri, bukan hanya klien HTTP.

Sebelum Anda mengirim apa pun, bangun hash permintaan deterministik dari input seperti prompt, ID model, ID aset, dan pengenal pengguna. Lalu simpan hash itu dengan status submitting di database Anda sendiri.

Jika hash yang sama itu muncul lagi, kembalikan job yang ada alih-alih membuat yang baru.

Setelah Anda menyimpan ID job penyedia, jangan kirim permintaan lagi. Cukup lanjutkan polling dengan ID job itu.