Kanzen Ads Docs
IntroductionQuickstartAuthentication
Connect to Hermes Agent
Payments / Top-up
Overview & CreditsGenerate ImageGenerate VideoRetrieve Media
Top Up Campaign AdsCharacter + Product Video
Errors & LimitsAPI ReferenceMeta Marketing API Guide

Skenario — Top up Campaign A kalau di bawah 5 iklan aktif

Agen Hermes disuruh jaga minimal 5 iklan aktif di Campaign A. Begitu kedeteksi kurang, dia generate 1 kreatif baru, terus serahin ke panggilan Meta Graph API-nya sendiri buat bikin iklannya.

1

Generate gambar kreatif

400 kredit (1 gambar, n: 1).

curl
curl -X POST https://kanzenads.com/api/gen/image \
  -H "x-api-key: hsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Product bottle on marble countertop, soft studio light, 3:2 ad creative",
    "productId": "clx_product_id",
    "size": "3:2",
    "n": 1
  }'
Response 201
{ "id": "clx_media_id", "status": "processing", "creditsCost": 400, "balanceAfter": 49600 }

Simpan id — bakal dipakai buat poll berikutnya.

2

Poll sampai selesai

curl — every 5–10s, timeout 15 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": "IMAGE",
  "videoUrl": "https://kanzenads.com/api/photos/serve/generated/clx_media_id.png",
  "completedAt": "2026-07-08T09:03:00Z"
}
⚠️

failed / stalled → kredit udah otomatis balik

Kalau status statusnya failed atau stalled, stop poll — refund-nya udah masuk (refundedAt udah keisi). Bisa retry dari step 1 pakai request baru, atau alert manusia kalau gagal terus-terusan.
3

Bikin iklan di Meta

Pakai URL gambar yang udah di-rehost (videoUrl field — liat Retrieve Media) sebagai kreatif buat iklan baru. Penulisan ke Meta ini (bikin iklan, nempelin ke adset Campaign A) itu domain-nya Hermes sendiri lewat Graph API — di luar cakupan Generation API. Dokumen ini cuma bahas titik serah-terimanya: lo udah punya URL kreatif permanen yang siap dipakai.

Timing end-to-end

StepWaktu biasanya
Generate gambar (submit → completed)detik sampe beberapa menit, timeout di 15 menit
Bikin iklan di MetaPanggilan Graph API-nya Hermes sendiri, di luar cakupan sini
← Retrieve MediaCharacter + Product Video →