Quickstart
Satu kunci, satu bentuk request, semua model gambar dan video. Kirim job, polling, dapatkan filenya.
/data/models.json.POST /v1/chat/completions yang kompatibel dengan OpenAI, ditagih per token dari kredit yang sama: lihat chat completions.| Base URL | https://api.revana.si/v1 |
| Autentikasi | Authorization: Bearer <key> |
| Submit | POST /v1/generations |
| Polling | GET /v1/generations/{id} |
| Model | GET /v1/models (tanpa kunci): semua model yang bisa Anda pakai untuk generate saat ini |
| Saldo | GET /v1/balance: yang bisa dibelanjakan akun milik kunci Anda |
| Unggah | POST /v1/uploads: tautan untuk file referensi di komputer Anda |
| Format | JSON masuk, JSON keluar. Harga dalam USD; 100 kredit = $1. |
| Dapat dibaca mesin | /openapi.json · /llms.txt |
Autentikasi
Buat kunci dari akun Anda, lalu kirim sebagai bearer token di setiap request. Simpan di server Anda; jangan pernah disertakan di browser atau aplikasi seluler.
Mengirim generasi
Kirim id model dan input-nya. Respons kembali langsung dengan id generasi dan status queued; pekerjaannya berjalan di latar belakang.
| Field | Tipe | Deskripsi |
|---|---|---|
model | string, wajib | Id model dari halaman model, mis. seedance-2.5. |
input | object, wajib | Prompt dan pengaturan; lihat field input. Field yang tidak dikenal ditolak. |
max_cost_usd | number, opsional | Jumlah maksimum yang akan Anda bayar untuk generasi ini, hingga 100 (default). Rute dengan harga di atasnya dilewati; jika tidak ada yang tersisa, request dijawab dengan 422 max_cost_exceeded. |
max_wait_s | integer, opsional | Rute yang diperkirakan memakan waktu lebih dari sekian detik dilewati. Setelah lewat, tidak ada rute baru yang dicoba, tetapi rute yang sudah berjalan boleh selesai (hingga 40 menit) dan ditagih jika berhasil mengirim hasil. |
Idempotency-Key | header, opsional | Hingga 200 karakter. Kirim kunci dan body yang sama lagi (setelah timeout atau 503) dan Anda mendapat generasi yang sama, bukan generasi kedua. Kunci yang sama dengan body berbeda menghasilkan 409 idempotency_conflict. |
Mengambil hasil
Lebih suka endpoint per model dan webhook penyelesaian? Lihat API antrean yang kompatibel dengan fal untuk ID request, URL status/hasil, alias fal yang didukung, dan batas migrasi.
Lakukan polling setiap beberapa detik sampai status berstatus succeeded atau failed, lalu unduh file di output.urls dengan kunci Anda: GET /v1/generations/{id}/content untuk yang pertama, dan /content/2, /content/3… saat model gambar mengembalikan beberapa. Gambar biasanya memakan waktu beberapa detik; video memakan waktu dari kurang dari semenit hingga beberapa menit tergantung model dan durasi.
Generasi yang selesai:
Field input
Nama yang sama dipakai di semua model. Field dan nilai yang diterima setiap model, beserta default-nya, tercantum per model di /data/models.json (options, tasks). Jika model tidak mendukung suatu field atau nilai, request ditolak dengan 422 invalid_input sebelum ada yang ditagih.
| Field | Tipe | Dipakai untuk |
|---|---|---|
prompt | string | Apa yang akan di-generate. Wajib untuk text-to-image dan text-to-video. |
image_url | string (URL) | Frame awal untuk image-to-video, atau gambar yang akan diedit untuk image-to-image. |
end_image_url | string (URL) | Frame akhir, untuk model dengan frame pertama + terakhir. |
image_urls | string[] | Gambar referensi, hingga batas model. |
resolution | string | 720p, 1080p, 2K... salah satu resolusi model. |
duration | number | Durasi video dalam detik, salah satu durasi model. |
aspect_ratio | string | 16:9, 9:16, 1:1... |
audio | boolean | Hasilkan suara bersama video, jika model mendukungnya. Dapat mengubah harga. |
negative_prompt | string | Apa yang dihindari, pada model yang menerimanya. |
video_url | string (URL) | Klip untuk ditransformasi, diperpanjang, atau di-upscale. Durasinya diukur dan, pada model per detik, ditagih. |
audio_url | string (URL) | Suara atau bunyi yang dianimasikan oleh model talking-avatar atau lip-sync. |
quality | string | Tier kualitas pada model yang harganya ditentukan olehnya (mis. low, medium, high). |
seed | integer | Seed, pada model yang menerimanya. |
Seedance 2.5 secara default memakai 720p, 5 detik (4–30), 16:9 dan tanpa suara, dan juga menerima:
| Field | Tipe | Dipakai untuk |
|---|---|---|
video_url | string (URL) | Klip 4–30 d untuk diedit. Hasilnya mempertahankan durasinya, jadi hilangkan duration. |
video_urls | string[] | Klip referensi, hingga 10 dan total 30 detik. Detiknya ditagih dengan tarif input video. |
audio_urls | string[] | Suara referensi, hingga 10 dan total 30 detik. |
image_url adalah frame pertama yang persis, jadi tidak bisa digabungkan dengan media referensi; gunakan image_urls untuk referensi visual yang lebih longgar. end_image_url membutuhkan image_url. Media harus berupa URL https publik yang bisa diunduh langsung.
Nemesis
nemesis menampilkan ulang klip dengan orang, produk, dan tempat milik Anda sendiri: gerakan, timing, dan kamera klip, diperankan oleh hingga 8 gambar referensi. Hasilnya mempertahankan durasi dan bentuk klip. Harganya sebesar tarif edit Seedance 2.5 ditambah $0.02 per detik ($0.08, $0.17, dan $0.36 pada 480p, 720p, dan 1080p), per detik klip masuk ditambah video keluar.
Ini mengikuti resep Scenario ALTER: klip Anda sendiri yang diedit, tanpa suara, dengan satu frame-nya digambar ulang dengan perubahan yang sudah diterapkan sebagai referensi pertama, dan suara asli klip dipasang kembali setelahnya. Jika ada lebih dari satu orang, gambar dicocokkan dari kiri ke kanan sesuai posisi orang di frame pertama.
| Field | Tipe | Dipakai untuk |
|---|---|---|
video_url | string (URL), wajib | Klip 4–30 d yang akan ditampilkan ulang. |
image_urls | string[], wajib | 1–8 gambar referensi. |
roles | string[] | Satu per gambar: person (default), product, location, atau look. |
target_frame | boolean | Sebelum render, frame pertama klip digambar ulang dengan perubahan yang sudah diterapkan, dalam pose, ukuran, dan cahaya yang sama, lalu dikirim sebagai referensi pertama, sehingga rambut, wajah, dan pakaian tetap setia pada gambar Anda. Aktif secara default untuk nemesis, nonaktif untuk nemesis-lite. Gratis. |
guide | string | nemesis-lite saja (nemesis selalu mengedit klip itu sendiri). clip (default dengan frame target): mengikuti gambar klip itu sendiri. people (default tanpa frame target): orangnya diganti dan latar dipertahankan. scene: semua yang terlihat berasal dari referensi dan prompt. |
sound | string | original (default aktif pada nemesis): suara asli klip dipasang kembali. none (default pada nemesis-lite): tanpa suara. |
face_mesh | boolean | nemesis-lite saja. Melacak setiap wajah di klip agar wajah baru mempertahankan ekspresi, mata, dan bibirnya. Aktif secara default dengan guide: "people", nonaktif untuk scene dan clip. Kirim false untuk menonaktifkannya. Tidak pernah ditampilkan di hasil. |
resolution | string | 480p, 720p (default) atau 1080p. |
prompt | string | Arahan opsional, hingga 5000 karakter. |
Pada nemesis-lite, klip tanpa seorang pun di dalamnya, yang dikirim dengan guide: "people", ditolak dengan invalid_input dan tidak ditagih; kirim dengan scene atau clip.
Berapa lama waktunya. Pertama klip disiapkan: pada nemesis frame target digambar, sekitar 15–40 detik; pada nemesis-lite suara dipisahkan dan setiap frame menjadi panduan kedalaman, sekitar 25 detik untuk klip 8 detik dan satu setengah menit untuk klip 30 detik. Lalu video dirender, yang memakan sebagian besar waktu tunggu: klip 8 detik pada 480p memakan waktu sekitar 4–7 menit. Lakukan polling pada generasi sampai selesai.
Nemesis Lite
nemesis-lite menerima input yang sama dengan nemesis dan merendernya di Wan 3.0: lebih murah, sedikit kurang setia pada wajah dan detail halus. Klipnya 2–15 d. Harganya sebesar tarif Wan 3.0 ditambah $0.02 per detik ($0.07, $0.11, dan $0.19 pada 480p, 720p, dan 1080p), per detik klip masuk ditambah video keluar.
Objek generasi
| Field | Tipe | Deskripsi |
|---|---|---|
id | string | Id generasi (gen_…), dipakai untuk polling. |
object | string | Selalu generation. |
model | string | Model yang Anda minta. |
status | string | Lihat status. |
message | string | Hanya saat hasil sedang dikonfirmasi dengan penyedia: apa yang sedang terjadi. |
quoted_usd | number | Harga di rute termurah, yaitu rute yang dicoba pertama. Jika rute itu tidak bisa membuatnya dan rute cadangan yang lebih mahal berhasil, tagihannya adalah harga rute itu, hingga reserved_usd. |
reserved_usd | number | Yang ditahan dari saldo Anda: biaya maksimum generasi ini, jika rute cadangan yang lebih mahal membuatnya setelah rute lain dicoba. Selisihnya dilepas saat penyelesaian. Agar tidak pernah membayar lebih dari quoted_usd, setel max_cost_usd ke jumlah itu: rute cadangan yang lebih mahal kemudian dilewati. |
output | object | null | Saat succeeded: urls, file hasil (model gambar bisa mengembalikan beberapa), dengan width dan height; video juga memiliki duration_s dan has_audio. Unduh dengan segera; file kedaluwarsa. |
cost_usd | number | null | Yang ditagih. Diisi saat generasi berhasil; 0 saat gagal. |
attempts | number | Rute yang dicoba, termasuk fallback. Hanya yang berhasil yang ditagih. |
error | object | null | Saat failed: code, message, dan retryable; penolakan konten juga memiliki reason. Lihat mengapa generasi gagal. |
created_at, completed_at | string | Stempel waktu ISO 8601. |
Status
| Status | Arti |
|---|---|
queued | Diterima, menunggu rute. |
running | Sedang generate. Jika sebuah rute gagal, job tetap running sementara berpindah ke rute berikutnya, dan saat hasil sedang dikonfirmasi (lihat message). |
succeeded | Selesai. output.urls berisi file dan cost_usd berisi yang Anda bayar. |
failed | Semua rute gagal atau input ditolak. Tidak ada yang ditagih. |
Penagihan
- Anda membayar dari kredit prabayar, 100 per dolar, dibeli dalam paket dari $10 hingga $5.000. Setiap harga berupa bilangan bulat kredit.
- Saat Anda mengirim,
reserved_usdditahan dari saldo Anda. Jika generasi gagal, seluruhnya dilepas. - Anda hanya ditagih saat generasi berhasil, sesuai harga yang dikutip untuk rute yang membuatnya. Biasanya itu rute pertama seharga
quoted_usd. Jika rute cadangan yang harus membuatnya, biayanya bisa lebih tinggi: harga rute itu, atau, jika rute yang dicoba sebelumnya ditagih oleh pemasoknya, biaya percobaan tersebut ditambah 10%, mana yang lebih besar. Tidak pernah di atasreserved_usd. - Tidak ada kuota bulanan atau batas per menit: saldo Anda dan
max_cost_usdadalah batasnya. - Harga setiap model ada di halamannya dan di tabel harga.
Saldo
Akun pemilik kunci Anda. Periksa sebelum batch besar; tidak dikenai biaya dan tidak dihitung dalam batas generasi.
| Field | Arti |
|---|---|
available_usd | Yang bisa dicadangkan oleh generasi baru. Submit dengan reserved_usd lebih besar akan mendapat 402 insufficient_credits. |
held_usd | Dicadangkan oleh generasi yang masih berjalan. Yang tidak mereka pakai kembali saat penyelesaian. |
balance_usd | Tersedia ditambah ditahan. |
spent_usd | Ditagih untuk generasi yang selesai, sepanjang waktu. |
*_credits | Jumlah yang sama dalam kredit (100 per dolar), dibulatkan agar jumlah tersedia tidak pernah terbaca lebih tinggi dari yang sebenarnya. |
Mengunggah file referensi
Referensi dikirim sebagai tautan https:// publik. Untuk file di mesin Anda sendiri, minta tautan unggah, kirim byte-nya ke sana, dan gunakan tautan yang Anda dapat kembali. Gratis.
| Field | Arti |
|---|---|
upload_url | Kirim file ke sini dengan PUT dalam satu jam, dengan header persis seperti di upload_headers (tipe dan ukurannya). Selain itu ditolak. |
url | Tautan file di api.revana.si, berlaku hingga expires_at (14 hari). Tidak membutuhkan kunci dan mengalihkan ke file, jadi siapa pun yang bisa mengambil tautan bisa membacanya. Gunakan sebagai referensi di POST /v1/generations. File dihapus tak lama kemudian. |
id | upl_… |
Gambar (image/*) hingga 30 MB, klip (video/*) hingga 50 MB, suara (audio/*) hingga 15 MB. File yang lebih besar atau jenis lain mendapat 413 too_large atau 400 invalid_request.
Mengapa generasi gagal
Generasi failed memiliki error.code, message yang ditulis untuk ditampilkan kepada orang yang meminta, dan retryable: true jika mengirim request yang sama lagi nanti bisa berhasil, false jika request itu sendiri harus diubah. Generasi yang gagal tidak pernah ditagih.
| Kode | Bisa dicoba ulang | Kapan |
|---|---|---|
content_policy | no | Model menolak prompt atau media, atau menahan hasil yang dibuatnya. reason menyebutkan aturan mana: sexual (konten NSFW atau dewasa), minors (anak-anak atau remaja), copyright (materi berhak cipta atau pihak ketiga, merek, karakter), real_person (rupa orang nyata atau terkenal), atau other jika model tidak memberi alasan. |
invalid_input | no | Referensi tidak bisa dibaca, prompt menyebut @Image2 padahal hanya satu gambar yang dikirim, atau nilai yang ditolak model. Pesan menyebutkan yang mana. |
model_declined | no | Model menjawab dengan kata-kata alih-alih membuat gambar atau video, biasanya karena prompt meminta sesuatu yang dibutuhkannya dan tidak dikirim. Buat prompt mendeskripsikan hasilnya sendiri. |
reference_changed | no | File referensi berubah setelah diperiksa. Kirim ulang. |
max_cost_exceeded | no | Satu-satunya rute yang bisa berjalan berbiaya lebih dari max_cost_usd. |
model_busy | yes | Semua rute untuk model sedang penuh. Coba lagi dalam semenit. |
model_unavailable | yes | Tidak ada rute untuk model ini yang bisa menerima job saat ini. |
timeout | yes | Tidak ada rute yang mengembalikan hasil tepat waktu, atau max_wait_s terlewati. |
all_routes_failed | yes | Semua rute gagal karena alasan di sisi mereka. |
Error
Error memakai kode status HTTP dan body JSON: {"error": {"code": "...", "message": "..."}}.
| HTTP | Kode | Kapan |
|---|---|---|
| 400 | invalid_request | Body bukan JSON, tidak memiliki model atau input, atau berisi field yang tidak dikenal API. |
| 401 | unauthorized | Kunci API tidak ada atau tidak valid. |
| 402 | insufficient_credits | Saldo tersedia Anda tidak mencakup reserved_usd. Isi saldo dan coba lagi. |
| 403 | account_disabled | Akun dijeda. Hubungi dukungan. |
| 403 | generation_not_enabled | Kunci Anda bisa membaca harga tetapi belum bisa generate. |
| 404 | not_found | Tidak ada generasi dengan id ini di akun Anda. |
| 409 | idempotency_conflict | Idempotency-Key ini sudah dipakai dengan body yang berbeda. |
| 409 | not_ready | Meminta file sebelum generasi berhasil. |
| 413 | body_too_large | Body lebih dari 1 MB. Kirim media sebagai URL. |
| 422 | invalid_input | Field, nilai, atau kombinasi yang tidak didukung model, atau media yang tidak bisa dibaca. Tidak ada yang ditagih. |
| 422 | max_cost_exceeded | Semua rute berbiaya lebih dari max_cost_usd. |
| 422 | model_not_available | Tidak ada model dengan id ini di API. Id ada di halaman model. |
| 429 | rate_limited | Terlalu banyak request dalam detik yang sama dari satu akun (pengaman terhadap loop tak terkendali, bukan kuota). Tunggu Retry-After detik. |
| 429 | concurrency_limit | Akun sudah mencapai jumlah maksimum generasi yang sedang berjalan. Coba lagi saat salah satu selesai. |
| 503 | busy | Sedang ada beban sesaat. Coba lagi setelah Retry-After dengan Idempotency-Key yang sama. |
| 503 | model_unavailable | Tidak ada rute untuk model ini yang aktif saat ini. Coba lagi sebentar lagi. |
| 500 | server_error | Ada yang rusak di sisi kami. Aman dicoba ulang dengan Idempotency-Key yang sama. |
Daftar model
Setiap model, opsi, dan harganya dipublikasikan sebagai JSON di /data/models.json, file yang sama yang dipakai situs ini untuk merender.