Kanzen Ads Docs

Skenario — Animasikan karakter "joni" bawa Product X → video portrait 10 detik

Pakai combiner multi-referensi JSON di POST /api/gen/video buat nge-anchor tampilan karakter dan penampilan produk dari foto referensi, sementara prompt teks bebas ngejelasin aksinya ("carrying", "walking toward camera", dst).

❗

Status wiring combiner

Skenario ini dokumentasiin kontrak JSON target buat feature 005 (multi-ref combiner). Konfirmasi ke integrator dulu bahwa handler POST /api/gen/video yang live udah dispatch body JSON-nya sebelum ini dijalanin di production — lihat callout di Generate Video.
1

Cari tau id karakter dan produk

Ambil id karakter "joni" dan id Product X — dari GET /api/hermes/library (Content API lama, kalau agent kamu udah punya akses assignment-scoped) atau dari id yang udah kamu catat sendiri. Kamu nggak perlu ambil foto-fotonya sendiri: dengan kasih characterId otomatis ke-pull sampai 5 foto referensi aktif punya joni, dan productId nambahin foto Product X di atasnya (total gabungan dibatasin maks 5 referensi).

2

Submit job generate video

1.300 kredit (SD, 10 detik).

curl
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"
  }'
Response 201
{ "id": "clx_media_id", "status": "processing", "creditsCost": 1300, "balanceAfter": 998700 }

Simpan id.

3

Poll sampai selesai

curl — every 10s, timeout 30 min
curl https://kanzenads.com/api/gen/media/clx_media_id \
  -H "x-api-key: hsk_your_key"
completed
{
  "id": "clx_media_id", "status": "completed", "mediaType": "VIDEO",
  "videoUrl": "https://kanzenads.com/api/photos/serve/generated/clx_media_id.mp4",
  "thumbnailUrl": "https://kanzenads.com/api/photos/serve/generated/clx_media_id_thumb.jpg",
  "durationSeconds": 10, "orientation": "portrait", "resolution": "SD",
  "completedAt": "2026-07-08T09:18:00Z"
}
⚠️

failed / stalled → kredit udah otomatis balik

Selesainya video cuma lewat poll (nggak ada webhook) dengan window stall server 30 menit. Kalau status statusnya failed atau stalled, kreditnya udah otomatis balik — retry dari step 2 atau alert manusia.

Catatan

  • Maksud "bawa product X" sepenuhnya ada di prompt teks bebas — gambar referensi dari characterId/productId cuma nge-anchor siapa dan apa yang bakal keliatan di video, bukan aksinya sendiri.
  • Kalau butuh interaksi spesifik, penempatan produk, atau gerakan kamera tertentu, jelasin di prompt-nya.
← Top Up Campaign AdsErrors & Limits →