baldart 3.6.2

package/framework/.claude/skills/issue-review/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: issue-review
+description: Run the GitHub issue review workflow for triage and planning. Use when the user asks to review or triage a GitHub issue, requests the /issue-review slash command, or needs an issue summary with priority/plan/tests.
+---
+
+# Issue Review
+
+## Overview
+
+Run the `/issue-review` automation, capture issue context, and produce a triage + plan summary using the project's GitHub issue subagent protocol.
+
+## Workflow
+
+If the user mentions `/issue-review` without a number, ask for the GitHub issue ID.
+
+### Phase 0 — Documentation Context
+
+Before triaging, use `search_docs` MCP tool (if available) with `mode: "hybrid"` to find related PRDs, ADRs, and reference docs for the issue's domain. The active retrieval layer is Obsidian-first LightRAG: use Obsidian for concept context, then verify implementation/stateful claims against repo docs/code. If MCP is unavailable, fall back to targeted canonical docs plus `rg` over `${paths.references_dir}/`, `${paths.backlog_dir}/`, and `.claude/agents/`. Check `${paths.references_dir}/traceability-matrix.md` for source-to-doc mappings.
+
+### Phase 1 — Triage
+
+1. Run `npm run issue-review <number>` (optionally `--repo owner/repo`). This calls `scripts/issue-review.mjs` to fetch the issue snapshot including structured JSON data.
+2. Perform the clarity analysis in `agents/github-issue-subagent.md` (MUST for bugs per AGENTS.md).
+3. Apply the triage matrix from `agents/github-issue-subagent.md`, listing Blocker/High impacts first.
+
+### Phase 2 — Plan
+
+4. Create or update a backlog card from `templates/feature-card.template.yml`. Populate `execution_mode`, `git_strategy`, and `claimed_paths` fields.
+5. Ask the user which git strategy to use (main vs feature branch) per AGENTS.md and record it in `git_strategy`.
+6. Route to specialist agents based on issue type:
+   - UI/UX issues: invoke `ui-expert` agent.
+   - New features (label "New Feature" or implicit): invoke `prd` agent, follow `agents/index.md` pre-implementation requirements.
+   - Architecture decisions: invoke `codebase-architect` agent.
+
+### Phase 3 — Execute
+
+7. For new features: invoke `prd` agent for spec, synthesize plan into backlog card, invoke `coder` agent to implement.
+8. For bugs/fixes: invoke `coder` agent for complex fixes.
+9. After implementation: invoke `code-reviewer` on the changes (MUST per agents/index.md).
+10. If documentation updates are needed: invoke `doc-reviewer`.
+11. Apply `vibe review` label and add a summary comment on the GitHub issue (MUST per AGENTS.md).
+
+## Agent Routing
+
+Follow `agents/index.md` for agent invocation rules and sequencing. Do not write production code yourself; orchestrate other agents and synthesize results. Run independent agents in the background where possible.

