KIE-AI-Z-IMAGE.md - reference for all image generation on odoo-expertos

ALL image generation goes through kie.ai z-image. NEVER use /blog image generate (Gemini), Google Imagen, OpenAI DALL-E, or any other provider. NO model fallback - if z-image errors, abort.

Authentication

Header: Authorization: Bearer ${KIE_API_KEY}
Key location: .env.local at repo root (already populated; gitignored). Loader resolves env var first, then this file.

API (async task pattern, same shape as nano-banana-2 / veo3_fast)

Submit

POST https://api.kie.ai/api/v1/jobs/createTask Headers: Authorization Bearer + Content-Type application/json Body:

{
  "model": "z-image",
  "input": {
    "prompt": "<your prompt>, NO text, NO letters, NO numbers, NO logos, NO watermarks.",
    "aspect_ratio": "16:9",
    "resolution": "2K",
    "output_format": "png"
  }
}

Response (success): { "code": 200, "data": { "taskId": "task_..." } }

Poll

GET https://api.kie.ai/api/v1/jobs/getTaskDetails?taskId=<taskId> (every 8 seconds; total timeout 300s) Headers: Authorization Bearer Response while running: { "code": 200, "data": { "status": "pending"|"running" } } Response when done: { "code": 200, "data": { "status": "completed", "output": { "image_url": "https://..." } } } Other completion fields seen across kie.ai models (handle all three): output.image_url, output.url, output.images[0].url. Response on failure: { "code": ..., "data": { "status": "failed"|"error", ... } } -> ABORT, never retry with another model.

Download

GET the resolved image URL, save to images/<slug>-<role>.png in the repo. Add <img> with unique alt; set og:image on hero; add <link rel="preload" as="image" href="/images/<slug>-hero.png">.

Helper (preferred entry point)

powershell -File seo-audit-2026-05-27\scripts\kie-image.ps1 \
  -Prompt "<full prompt ending with NO text/letters/numbers/logos>" \
  -OutPath "images/<slug>-<role>.png" \
  -Model z-image \
  -Aspect 16:9 \
  -Resolution 2K

Returns the saved absolute path on stdout. Echoes status to stderr. The helper already implements submit/poll/download/error-abort and loads KIE_API_KEY from .env.local.

Per-article image set (minimum 3)

Hero -> images/<slug>-hero.png aspect 16:9, resolution 2K. Topic metaphor.
Fig 1 (after H2 #2) -> images/<slug>-fig1.png aspect 16:9 or 4:3, resolution 1K. Mechanism/architecture motif.
Fig 2 (after H2 #4) -> images/<slug>-fig2.png aspect 16:9 or 4:3, resolution 1K. Outcome/comparison motif.

All three from z-image; distinct subjects per image; each with its own unique alt text derived from surrounding H2 + body.

Prompt rules (HARD)

MUST end with: ", NO text, NO letters, NO numbers, NO logos, NO watermarks."
Editorial illustration aesthetic; neutral palette; clean enterprise feel; no stock-photo cliches.
Never mention brand names, competitor names, currency symbols, percentages, dates, charts-with-labels, screenshots-of-UI, or human faces.
Subject only - no overlays, no text boxes, no infographics with labels.

Pre-flight probe (Phase 0, SETUP only)

powershell -File seo-audit-2026-05-27\scripts\kie-image.ps1 \
  -Prompt "abstract data visualization, blue gradient, NO text, NO letters, NO numbers, NO logos" \
  -OutPath "seo-audit-2026-05-27\scripts\.zimage-probe.png" \
  -Model z-image -Aspect 16:9 -Resolution 1K

If this errors -> abort the run with "z-image unavailable" + the kie.ai response. Do NOT continue.

Cost discipline

Use Resolution 1K for fig1/fig2, 2K only for hero.
Keep prompts under ~400 chars.
Batch sequentially per article (the per-batch goal already serializes the 3 calls per article).

3.6 KiB Raw Blame History