--- name: pp-kie description: "Printing Press CLI for Kie. Unified API for Kie.ai's AI generation platform: image, video, music, and chat models, plus account and file utilities." author: "Kelvin Cushman" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - kie-pp-cli --- # Kie — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `kie-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first: 1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows: ```bash npx -y @mvanhorn/printing-press-library install kie --cli-only ``` 2. Verify: `kie-pp-cli --version` 3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill. If the `npx` install fails before this CLI has a public-library category, install Node or use the category-specific Go fallback after publish. If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds. Unified API for Kie.ai's AI generation platform: image, video, music, and chat models, plus account and file utilities. Async generation endpoints return a taskId; poll the matching record-info/get-details endpoint (or use a callBackUrl) to retrieve results. ## Command Reference **aleph** — Manage aleph - `kie-pp-cli aleph generate-video` — Using Runway Aleph model for video-to-video conversion to create dynamic AI-generated videos ## Overview Transform - `kie-pp-cli aleph get-video-details` — Retrieving comprehensive information about Runway Alpeh video generation tasks ## Overview Retrieve detailed **chat** — Manage chat - `kie-pp-cli chat` — Get the current credit balance available in your account. **claude** — Manage claude - `kie-pp-cli claude` — When `stream: true` is set in the request, the API returns responses as server-sent events (SSE). **codex** — Manage codex - `kie-pp-cli codex` — GPT 5. **common** — Manage common - `kie-pp-cli common` — Convert generated file URLs into downloadable temporary links. Only supports files generated by kie.ai services. **file-base64-upload** — Manage file base64 upload - `kie-pp-cli file-base64-upload` — Uploaded files are temporary and will be automatically deleted after 24h ### Features * Supports Base64 encoded data **file-stream-upload** — Manage file stream upload - `kie-pp-cli file-stream-upload` — Uploaded files are temporary and will be automatically deleted after 24h ### Features * Supports binary stream upload **file-url-upload** — Manage file url upload - `kie-pp-cli file-url-upload` — Uploaded files are temporary and will be automatically deleted after 24h ### Features * Supports HTTP and HTTPS file **flux** — Manage flux - `kie-pp-cli flux generate-or-edit-image` — Create a new image generation or editing task using the Flux Kontext AI model. ### Usage Modes 1. - `kie-pp-cli flux get-image-details` — Query the status and results of an image generation or editing task. **gemini** — Manage gemini - `kie-pp-cli gemini 3-5-flash` — The Gemini endpoint returns streaming chunks from `streamGenerateContent`. - `kie-pp-cli gemini 3-6-flash` — The Gemini endpoint returns streaming chunks from `streamGenerateContent`. - `kie-pp-cli gemini 3-flash-v1betamodels` — The Gemini endpoint returns streaming chunks from `streamGenerateContent`. **gemini-2-5-flash** — Manage gemini 2 5 flash - `kie-pp-cli gemini-2-5-flash chat-completions` — When `stream: true` is set in the request, the API returns responses as server-sent events (SSE) with `Content-Type **gemini-2-5-pro** — Manage gemini 2 5 pro - `kie-pp-cli gemini-2-5-pro chat-completions` — When `stream: true` is set in the request, the API returns responses as server-sent events (SSE) with `Content-Type **gemini-3-1-pro** — Manage gemini 3 1 pro - `kie-pp-cli gemini-3-1-pro` — When `stream: true` is set in the request, the API returns responses as server-sent events (SSE) with `Content-Type **gemini-3-5-flash-openai** — Manage gemini 3 5 flash openai - `kie-pp-cli gemini-3-5-flash-openai` — When `stream: true` is set in the request, the API returns responses as server-sent events (SSE) with `Content-Type **gemini-3-6-flash-openai** — Manage gemini 3 6 flash openai - `kie-pp-cli gemini-3-6-flash-openai` — When `stream: true` is set in the request, the API returns responses as server-sent events (SSE) with `Content-Type **gemini-3-flash** — Manage gemini 3 flash - `kie-pp-cli gemini-3-flash` — When `stream: true` is set in the request, the API returns responses as server-sent events (SSE) with `Content-Type **gemini-3-pro** — Manage gemini 3 pro - `kie-pp-cli gemini-3-pro chat-completions` — When `stream: true` is set in the request, the API returns responses as server-sent events (SSE) with `Content-Type **generate** — Manage generate - `kie-pp-cli generate add-instrumental` — Generate instrumental accompaniment based on uploaded audio files. - `kie-pp-cli generate add-vocals` — Generate music with vocals based on uploaded audio files. - `kie-pp-cli generate extend-music` — Extend or modify existing music by creating a continuation based on a source audio track. - `kie-pp-cli generate get-music-details` — Retrieve detailed information about a music generation task. - `kie-pp-cli generate get-timestamped-lyrics` — Retrieve synchronized lyrics with precise timestamps for music tracks. - `kie-pp-cli generate mashup` — Create remix music using AI models by combining multiple audio tracks. - `kie-pp-cli generate music` — Generate music with or without lyrics using AI models. - `kie-pp-cli generate persona` — Create a personalized music Persona based on generated music, giving the music a unique identity and characteristics. - `kie-pp-cli generate replace-section` — Replace a specific time segment within existing music. - `kie-pp-cli generate sounds` — Used for creating a sound generation task (Sounds Task). - `kie-pp-cli generate upload-and-cover-audio` — This API creates a cover version of an audio track by transforming it into a new style while retaining its core melody. - `kie-pp-cli generate upload-and-extend-audio` — This API extends audio while preserving the original style, generating a longer and seamless audio track. **gpt-5-2** — Manage gpt 5 2 - `kie-pp-cli gpt-5-2` — GPT-5-2 API is a next-generation multimodal model with exceptional reasoning capabilities **gpt4o-image** — Manage gpt4o image - `kie-pp-cli gpt4o-image generate-4o-image` — Create a new 4o Image generation task. Generated images are stored for 14 days, after which they expire. - `kie-pp-cli gpt4o-image get-4o-image-details` — Query 4o Image generation task details using taskId, including generation status, parameters and results. - `kie-pp-cli gpt4o-image get-4o-image-download-url` — Convert an image URL to a direct download URL. This helps solve cross-domain issues when downloading images directly. **grok** — Manage grok - `kie-pp-cli grok responses` — GPT Grok 4. **kie-ai-jobs** — Manage kie ai jobs - `kie-pp-cli kie-ai-jobs market-create-task` — Unified entry point for every model in the Kie.ai Market catalog (image, video, and audio generation). - `kie-pp-cli kie-ai-jobs market-query-task` — Query the status and results of any task created in the Market models. **lyrics** — Manage lyrics - `kie-pp-cli lyrics generate` — Generate creative lyrics content based on a text prompt. - `kie-pp-cli lyrics get-details` — Retrieve detailed information about a lyrics generation task. **midi** — Manage midi - `kie-pp-cli midi generate` — Convert separated audio tracks into MIDI format with detailed note information for each instrument. - `kie-pp-cli midi get-details` — Retrieve detailed information about a MIDI generation task including complete note data for all detected instruments. **mp4** — Manage mp4 - `kie-pp-cli mp4 create-music-video` — Create a video with visualizations based on your generated music track. - `kie-pp-cli mp4 get-music-video-details` — Retrieve detailed information about a music video generation task. **omni** — Manage omni - `kie-pp-cli omni gemini-audio` — Use this endpoint to create a new audio. - `kie-pp-cli omni gemini-character` — - `image_urls` supports only `1` image **responses** — Manage responses - `kie-pp-cli responses` — GPT Codex API is a multimodal chat-completions style endpoint that accepts structured input arrays **runway** — Manage runway - `kie-pp-cli runway extend-ai-video` — Extend existing AI-generated videos to create longer sequences. - `kie-pp-cli runway generate-ai-video` — Create dynamic AI-generated videos from text prompts or image references. - `kie-pp-cli runway get-ai-video-details` — Retrieve comprehensive information about an AI-generated video task. **style** — Manage style - `kie-pp-cli style` — Boost Music Style **suno** — Manage suno - `kie-pp-cli suno generate-cover` — Generate personalized cover images based on original music tasks. - `kie-pp-cli suno get-cover-details` — Get detailed information about Cover generation tasks. **veo** — Manage veo - `kie-pp-cli veo extend-veo3-1-video` — Extend an existing Veo 3.1 video by generating new content based on the original video and a text prompt. - `kie-pp-cli veo generate-veo3-1-video` — Our **Veo 3.1 Generation API** is more than a direct wrapper around Google's baseline. - `kie-pp-cli veo get-veo3-1-1080p-video` — Get the high-definition 1080P version of a Veo 3.1 video generation task. - `kie-pp-cli veo get-veo3-1-4k-video` — Get the ultra-high-definition 4K version of a Veo 3.1 video generation task. - `kie-pp-cli veo get-veo3-1-video-details` — This endpoint is the authoritative source of truth for querying the execution status and final results of all Veo 3. **vocal-removal** — Manage vocal removal - `kie-pp-cli vocal-removal get-vocal-separation-details` — Retrieve detailed information about a vocal separation task. - `kie-pp-cli vocal-removal separate-vocals` — Use advanced audio processing technology to separate music into vocals, accompaniment **voice** — Manage voice - `kie-pp-cli voice suno-check` — Check whether a generated Suno custom voice is available. - `kie-pp-cli voice suno-generate` — Generate a custom Suno Voice after the user reads the validation phrase. - `kie-pp-cli voice suno-record-info` — Query the custom Suno Voice generation result. - `kie-pp-cli voice suno-regenerate` — Regenerate the validation phrase for an existing Suno Voice task. - `kie-pp-cli voice suno-validate` — Generate a validation phrase for the Suno Voice custom voice workflow. - `kie-pp-cli voice suno-validate-info` — Query the validation phrase generation result for a Suno Voice task. **wav** — Manage wav - `kie-pp-cli wav convert-to` — Convert an existing music track to high-quality WAV format. - `kie-pp-cli wav get-details` — Retrieve detailed information about a WAV format conversion task. ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash kie-pp-cli which "" ``` `which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query. ## Auth Setup Run `kie-pp-cli auth setup` for the URL and steps to obtain a token (add `--launch` to open the URL). Then store it: ```bash kie-pp-cli auth set-token YOUR_TOKEN_HERE ``` Or set `KIE_BEARER_AUTH` as an environment variable. Run `kie-pp-cli doctor` to verify setup. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color --yes`. - **Pipeable** — JSON on stdout, errors on stderr - **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs: ```bash kie-pp-cli aleph generate-video --prompt example-value --agent --select id,name,status ``` - **Previewable** — `--dry-run` shows the request without sending - **Offline-friendly** — sync/search commands can use the local SQLite store when available - **Non-interactive** — never prompts, every input is a flag - **Explicit retries** — use `--idempotent` only when an already-existing create should count as success ### Response envelope Commands that read from the local store or the API wrap output in a provenance envelope: ```json { "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."}, "results": } ``` Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal AND no machine-format flag (`--json`, `--csv`, `--compact`, `--quiet`, `--plain`, `--select`) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout. ## Paths and state Agents should treat the CLI's path resolver as part of the runtime contract: - Use `--home ` for one invocation, or set `KIE_HOME=` to relocate all four path kinds under one root. - Use per-kind env vars only when a specific kind must diverge: `KIE_CONFIG_DIR`, `KIE_DATA_DIR`, `KIE_STATE_DIR`, `KIE_CACHE_DIR`. - Resolution order is per-kind env var, `--home`, `KIE_HOME`, XDG (`XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`), then platform defaults. - `config` contains settings like `config.toml` and profiles. `data` contains `credentials.toml`, `data.db`, cookies, and auth sidecars. `state` contains persisted queries, jobs, and `teach.log`. `cache` contains regenerable HTTP/cache files. - Stored secrets live in `credentials.toml` under the data dir. Existing legacy `config.toml` secrets are read for compatibility and leave `config.toml` on the first auth write. - Run `kie-pp-cli doctor --fail-on warn` to surface path and credential-location warnings. `agent-context` exposes a schema v4 `paths` block for agents that need the resolved dirs. - For MCP, pass relocation through the MCP host config. The MCP binary does not inherit CLI flags: ```json { "mcpServers": { "kie": { "command": "kie-pp-mcp", "env": { "KIE_HOME": "/srv/kie" } } } } ``` Fleet precedence: an inherited per-kind env var overrides an explicit `--home` for that kind. Use `KIE_HOME` or per-kind vars as durable fleet levers, and use `--home` only for a single invocation. Relocation is not reversible by unsetting env vars; move files manually before clearing `KIE_HOME`, or `doctor` will not find credentials left under the former root. ## Automatic learning This CLI ships a self-capturing learning loop. The CLI does its own bookkeeping: every invocation is journaled locally, a failed flag followed by a corrected retry auto-derives a `flag_alias` candidate, and a `teach` on a query family without a playbook auto-synthesizes a `playbook_candidate` from the session's journal. Your job is judgment only: `recall` first, act on surfaced candidates, `teach` the final answer, `playbook amend` when you observe a correction. You never record failures by hand. ### Step 1: `recall` before any discovery Before list/search/drill commands on a new user question, run: ```bash kie-pp-cli recall "" --agent ``` The response envelope: ```json { "query": "...", "normalized": "", "query_entities": ["..."], "found": true | false, "match_score": 0.0, "results": [ { "resource_id": "...", "resource_type": "...", "venue": "...", "confidence": 2, "entity_match": "exact|partial|unknown", "source": "taught|preseed|pattern", "warnings": ["..."] } ], "mismatches": [ /* only when --debug-mismatches */ ], "warnings": [ /* top-level */ ], "candidates": [ { "id": 12, "class": "flag_alias | playbook_candidate", "summary": "...", "sightings": 3, "last_seen": "...", "rationale": "...", "next_action": ["", "kie-pp-cli learnings confirm 12"] } ], "playbook": { "query_family": "...", "playbook": { "steps": [ { "cmd": "", "purpose": "..." } ], "entity_slots": ["$ENTITY"], "expected_tool_calls": 3 }, "slots_resolved": { "$ENTITY": { "token": "", "canonical": "" } }, "notes": "" }, "notes": "" } ``` Empty-store short-circuit: if the store has no learnings, playbooks, or candidates yet (recall finds nothing and `learnings list` and `learnings candidates` are both empty), skip recall for the rest of this session instead of taxing every query; resume recall-first once something has been taught. ### Step 2: decision tree Read `candidates`, `playbook`, `notes`, `results[0]`, and warnings in that order: ``` if Candidates present (warnings include "candidates_present"): -> candidates are try-then-confirm, never facts. Follow each candidate's two-step next_action verbatim: run the trial command first, then run `learnings confirm ` only after the trial verified the behavior. Reject a wrong candidate with `learnings reject `. -> NEVER re-teach something recall surfaced as a candidate; confirm or reject that candidate instead of teaching a duplicate. -> candidates ride alongside playbooks and resource hits, not instead of them; continue with the branches below after acting on them. if Playbook present: -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose) -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries for the entity slot tokens. If a step's slot is unresolved, fall back to discovery for that step only. -> the Playbook's expected_tool_calls is a budget; if you find yourself running materially more, record the divergence via `kie-pp-cli playbook amend` at end-of-session. elif Notes present (no Playbook): -> read Notes verbatim before any discovery step; they carry known gotchas for this query family even when no structured choreography exists yet. elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2: -> skip discovery; fetch live data for Results[*].ResourceID in parallel elif Found AND Results[0].EntityMatch == "partial": -> candidate hint, NOT a hit; read the resource title to validate before trusting elif (any row in Mismatches[] when --debug-mismatches was passed): -> treat as cold start; the stored learning is for a different entity (different canonical resolved from query_entities) else: // Found == false, no playbook, no notes -> cold start; run discovery normally; teach the answer afterward (Step 4). If the family has no playbook yet, that teach auto-synthesizes a playbook candidate from this session's journal - you do not need to record one by hand. ``` Playbook and Notes are orthogonal to the per-resource path. A recall response can carry both a Playbook AND a `Results[]` hit - use both: the Playbook tells you which choreography to run; the resource