package/framework/.claude/skills/kie-ai/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: kie-ai
+description: >
+  Generate images, videos, and audio using Kie.ai's unified AI API platform (80+ models).
+  Use when: (1) generating images from text or editing images (Nano Banana 2, Imagen 4, Flux Kontext,
+  4o Image, Seedream, Grok Imagine, Qwen, Ideogram, Flux-2, GPT Image 1.5, Z-Image),
+  (2) generating videos from text/images (Kling 3.0, Sora 2, Veo 3.1, Runway Gen-4, Wan 2.6,
+  Hailuo, Bytedance Seedance), (3) upscaling images/videos (Topaz, Recraft),
+  (4) generating music/audio (Suno V4, ElevenLabs TTS/SFX), (5) removing backgrounds,
+  (6) any task involving "kie", "kie.ai", "genera immagine", "genera video", "crea immagine",
+  "crea video", "text to image", "text to video", "image to video", or model names like
+  "nano banana", "imagen", "flux", "kling", "sora", "veo", "runway", "seedream", "wan",
+  "hailuo", "midjourney", "suno", "elevenlabs".
+  Triggers on: /kie, /generate-image, /generate-video, /kie-setup.
+---
+
+# Kie.ai — AI Image, Video & Audio Generation
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** `paths.design_system`, `paths.ui_guidelines`, `identity.design_philosophy`, `identity.brand_name`.
+**Gated by features:** `features.has_design_system` (when `true`, the design-system reads below are BLOCKING; when `false`, fall back to `paths.ui_guidelines` alone).
+**Overlay:** loads `.baldart/overlays/kie-ai.md` if present — project-specific illustration character library, video-prompt motion vocabulary, and forbidden aesthetic patterns.
+**On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
+
+## Visual Contract (project-specific)
+
+When generating images, videos, or animation prompts for product illustrations, the project's design-system SSOT is a BLOCKING prerequisite before model selection or prompt writing — but only when the project has one. Reading order:
+
+1. `${paths.design_system}/INDEX.md` — design-system entry point (when `features.has_design_system: true`).
+2. `${paths.design_system}/tokens-reference.md` — canonical color and shadow contract (when present).
+3. `${paths.ui_guidelines}` — brand visual language and UI constraints.
+4. `${paths.design_system}/patterns/illustration-motion.md` — canonical illustration, character, product-variant, and surgical video-prompt rules (when present; otherwise consult `.baldart/overlays/kie-ai.md`).
+
+Every prompt should reflect `identity.design_philosophy` (e.g. "Neo-Brutalism" → bold flat shapes + hard offsets; "Minimalist" → restrained palette + breathing room). Every video prompt should use element-by-element "surgical motion" rules (what moves, what reacts, what stays fixed) rather than leaving motion to implicit model interpretation.
+
+## Setup (First-Time)
+
+If no API key is configured, run setup before any generation:
+
+```bash
+bash scripts/setup_api_key.sh
+```
+
+Stores key securely in macOS Keychain (or `~/.config/kie-ai/config` on Linux).
+Get your key at: <https://kie.ai/api-key>
+
+Check remaining credits:
+
+```bash
+bash scripts/kie_api.sh credits
+```
+
+## Quick Reference
+
+- **Full model catalog with parameters**: Read [references/models-catalog.md](references/models-catalog.md)
+- **API helper script**: `scripts/kie_api.sh` (handles auth, create, poll, download)
+- **Base URL**: `https://api.kie.ai`
+- **Auth**: `Authorization: Bearer <KEY>` (key retrieved automatically by scripts)
+- **Docs**: <https://docs.kie.ai>
+
+## Limits
+
+Max 20 requests / 10 seconds, ~100 concurrent. HTTP 429 = wait and retry.
+
+## How It Works
+
+All Kie.ai APIs are **asynchronous**:
+1. **Create task** → get `taskId`
+2. **Poll status** until `success` or `fail`
+3. **Download** the generated file (URLs valid 14 days, direct downloads 20 min)
+
+## API Patterns
+
+Two patterns exist (Market Unified vs Dedicated). See [models-catalog.md](references/models-catalog.md#two-api-patterns) for details. The helper script handles both — use `create-market` or `create`.
+
+## Generation Workflow
+
+### Step 1: Determine task and model
+
+**Default model for images: `nano-banana-2`** (Nano Banana 2). Use it automatically
+unless the user explicitly requests a different model. Do NOT present a model selection
+menu — just proceed with nano-banana-2. Mention alternatives only if the user asks
+"quale modello?" or names a specific one.
+
+**Default model for videos: `kling-3.0/video`** (Kling 3.0).
+
+If the user needs **maximum fidelity or complex text rendering**, suggest upgrading to
+`nano-banana-pro` (Gemini 3.0 Pro, 18-24 cr) — same API pattern, just change model ID.
+
+Alternative models (only when explicitly requested):
+- **Images**: Nano Banana Pro, Imagen 4, Flux Kontext, 4o Image, Seedream, Flux-2, Grok Imagine
+- **Videos**: Veo 3.1, Sora 2, Runway Gen-4 Turbo, Runway Aleph (V2V/VFX), Wan 2.6, Hailuo, Luma Modify
+- **Audio**: Suno V4 (music), ElevenLabs (TTS, SFX, dialogue)
+- **Upscale**: Topaz (image/video), Recraft (background removal, upscale)
+
+For model-specific parameters, read [references/models-catalog.md](references/models-catalog.md).
+
+### Step 2: Collect parameters
+
+Ask for the essential parameters only:
+- **Prompt** (always required)
+- **Aspect ratio** (default `1:1` if not specified)
+- **Resolution** for nano-banana-2: default `2K` (good balance quality/cost at 12 credits)
+
+For non-default models, read [references/models-catalog.md](references/models-catalog.md) for exact parameters.
+
+Common parameters across models:
+- `prompt` (always required for generation)
+- `aspect_ratio` / `size` (varies per model)
+- `callBackUrl` (optional, omit for polling)
+- Image/video URLs for edit/I2V modes
+
+### Step 2.5: Transparency Check (images only — SKIP for video/audio/upscale)
+
+**This step applies ONLY to image generation.** Skip entirely for video, audio, and upscale tasks.
+
+**HARD GATE.** Before sending ANY image generation request, you MUST
+ask the user whether they need a transparent background. Do NOT skip this step. Do NOT
+assume the answer.
+
+**Ask explicitly:**
+
+> **Sfondo trasparente?**
+> L'immagine deve avere lo sfondo trasparente (PNG con alpha)?
+> - **A)** Si, sfondo trasparente
+> - **B)** No, sfondo normale
+
+**⛔ STOP.** Wait for the user's answer before proceeding.
+
+**If the user wants transparent background:**
+
+1. **Modify the prompt** — append to the user's prompt:
+   ```
+   The subject MUST be placed on a perfectly uniform, solid, bright GREEN
+   (#00FF00) chroma-key background. The green must be flat, even, with NO
+   shadows, NO gradients, NO reflections on the green area. The subject
+   must have clean, sharp edges with NO green spill on the subject itself.
+   ```
+2. **Force PNG output** — set `output_format: "png"` (or equivalent per model).
+3. **Set `needs_transparency: true`** in your internal tracking for this request.
+
+**If the user does NOT want transparent background:**
+- Proceed normally. Set `needs_transparency: false`.
+
+**Detection from context:** If the user's original request or the calling system
+already mentions "transparent", "sfondo trasparente", "no background", "alpha",
+"PNG with transparency", or "rimuovi sfondo" → still ask the question to confirm,
+but default the recommendation to **A) Si**.
+
+### Output Path Convention
+
+Save all generated files to `/tmp/kie-ai/`. Create the directory if it doesn't exist.
+Naming: `<slug>-<timestamp>.<ext>` (e.g., `promo-cityscape-20260404-143022.png`).
+For transparency processing: raw file as `<name>-raw-greenscreen.png`, final as `<name>.png`.
+
+### Step 3: Execute
+
+Use the helper script:
+
+```bash
+# Market models (most models)
+bash scripts/kie_api.sh create-market '{
+  "model": "nano-banana-2",
+  "input": {
+    "prompt": "A futuristic cityscape at sunset",
+    "aspect_ratio": "16:9",
+    "resolution": "2K"
+  }
+}'
+
+# Dedicated models (Runway, Veo3, 4o Image, Flux Kontext)
+bash scripts/kie_api.sh create "/api/v1/veo/generate" '{
+  "prompt": "A cat exploring a magical forest",
+  "model": "veo3_fast",
+  "aspect_ratio": "16:9"
+}'
+```
+
+### Step 4: Poll and download
+
+```bash
+# Market models
+bash scripts/kie_api.sh poll-market "task_12345" 60 10
+
+# Dedicated models
+bash scripts/kie_api.sh poll "/api/v1/veo/record-info" "veo_task_abc" 60 10
+
+# Download result
+bash scripts/kie_api.sh download "https://tempfile..." "./output.png"
+```
+
+### Step 5: Post-process and present result
+
+**If `needs_transparency` is true:**
+
+After downloading the image, remove the green screen and produce a transparent PNG:
+
+```bash
+python3 scripts/remove_greenscreen.py "<input_path>" "<output_path>" [--tolerance 60] [--edge-blur 1]
+```
+
+The script:
+1. Converts green (#00FF00 region) to transparent alpha
+2. Applies edge cleanup to remove green fringe/spill
+3. Saves as PNG with alpha channel
+
+Parameters:
+- `--tolerance` (default 60): how much deviation from pure green to include (0-255).
+  Increase if green remnants remain, decrease if subject edges are eaten.
+- `--edge-blur` (default 1): pixel radius for edge anti-aliasing. Use 0 for pixel-perfect
+  edges, 2-3 for softer blending.
+
+After processing, show the user the **transparent PNG path** (not the raw green screen
+version). Keep the raw version as `<name>-raw-greenscreen.png` in case the user wants
+to re-process with different tolerance.
+
+**If `needs_transparency` is false:**
+
+Show the user the download URL or local file path. If multiple URLs, list them all.
+
+## Error Handling
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 200 | Task created (NOT completed) | Poll for result |
+| 401 | Invalid API key | Re-run setup |
+| 402 | Insufficient credits | Top up at kie.ai |
+| 422 | Invalid parameters | Check model docs |
+| 429 | Rate limited | Wait and retry |
+| 451 | Image fetch failed | Check image URL |
+| 455 | Service maintenance | Wait |
+| 500 | Server error | Retry |
+| 501 | Generation failed | Retry with different params |
+
+## File Upload (when user has local files)
+
+```bash
+# Upload local file
+bash scripts/kie_api.sh upload-stream "/path/to/image.png"
+
+# Upload from URL
+bash scripts/kie_api.sh upload-url "https://example.com/image.png"
+```
+
+Upload response contains `fileUrl` to use as input. Files expire in 3 days.
+
+## Pricing Reference (credits)
+
+**Default models:**
+
+| Model | Cost |
+|-------|------|
+| Nano Banana 2 (1K) | 8 cr |
+| Nano Banana 2 (2K) | 12 cr |
+| Nano Banana 2 (4K) | 18 cr |
+| Kling 3.0 video | 20-40 cr/s |
+| Recraft bg removal | 2 cr |
+
+For other models, see [references/models-catalog.md](references/models-catalog.md).
+
+Check credits: `bash scripts/kie_api.sh credits`

package/framework/.claude/skills/kie-ai/references/models-catalog.md

@@ -0,0 +1,272 @@
+# Kie.ai Models Catalog
+
+Complete reference of all available models, organized by category.
+Base URL: `https://api.kie.ai`
+
+## Quick Pick (most common)
+
+| Task | Model | ID | Credits |
+|------|-------|----|---------|
+| Image (default — fast + cheap) | Nano Banana 2 | `nano-banana-2` | 8-18 |
+| Image (max fidelity + text) | Nano Banana Pro | `nano-banana-pro` | 18-24 |
+| Video (best quality) | Kling 3.0 | `kling-3.0/video` | 20-40/s |
+| Background removal | Recraft | `recraft/remove-background` | 2 |
+
+## Two API Patterns
+
+### 1. Dedicated Endpoints (Legacy models)
+Specific URL per model. Used by: Runway, Veo3, 4o Image, Flux Kontext.
+
+### 2. Market Unified Endpoint (Newer models)
+All use `POST /api/v1/jobs/createTask` with `model` field. Status: `GET /api/v1/jobs/recordInfo?taskId={id}`.
+
+---
+
+## IMAGE MODELS
+
+### 4o Image (GPT-4o)
+- **Endpoint**: `POST /api/v1/gpt4o-image/generate`
+- **Status**: `POST /api/v1/gpt4o-image/record-info` (GET with taskId query)
+- **Download**: `POST /api/v1/gpt4o-image/download-url`
+- **Parameters**:
+  | Param | Type | Required | Values |
+  |-------|------|----------|--------|
+  | prompt | string | Yes* | Max text (*at least prompt or filesUrl) |
+  | filesUrl | string[] | Yes* | Up to 5 image URLs |
+  | size | string | Yes | `1:1`, `3:2`, `2:3` |
+  | maskUrl | string | No | Mask URL (black=modify, white=preserve) |
+  | callBackUrl | string | No | Webhook URL |
+  | isEnhance | boolean | No | Prompt enhancement (default: false) |
+  | enableFallback | boolean | No | Auto-fallback (default: false) |
+  | fallbackModel | string | No | `GPT_IMAGE_1`, `FLUX_MAX` |
+
+### Flux Kontext
+- **Endpoint**: `POST /api/v1/flux/kontext/generate`
+- **Status**: `GET /api/v1/flux/kontext/record-info?taskId={id}`
+- **Parameters**:
+  | Param | Type | Required | Values |
+  |-------|------|----------|--------|
+  | prompt | string | Yes | English preferred |
+  | inputImage | string | No | URL for edit mode |
+  | model | string | No | `flux-kontext-pro`, `flux-kontext-max` |
+  | aspectRatio | string | No | `21:9`,`16:9`,`4:3`,`1:1`,`3:4`,`9:16` |
+  | outputFormat | string | No | `jpeg`, `png` |
+  | promptUpsampling | boolean | No | Better quality, slower |
+  | safetyTolerance | int | No | 0-6 (gen), 0-2 (edit) |
+  | watermark | string | No | Watermark text |
+  | enableTranslation | boolean | No | Auto-translate (default: true) |
+
+### Nano Banana 2 (Google Gemini 3.1 Flash Image)
+- **Model ID**: `nano-banana-2`
+- **Endpoint**: `POST /api/v1/jobs/createTask`
+- **Parameters**:
+  | Param | Type | Required | Values |
+  |-------|------|----------|--------|
+  | prompt | string | Yes | Max 20,000 chars |
+  | image_input | string[] | No | Up to 14 images (JPEG/PNG/WebP, 30MB each) |
+  | google_search | boolean | No | Real-time search grounding |
+  | aspect_ratio | string | No | `1:1`,`1:4`,`1:8`,`2:3`,`3:2`,`3:4`,`4:1`,`4:3`,`4:5`,`5:4`,`8:1`,`9:16`,`16:9`,`21:9`,`auto` |
+  | resolution | string | No | `1K`,`2K`,`4K` (default: 1K) |
+  | output_format | string | No | `png`, `jpg` |
+- **Pricing**: 8 credits (1K), 12 credits (2K), 18 credits (4K)
+
+### Nano Banana Pro (Google Gemini 3.0 Pro Image)
+
+- **Model ID**: `nano-banana-pro`
+- **Endpoint**: `POST /api/v1/jobs/createTask`
+- **Parameters**:
+  | Param | Type | Required | Values |
+  |-------|------|----------|--------|
+  | prompt | string | Yes | Max 10,000 chars |
+  | image_input | string[] | No | Up to 8 images (JPEG/PNG/WebP, 30MB each) |
+  | aspect_ratio | string | No | `1:1`,`2:3`,`3:2`,`3:4`,`4:3`,`4:5`,`5:4`,`9:16`,`16:9`,`21:9`,`auto` |
+  | resolution | string | No | `1K`,`2K`,`4K` (default: 1K) |
+  | output_format | string | No | `png`, `jpg` |
+- **Pricing**: 18 credits (1K-2K), 24 credits (4K)
+- **Use when**: max fidelity needed, complex text rendering, UI/label readability, deeper reasoning
+
+### Google Imagen 4
+- **Model ID**: `google/imagen4`
+- **Endpoint**: `POST /api/v1/jobs/createTask`
+- **Parameters**:
+  | Param | Type | Required | Values |
+  |-------|------|----------|--------|
+  | prompt | string | Yes | Max 5000 chars |
+  | negative_prompt | string | No | Elements to avoid |
+  | aspect_ratio | string | No | `1:1`,`16:9`,`9:16`,`3:4`,`4:3` |
+  | seed | string | No | Reproducibility |
+- **Variants**: `google/imagen4-fast`, `google/imagen4-ultra`
+
+### Seedream Series (ByteDance)
+
+| Version | Model ID | Notes |
+|---------|----------|-------|
+| v4 | `bytedance/seedream-v4-text-to-image` | Legacy naming |
+| v4.5 | `seedream/4.5-text-to-image` | Current naming |
+| v5.0 Lite | `seedream/5.0-lite-text-to-image` | Reasoning model, up to 6 images |
+| v5.0 Lite (I2I) | `seedream/5.0-lite-image-to-image` | Edit variant |
+
+- **Endpoint**: `POST /api/v1/jobs/createTask`
+- **Common Parameters**:
+  | Param | Type | Required | Values |
+  |-------|------|----------|--------|
+  | prompt | string | Yes | Max 5000 chars |
+  | image_size | string | No | `square`,`square_hd`,`portrait_4_3`,`portrait_3_2`,`portrait_16_9`,`landscape_4_3`,`landscape_3_2`,`landscape_16_9`,`landscape_21_9` |
+  | image_resolution | string | No | `1K`,`2K`,`4K` |
+  | max_images | number | No | 1-6 |
+  | seed | integer | No | Reproducibility |
+- **Edit variants** also accept `image_urls` for image-to-image
+
+### Flux-2 Series
+- **Model IDs**: `flux-2/pro-text-to-image`, `flux-2/pro-image-to-image`, `flux-2/flex-text-to-image`, `flux-2/flex-image-to-image`
+- **Endpoint**: `POST /api/v1/jobs/createTask`
+
+### Other Image Models
+- **Grok Imagine**: `grok-imagine/text-to-image`, `grok-imagine/image-to-image`
+- **GPT Image 1.5**: `gpt-image-1.5/text-to-image`, `gpt-image-1.5/image-to-image`
+- **Qwen**: `qwen/text-to-image`, `qwen/image-to-image`, `qwen/image-edit`
+- **Ideogram**: `ideogram/v3-reframe`, `ideogram/character`, `ideogram/character-edit`, `ideogram/character-remix`
+- **Z-Image**: `z-image` (check docs)
+- **Recraft**: `recraft/remove-background`, `recraft/crisp-upscale`
+- **Topaz**: `topaz/image-upscale`
+
+---
+
+## VIDEO MODELS
+
+### Runway Gen-4 / Gen-4 Turbo
+
+- **Endpoint**: `POST /api/v1/runway/generate`
+- **Status**: `GET /api/v1/runway/record-info?taskId={id}`
+- **Extend**: `POST /api/v1/runway/extend`
+- **Parameters**:
+  | Param | Type | Required | Values |
+  |-------|------|----------|--------|
+  | prompt | string | Yes | Max 1800 chars |
+  | imageUrl | string | No | Reference image |
+  | duration | number | Yes | `5`, `10` |
+  | quality | string | Yes | `720p`, `1080p` (1080p only with 5s) |
+  | aspectRatio | string | No* | `16:9`,`4:3`,`1:1`,`3:4`,`9:16` (*required for text-to-video) |
+  | waterMark | string | No | Watermark text |
+  | callBackUrl | string | Yes | Webhook URL |
+- **Pricing**: 5s 720p = 12 cr, 10s 720p / 5s 1080p = 30 cr
+- **Gen-4 Turbo**: ~5x faster generation (5-8s videos in ~1 minute)
+
+### Runway Aleph (Video-to-Video, Relighting, VFX)
+
+- **Endpoint**: `POST /api/v1/aleph/generate`
+- **Status**: `GET /api/v1/aleph/record-info?taskId={id}`
+- **Capabilities**: video-to-video, relighting, scene edits, VFX via text/image prompts
+
+### Veo 3.1 (Google)
+- **Endpoint**: `POST /api/v1/veo/generate`
+- **Status**: `GET /api/v1/veo/record-info?taskId={id}`
+- **1080P**: `POST /api/v1/veo/get-1080p`
+- **4K**: `POST /api/v1/veo/get-4k`
+- **Parameters**:
+  | Param | Type | Required | Values |
+  |-------|------|----------|--------|
+  | prompt | string | Yes | Scene description |
+  | imageUrls | string[] | No | 1-2 images (I2V mode) |
+  | model | string | No | `veo3`, `veo3_fast` (default: veo3_fast) |
+  | generationType | string | No | `TEXT_2_VIDEO`, `FIRST_AND_LAST_FRAMES_2_VIDEO`, `REFERENCE_2_VIDEO` |
+  | aspect_ratio | string | No | `16:9`, `9:16`, `Auto` |
+  | seeds | integer | No | 10000-99999 |
+  | enableTranslation | boolean | No | Auto-translate (default: true) |
+  | watermark | string | No | Watermark text |
+
+### Kling 3.0
+- **Model ID**: `kling-3.0/video`
+- **Endpoint**: `POST /api/v1/jobs/createTask`
+- **Parameters**:
+  | Param | Type | Required | Values |
+  |-------|------|----------|--------|
+  | prompt | string | Yes* | Max 2500 chars (*required when multi_shots=false) |
+  | image_urls | string[] | No | Max 2 (start/end frame) |
+  | sound | boolean | Yes | Audio generation |
+  | duration | string | Yes | `3` to `15` seconds |
+  | aspect_ratio | string | Yes* | `16:9`, `9:16`, `1:1` |
+  | mode | string | Yes | `std` (720p), `pro` (1080p) |
+  | multi_shots | boolean | Yes | Multi-shot storytelling |
+  | multi_prompt | array | No* | [{prompt, duration}] max 5 shots (*required when multi_shots=true) |
+  | kling_elements | array | No | Character consistency elements |
+- **Pricing**: std 20 cr/s, pro 27 cr/s (+10 cr/s with audio)
+
+### Sora 2 (OpenAI)
+- **Model IDs**: `sora-2-text-to-video`, `sora-2-image-to-video`, `sora-2-pro-text-to-video`, `sora-2-pro-image-to-video`, `sora-2-characters`, `sora-2-characters-pro`, `sora-watermark-remover`, `sora-2-pro-storyboard`
+- **Endpoint**: `POST /api/v1/jobs/createTask`
+- **Text-to-Video Parameters**:
+  | Param | Type | Required | Values |
+  |-------|------|----------|--------|
+  | prompt | string | Yes | Max 10,000 chars |
+  | aspect_ratio | string | No | `portrait`, `landscape` |
+  | n_frames | string | No | `10`, `15` |
+  | remove_watermark | boolean | No | Remove watermark |
+  | character_id_list | string[] | No | Max 5 character IDs |
+
+### Wan Series (Alibaba)
+- **Model IDs**: `wan/2-6-text-to-video`, `wan/2-6-image-to-video`, `wan/2-6-video-to-video`, `wan/2-6-flash-image-to-video`, `wan/2-6-flash-video-to-video`
+- **Endpoint**: `POST /api/v1/jobs/createTask`
+- **Common Parameters**:
+  | Param | Type | Required | Values |
+  |-------|------|----------|--------|
+  | prompt | string | Yes | 2-1500 chars |
+  | image_urls | string[] | Varies | Reference images |
+  | duration | string | No | `5`, `10`, `15` |
+  | resolution | string | No | `720p`, `1080p` |
+  | audio | boolean | Yes | Audio generation |
+  | multi_shots | boolean | No | Multiple shots |
+
+### Hailuo Series
+- **Model IDs**: `hailuo/2.3-pro-image-to-video`, `hailuo/2.3-standard-image-to-video`, `hailuo/pro-text-to-video`, etc.
+- **Endpoint**: `POST /api/v1/jobs/createTask`
+
+### Bytedance Video (Seedance)
+- **Model IDs**: `bytedance/seedance-1.5-pro`, `bytedance/v1-pro-image-to-video`, `bytedance/v1-lite-text-to-video`, etc.
+- **Endpoint**: `POST /api/v1/jobs/createTask`
+
+---
+
+## AUDIO MODELS
+
+### Suno V4 (Music)
+- **Endpoint**: `POST /api/v1/generate/music`
+- **Capabilities**: Generate, extend, cover, stems, MIDI, lyrics, music video
+
+### ElevenLabs
+- **Model IDs**: `elevenlabs/text-to-speech-multilingual-v2`, `elevenlabs/turbo-2.5`, `elevenlabs/text-to-dialogue-v3`, `elevenlabs/speech-to-text`, `elevenlabs/sound-effect-v2`, `elevenlabs/audio-isolation`
+- **Endpoint**: `POST /api/v1/jobs/createTask`
+
+---
+
+## CHAT/LLM MODELS
+
+- `gemini/3-pro`, `gemini/2.5-flash`, `gemini/2.5-pro`
+- `gpt/5-2`
+- `claude/sonnet-4.5`, `claude/opus-4.5`
+
+---
+
+## COMMON ENDPOINTS
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/api/v1/chat/credit` | GET | Check remaining credits |
+| `/api/v1/jobs/recordInfo?taskId={id}` | GET | Market task status |
+| `/api/v1/common/download-url` | POST | Get direct download URL (20min valid) |
+
+### Task States (Market unified)
+- `waiting` → `queuing` → `generating` → `success` / `fail`
+
+### Task States (Dedicated endpoints)
+- `successFlag`: 0=generating, 1=success, 2=failed, 3=generation_failed
+
+## FILE UPLOAD
+
+| Method | Endpoint | Best For |
+|--------|----------|----------|
+| Base64 | `POST https://kieai.redpandaai.co/api/file-base64-upload` | Small files ≤10MB |
+| Stream | `POST https://kieai.redpandaai.co/api/file-stream-upload` | Large local files |
+| URL | `POST https://kieai.redpandaai.co/api/file-url-upload` | Remote files ≤100MB |
+
+Uploaded files expire after 3 days. Generated files expire after 14 days.