Generate Video

POST/api/gen/video

Dua bentuk request di endpoint yang sama: JSON multi-reference combiner (karakter + produk + referensi foto), dan upload gambar tunggal via multipart. Endpoint-nya milih berdasarkan Content-Type. Async — panggilan ini cuma submit job; abis itu poll Retrieve Media buat hasilnya.

Opsi A — JSON (multi-ref combiner)

Gabungin foto referensi karakter dan/atau foto produk dan/atau id foto referensi eksplisit jadi maksimal 5 referensi gambar buat model video.

Field	Tipe	Wajib	Catatan
`prompt`	string	Ya	Maks 2000 karakter
`characterId`	string	Tidak	Auto-tarik sampai 5 foto referensi aktif dari karakter itu
`productId`	string	Tidak	Otomatis nge-attach foto utama produk (foto aktif tertua) sebagai referensi input secara default; total gabungan semua referensi dibatasin 5 — lihat useProductPhoto/productPhotoReferenceIds di bawah
`useProductPhoto`	boolean	Tidak	Default true kalau productId diisi. False = productId cuma nge-tag output; nggak ada foto yang ditarik jadi referensi
`productPhotoReferenceIds`	string[]	Tidak	Override pilihan foto utama otomatis dengan id foto produk spesifik ini (harus milik productId) — lihat GET /api/gen/products/:id/reference
`photoReferenceIds`	string[]	Tidak	ID foto referensi eksplisit
`orientation`	`portrait｜landscape｜square`	Tidak	Default `portrait`
`durationSeconds`	`6｜10｜15`	Tidak	Default 10
`resolution`	`SD｜HD`	Tidak	Default SD
`clientRef`	string	Tidak	Maks 200 karakter

bash

curl -X POST https://kanzenads.com/api/gen/video \
  -H "x-api-key: hsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "joni holding product X, walking toward camera, cinematic, natural light",
    "characterId": "clx_character_joni",
    "productId": "clx_product_x",
    "orientation": "portrait",
    "durationSeconds": 10,
    "resolution": "SD"
  }'

Auto-attach foto produk

Kasih productId aja, otomatis ke-attach foto utama produk itu (foto referensi aktif tertua) jadi referensi input video-nya — nggak perlu langkah tambahan. Mau foto lain? Panggil GET /api/gen/products/:id/reference buat liat daftar foto produknya (yang ditandain isPrimary itu yang auto-attach secara default), terus kirim id-nya lewat productPhotoReferenceIds. Nggak mau ada foto produk yang ditarik — cuma mau tag output doang? Set useProductPhoto: false.

Nulis prompt kalau ada foto referensi

❗

Jangan deskripsiin ulang apa yang udah ada di foto

Kalau ada foto referensi produk atau karakter yang ke-attach, prompt-nya JANGAN mendeskripsikan rupa produk/karakter itu pakai kata-kata — foto itu udah jadi sumber kebenaran soal rupanya. Deskripsiin ulang di teks malah melawan foto-nya, hasilnya jadi nggak konsisten.

Cukup rujuk fotonya aja (misal "produk sesuai referensi foto", "karakter sesuai referensi foto"), lalu fokusin kata-kata di prompt ke scene, gaya, aksi, pencahayaan, dan komposisi — bukan ke deskripsi ulang rupa yang udah ada di foto.

❌ Salah — deskripsiin ulang rupa produk padahal udah ada foto referensi

"A sleek white 500ml serum bottle with a gold cap, on marble, studio lighting"

✅ Benar — rujuk fotonya, fokus ke scene

"Product from the reference photo, on a marble surface, soft morning light, minimalist" + productId (auto-attaches the primary photo)

❌ Salah — deskripsiin ulang rupa karakter padahal udah ada foto referensi

"A young woman with long black hair wearing a red dress, smiling"

✅ Benar — rujuk fotonya, fokus ke scene/aksi

"Character from the reference photo, walking toward camera, cinematic lighting" + characterId

Opsi B — multipart/form-data (gambar tunggal, udah live)

Field	Tipe	Wajib	Catatan
`prompt`	string	Ya	Maks 2000 karakter
`file`	binary	Ya	JPEG/PNG/WebP, maks 10 MB — satu gambar referensi
`orientation`	`landscape｜portrait｜square`	Tidak	Default `portrait`; ditolak dengan 400 kalau nggak valid
`resolution`	`SD｜HD`	Tidak	Default SD
`durationSeconds`	`6｜10｜15`	Tidak	Default 10
`clientRef`	string	Tidak	Maks 200 karakter

bash

curl -X POST https://kanzenads.com/api/gen/video \
  -H "x-api-key: hsk_your_key" \
  -F "prompt=Product showcase, cinematic, natural light" \
  -F "orientation=portrait" \
  -F "resolution=SD" \
  -F "durationSeconds=10" \
  -F "file=@/path/to/reference.jpg"

Response (kedua bentuk) — job submitted, sekarang poll

201

{
  "id": "clx_media_id",
  "status": "processing",
  "creditsCost": 1300,
  "balanceAfter": 998700,
  "waiting": true,
  "pollUrl": "/api/gen/media/clx_media_id",
  "pollAfterSeconds": 10,
  "message": "Video job accepted and processing (credits reserved, auto-refunded on failure). Poll GET /api/gen/media/{id} every ~10s until status is \"completed\", then read the file URL from \"videoUrl\"."
}

