kie-ai

# kie.ai API Wrapper Unified access to multiple AI models through kie.ai's API. Generate images, videos, and music at 30-80% lower cost than official APIs. ## Features - 🎨 **Image Generation**: Nano Banana Pro (Gemini 3 Pro), Flux, 4o-image - 📤 **Google Drive Upload**: Optional automatic upload to Drive folder - 📊 **Usage Tracking**: Local task history and cost estimation - 💾 **Local Storage**: All files saved to `images/` before optional upload - 🎬 **Video Generation** *(coming soon)*: Veo 3.1, Runway Gen-4 Aleph - 🎵 **Music Generation** *(coming soon)*: Suno V4/V4.5 ## Quick Start ```bash # Generate an image ./kie-ai.sh generate-image "A serene Japanese garden at sunset" # With custom options ./kie-ai.sh generate-image "Cyberpunk city" --resolution 2K --aspect 16:9 # Upload to Google Drive ./kie-ai.sh generate-image "Space nebula" --upload-drive # Check usage ./kie-ai.sh balance ``` ## Installation ### Prerequisites 1. **kie.ai API Key**: - Sign up at https://kie.ai - Get API key from dashboard - Add to `~/.openclaw/openclaw.json`: ```json "env": { "vars": { "KIE_API_KEY": "your-key-here" } } ``` 2. **(Optional) Maton API Key** for Google Drive uploads: - Sign up at https://maton.ai - Get API key from https://maton.ai/settings - Set up Google Drive connection at https://ctrl.maton.ai - Add to config: ```json "MATON_API_KEY": "your-maton-key" ``` ### Setup ```bash # Clone to ~/src cd ~/src git clone https://github.com/jon-xo/kie-ai-skill.git cd kie-ai-skill # Make executable chmod +x kie-ai.sh lib/*.py # Create symlink for OpenClaw ln -s ~/src/kie-ai-skill ~/.openclaw/workspace/skills/kie-ai-skill # Test it ./kie-ai.sh generate-image "test image" ``` ## Configuration ### Google Drive Upload (Optional) ```bash # View/edit config ./kie-ai.sh config # Edit config.json { "drive": { "enabled": true, "folder_id": "YOUR_GOOGLE_DRIVE_FOLDER_ID" } } ``` Get your folder ID from the Google Drive URL: ``` https://drive.google.com/drive/folders/1abc...xyz ^^^^ this part ``` ## Commands ### generate-image Generate images with various models. ```bash ./kie-ai.sh generate-image <prompt> [options] Options: --model <name> Model: nano-banana-pro (default), google/nano-banana, flux-kontext, 4o-image --resolution <res> Resolution: 1K (default), 2K, 4K --aspect <ratio> Aspect ratio: 1:1 (default), 16:9, 9:16, 4:3, etc. --upload-drive Upload to Google Drive after generation (requires config) ``` **Examples:** ```bash # Basic generation ./kie-ai.sh generate-image "A red apple on a wooden table" # High resolution ./kie-ai.sh generate-image "Mountain landscape" --resolution 4K # Widescreen ./kie-ai.sh generate-image "Cinematic scene" --resolution 2K --aspect 16:9 # 16-bit pixel art ./kie-ai.sh generate-image "Cyberpunk lobster, 16-bit pixel art, no text" --aspect 16:9 # Generate and upload ./kie-ai.sh generate-image "Abstract art" --upload-drive ``` ### balance Check credit usage and remaining balance. ```bash ./kie-ai.sh balance ``` Shows: - Link to web UI for actual balance - Local task history - Estimated credit consumption - USD equivalent ### status Show active/pending tasks. ```bash ./kie-ai.sh status ``` ### models List available models and pricing. ```bash ./kie-ai.sh models ``` ### config View/configure Google Drive upload settings. ```bash ./kie-ai.sh config ``` ## Pricing Approximate costs (kie.ai vs official): | Model | kie.ai | Official | Savings | |-------|--------|----------|---------| | Nano Banana Pro | ~18-24 credits ($0.09-$0.12) | $0.15 | 20-40% | | Veo 3.1 | Variable | N/A | — | | Flux Kontext | ~50 credits ($0.25) | $0.30 | ~17% | | Suno V4 | Variable | $0.10/track | Comparable | **Credit pricing:** ~$0.005 per credit (1,000 credits = $5) Check exact costs at: https://docs.kie.ai/pricing ## File Storage Generated files are saved to the `images/` directory (gitignored): ``` ~/src/kie-ai-skill/images/ 2026-02-11-12-05-01-1.png 2026-02-11-12-09-56-1.png ... ``` Format: `YYYY-MM-DD-HH-MM-SS-{index}.png` **Retention:** - Local: Forever (or until you delete) - kie.ai CDN: 14 days - Google Drive: Forever (if uploaded) ## Task State Tasks are tracked in: ``` ~/src/kie-ai-skill/.task-state.json ``` Used for: - Resume interrupted tasks - Usage tracking - Preventing duplicate submissions ## Available Models ### Image Generation - `nano-banana-pro` - Gemini 3 Pro Image (1K/2K/4K) - `google/nano-banana` - Gemini 2.5 Flash Image (cheaper) - `flux-kontext` - Flux by Black Forest Labs - `4o-image` - OpenAI GPT-4o Image ### Video Generation *(coming soon)* - `veo-3.1` - Google Veo 3.1 (cinematic) - `veo-3.1-fast` - Veo 3.1 Fast (cheaper) - `runway-aleph` - Runway Gen-4 Aleph ### Music Generation *(coming soon)* - `suno-v4` - Suno V4 (up to 8min) - `suno-v4.5` - Suno V4.5 Plus See https://docs.kie.ai for full list. ## Troubleshooting ### "KIE_API_KEY not set" Add to `~/.openclaw/openclaw.json`: ```json "env": { "vars": { "KIE_API_KEY": "your-key-here" } } ``` ### "Credits insufficient" Top up at: https://kie.ai/billing ### "MATON_API_KEY not set" (Drive upload) 1. Sign up at https://maton.ai 2. Add `MATON_API_KEY` to openclaw.json 3. Create Google Drive connection at https://ctrl.maton.ai ### "Drive upload failed" 1. Check MATON_API_KEY is set 2. Verify Google Drive connection is active at https://ctrl.maton.ai 3. Ensure folder_id in config.json is correct 4. Try generating without `--upload-drive` first ## Integration with OpenClaw Use via exec or directly in OpenClaw agent conversations: ```bash # From OpenClaw chat Generate a cyberpunk city image with kie.ai # The agent will run: cd ~/src/kie-ai-skill && ./kie-ai.sh generate-image "cyberpunk city" ``` ## Security ### Environment Variables | Variable | Required | Purpose | |---|---|---| | `KIE_API_KEY` | Yes | Authenticates all requests to `api.kie.ai` | | `MATON_API_KEY` | No | Authenticates Google Drive uploads via `gateway.maton.ai` | ### External Endpoints | Endpoint | Method | Data Sent | Used By | |---|---|---|---| | `https://api.kie.ai/api/v1/jobs/createTask` | POST | prompt, model, resolution, aspect ratio | `generate-image.py` | | `https://api.kie.ai/api/v1/jobs/recordInfo` | GET | task ID | `generate-image.py`, `watch_task.py` | | `https://api.kie.ai/api/v1/chat/credit` | GET | — (auth header only) | `balance.py` | | `https://gateway.maton.ai/google-drive/upload/...` | POST | image file bytes, filename | `upload-drive.py` (optional) | ### Data Leaving This Machine - **Prompt text** is sent to `api.kie.ai` to generate images. - **Generated image files** are sent to `gateway.maton.ai` only when `--upload-drive` is explicitly passed. - **API keys** are transmitted as `Authorization: Bearer` headers and are never logged or written to disk by this skill. - No telemetry, analytics, or usage data is collected by this skill itself. ### Trust Statement This skill sends data to two third-party services: [kie.ai](https://kie.ai) for AI generation and [maton.ai](https://maton.ai) as an OAuth gateway for Google Drive. Review their respective privacy policies before use. Drive upload is strictly opt-in via `--upload-drive`. ### Autonomous Invocation This skill can be invoked autonomously by an OpenClaw agent when asked to generate images. It does not execute autonomously on its own — it must be called explicitly. To prevent autonomous invocation, remove the skill symlink from your OpenClaw workspace. ## Links - **kie.ai Dashboard**: https://kie.ai - **Documentation**: https://docs.kie.ai - **Pricing**: https://docs.kie.ai/pricing - **Logs/Balance**: https://kie.ai/logs - **Billing**: https://kie.ai/billing - **Maton (for Drive)**: https://maton.ai - **GitHub Repo**: https://github.com/jon-xo/kie-ai-skill ## License MIT ## Support Issues: https://github.com/jon-xo/kie-ai-skill/issues