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 — liat callout di Generate Video.

Cari tau id karakter dan produk

Ambil id karakter "joni" dan id Product X — dari GET /api/hermes/library (Content API lama, kalau agent lo udah punya akses assignment-scoped) atau dari id yang udah lo catat sendiri. Lo 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).

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.

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 Ads Errors & Limits →