Generate Image

JSON body. Async — panggilan ini cuma submit job; abis itu poll Retrieve Media buat hasilnya.

Request body

Gambar referensi (image-to-image)

Kasih model sesuatu buat jadi acuan, bukan cuma generate dari prompt doang. Gabungin imageUrls (URL HTTPS mentah), photoReferenceIds (record PhotoReference yang udah ada), dan characterId (semua foto referensi karakter itu) — semuanya digabung dan di-dedup, dibatasin maksimal 5 referensi total. photoReferenceIds dan characterId di-resolve di server dan owner-scoped — lo cuma bisa referensiin foto/karakter milik lo sendiri. Tambahin maskUrl buat batesin edit ke area yang di-mask (inpainting).

{
  "prompt": "Character holding the product bottle, studio lighting",
  "characterId": "clx_character_id",
  "photoReferenceIds": ["clx_photo_ref_id"],
  "maskUrl": "https://example.com/mask.png",
  "size": "1:1"
}

Auto-attach foto produk

Kasih productId aja, otomatis ke-attach foto utama produk itu (foto referensi aktif tertua) jadi input image-to-image — 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 yang ditarik — cuma mau tag output doang? Set useProductPhoto: false.

{
  "prompt": "Product bottle on a marble countertop, soft morning light",
  "productId": "clx_product_id"
}

{
  "prompt": "Same product, different angle",
  "productId": "clx_product_id",
  "productPhotoReferenceIds": ["clx_photo_ref_id"]
}

Nulis prompt kalau ada foto referensi

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.

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

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

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

"Character from the reference photo, holding the product, warm studio lighting" + characterId

Contoh

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 a marble countertop, soft morning light",
    "productId": "clx_product_id",
    "size": "3:2",
    "n": 1
  }'

{
  "id": "clx_media_id",
  "status": "processing",
  "creditsCost": 400,
  "balanceAfter": 49600,
  "waiting": true,
  "pollUrl": "/api/gen/media/clx_media_id",
  "pollAfterSeconds": 10,
  "message": "Image 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\"."
}

{ "error": "Insufficient credits", "balance": 200, "required": 400 }

Polling di sisi server

Endpoint ini cuma submit job — nggak nunggu hasilnya. Job-nya diproses async; ada tick background yang majuin tiap 2 menit. Gambar yang udah selesai disajiin dari URL Kanzen Ads yang permanen. Ikutin pollUrl, pollAfterSeconds, dan message dari response submit, atau poll aja GET /api/gen/media/:id tiap ~10 detik.

Terus poll buat hasilnya

Pakai id yang dibalikin dengan GET /api/gen/media/:id.