# 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.
