# 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:
```json
{
  "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)
1. **Hero** -> `images/<slug>-hero.png` aspect 16:9, resolution 2K. Topic metaphor.
2. **Fig 1** (after H2 #2) -> `images/<slug>-fig1.png` aspect 16:9 or 4:3, resolution 1K. Mechanism/architecture motif.
3. **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).