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

Retrieve Media

GET/api/gen/media/:id

Endpoint poll terpadu buat job gambar maupun video.

Response

json
{
  "id": "clx_media_id",
  "status": "queued | processing | completed | failed | stalled",
  "prompt": "string",
  "mediaType": "IMAGE | VIDEO",
  "creditsCost": 1300,
  "videoUrl": "string | null",
  "thumbnailUrl": "string | null",
  "durationSeconds": 10,
  "errorMessage": "string | null",
  "refundedAt": "ISO8601 | null",
  "createdAt": "ISO8601",
  "completedAt": "ISO8601 | null",
  "resolution": "SD | HD",
  "orientation": "portrait | landscape | square",
  "inputs": [{ "photoReferenceId": "string", "fileUrl": "string", "label": "string", "order": 0 }],

  "waiting": true,
  "progress": 40,
  "pollAfterSeconds": 10,
  "nextAction": "poll_again | use_videoUrl | retry",
  "message": "string"
}

Yang lo liat pas nunggu

Job-nya jalan dari queued (diterima, belum mulai) → processing (lagi di-render — progress nunjukin persentase 0–100 begitu dilaporin provider, kalau enggak null) → status akhir: completed (baca videoUrl), failed (liat errorMessage), atau stalled (timeout). Baik failed maupun stalled otomatis balikin kredit.

Lo nggak perlu implement logic ini manual: waiting bernilai true buat queued/processing dan false begitu status akhir; nextAction ngasih tau langkah selanjutnya (poll_again, use_videoUrl, atau retry); pollAfterSeconds nunjukin berapa lama nunggu sebelum request berikutnya (10 pas lagi nunggu, null begitu status akhir); dan message adalah ringkasan yang gampang dibaca dari semua di atas. Agent yang integrasi bisa gampang loop di waiting / nextAction dan pollAfterSeconds tanpa perlu cek status langsung.

⚠️

videoUrl juga nyimpen gambar — di sini nggak ada field imageUrl

Endpoint ini selalu pakai key videoUrl buat filenya, bahkan pas mediaType adalah "IMAGE". Kalau client lo ngarepin imageUrl, cek mediaType dan baca videoUrl aja. (Cuma endpoint list, GET /api/gen/image, yang me-remap field ini ke imageUrl — endpoint single-item ini enggak.)

Rekomendasi polling buat agent

Tipe mediaInterval pollNyerah (timeout)
Gambartiap 5–10 detik15 menit (samain sama stall window server)
Videotiap 5–10 detik30 menit (samain sama stall window server)

Ini interval yang dipakai client agent buat polling; cron completion di server jalan tiap 2 menit secara internal — interval di sisi client lo nggak perlu samain itu, yang penting wajar dan berhenti sebelum stall window.

Nanganin failed / stalled

  • failed — errorMessage jelasin kenapa (error dari provider). Kredit udah dibalikin.
  • stalled — kelewat stall window server tanpa hasil. Kredit udah dibalikin. Aman buat coba lagi dengan request baru.
  • Cek refundedAt buat mastiin refund-nya masuk (selalu kejadian buat kedua status akhir kegagalan).

Contoh

bash
curl https://kanzenads.com/api/gen/media/clx_media_id \
  -H "x-api-key: hsk_your_key"
← Generate VideoTop Up Campaign Ads →