402 — insufficient credits

{ "error": "Insufficient credits", "balance": 500, "required": 1300 }

Biaya

SD/6s = 1,000 · SD/10s = 1,300 · HD = ×2 (HD/6s = 2,000, HD/10s = 2,600). Rumus yang sama berlaku buat kedua bentuk request.

⚠️

Completion cuma lewat poll — timeout stall server: 30 menit

Endpoint ini cuma submit job — nggak nunggu hasilnya. Completion dideteksi lewat polling; nggak ada webhook callback — poll GET /api/gen/media/:id (ikutin pollUrl dan pollAfterSeconds dari response submit, kira-kira tiap 10 detik). Ada cron internal yang majuin job tiap 2 menit. Kalau job-nya belum kelar dalam 30 menit, ditandain stalled dan kreditnya dibalikin.

← Generate Image Retrieve Media →

Generate Video

POST/api/gen/video

Opsi A — JSON (multi-ref combiner)

Gabungin foto referensi karakter dan/atau foto produk dan/atau id foto referensi eksplisit jadi maksimal 5 referensi gambar buat model video.

Field	Tipe	Wajib	Catatan
`prompt`	string	Ya	Maks 2000 karakter
`characterId`	string	Tidak	Auto-tarik sampai 5 foto referensi aktif dari karakter itu
`productId`	string	Tidak	Otomatis nge-attach foto utama produk (foto aktif tertua) sebagai referensi input secara default; total gabungan semua referensi dibatasin 5 — lihat useProductPhoto/productPhotoReferenceIds di bawah
`useProductPhoto`	boolean	Tidak	Default true kalau productId diisi. False = productId cuma nge-tag output; nggak ada foto yang ditarik jadi referensi
`productPhotoReferenceIds`	string[]	Tidak	Override pilihan foto utama otomatis dengan id foto produk spesifik ini (harus milik productId) — lihat GET /api/gen/products/:id/reference
`photoReferenceIds`	string[]	Tidak	ID foto referensi eksplisit
`orientation`	`portrait｜landscape｜square`	Tidak	Default `portrait`
`durationSeconds`	`6｜10｜15`	Tidak	Default 10
`resolution`	`SD｜HD`	Tidak	Default SD
`clientRef`	string	Tidak	Maks 200 karakter

bash

curl -X POST https://kanzenads.com/api/gen/video \
  -H "x-api-key: hsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "joni holding product X, walking toward camera, cinematic, natural light",
    "characterId": "clx_character_joni",
    "productId": "clx_product_x",
    "orientation": "portrait",
    "durationSeconds": 10,
    "resolution": "SD"
  }'

Auto-attach foto produk

Nulis prompt kalau ada foto referensi

❗

Jangan deskripsiin ulang apa yang udah ada di foto

❌ Salah — deskripsiin ulang rupa produk padahal udah ada foto referensi

"A sleek white 500ml serum bottle with a gold cap, on marble, studio lighting"

✅ Benar — rujuk fotonya, fokus ke scene

"Product from the reference photo, on a marble surface, soft morning light, minimalist" + productId (auto-attaches the primary photo)

❌ Salah — deskripsiin ulang rupa karakter padahal udah ada foto referensi

"A young woman with long black hair wearing a red dress, smiling"

✅ Benar — rujuk fotonya, fokus ke scene/aksi

"Character from the reference photo, walking toward camera, cinematic lighting" + characterId

Opsi B — multipart/form-data (gambar tunggal, udah live)

Field	Tipe	Wajib	Catatan
`prompt`	string	Ya	Maks 2000 karakter
`file`	binary	Ya	JPEG/PNG/WebP, maks 10 MB — satu gambar referensi
`orientation`	`landscape｜portrait｜square`	Tidak	Default `portrait`; ditolak dengan 400 kalau nggak valid
`resolution`	`SD｜HD`	Tidak	Default SD
`durationSeconds`	`6｜10｜15`	Tidak	Default 10
`clientRef`	string	Tidak	Maks 200 karakter

bash

curl -X POST https://kanzenads.com/api/gen/video \
  -H "x-api-key: hsk_your_key" \
  -F "prompt=Product showcase, cinematic, natural light" \
  -F "orientation=portrait" \
  -F "resolution=SD" \
  -F "durationSeconds=10" \
  -F "file=@/path/to/reference.jpg"

Response (kedua bentuk) — job submitted, sekarang poll

201

{
  "id": "clx_media_id",
  "status": "processing",
  "creditsCost": 1300,
  "balanceAfter": 998700,
  "waiting": true,
  "pollUrl": "/api/gen/media/clx_media_id",
  "pollAfterSeconds": 10,
  "message": "Video job accepted and processing (credits reserved, auto-refunded on failure). Poll GET /api/gen/media/{id} every ~10s until status is \"completed\", then read the file URL from \"videoUrl\"."
}

402 — insufficient credits

{ "error": "Insufficient credits", "balance": 500, "required": 1300 }

Biaya

SD/6s = 1,000 · SD/10s = 1,300 · HD = ×2 (HD/6s = 2,000, HD/10s = 2,600). Rumus yang sama berlaku buat kedua bentuk request.

⚠️

Completion cuma lewat poll — timeout stall server: 30 menit

← Generate Image Retrieve Media →