# kie-ai

> Use when integrating with Kie.ai API for image/video/music generation, writing async task-based code with polling, or when user mentions kie, seedream, veo, suno, runway, kling, hailuo, flux

- Author: ungurenko
- Repository: ungurenko/claude-config
- Version: 20260127095846
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/ungurenko/claude-config
- Web: https://mule.run/skillshub/@@ungurenko/claude-config~kie-ai:20260127095846

---

---
name: kie-ai
description: Use when integrating with Kie.ai API for image/video/music generation, writing async task-based code with polling, or when user mentions kie, seedream, veo, suno, runway, kling, hailuo, flux
---

# Kie.ai API Reference

## Overview

**Kie.ai** — агрегатор AI-моделей для генерации изображений, видео и музыки. **НЕ OpenAI-совместимый** — асинхронный REST API с polling/webhook.

## Quick Reference

| Parameter | Value |
|-----------|-------|
| **Base URL** | `https://api.kie.ai` |
| **Auth Header** | `Authorization: Bearer API_KEY` |
| **Model Format** | `provider/model` (e.g., `bytedance/seedream`) |
| **Pricing** | 1 credit ≈ $0.005 |

## Endpoints

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/api/v1/jobs/createTask` | POST | Create generation task |
| `/api/v1/jobs/recordInfo?taskId=X` | GET | Query task status |
| `/api/v1/chat/credit` | GET | Check credits |
| `/api/v1/common/download-url` | POST | Get temp download URL |

## Async Workflow

```
createTask → taskId → poll recordInfo → state: success → parse resultJson
```

**Task States:** `waiting` → `queuing` → `generating` → `success` | `fail`

## Code Example (TypeScript)

```typescript
interface KieTaskResponse {
  code: number;
  msg: string;
  data: { taskId: string };
}

interface KieRecordResponse {
  code: number;
  data: {
    taskId: string;
    state: 'waiting' | 'queuing' | 'generating' | 'success' | 'fail';
    resultJson: string; // JSON string: {"resultUrls": ["..."]}
    failMsg: string;
  };
}

const KIE_API = 'https://api.kie.ai';
const API_KEY = process.env.KIE_API_KEY!;

async function createTask(model: string, input: Record<string, unknown>, callBackUrl?: string) {
  const res = await fetch(`${KIE_API}/api/v1/jobs/createTask`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ model, input, callBackUrl }),
  });
  const data: KieTaskResponse = await res.json();
  if (data.code !== 200) throw new Error(data.msg);
  return data.data.taskId;
}

async function pollResult(taskId: string, maxAttempts = 60, intervalMs = 5000) {
  for (let i = 0; i < maxAttempts; i++) {
    const res = await fetch(`${KIE_API}/api/v1/jobs/recordInfo?taskId=${taskId}`, {
      headers: { 'Authorization': `Bearer ${API_KEY}` },
    });
    const { data }: KieRecordResponse = await res.json();

    if (data.state === 'success') {
      return JSON.parse(data.resultJson).resultUrls as string[];
    }
    if (data.state === 'fail') {
      throw new Error(data.failMsg);
    }
    await new Promise(r => setTimeout(r, intervalMs));
  }
  throw new Error('Timeout');
}

// Usage
async function generateImage(prompt: string) {
  const taskId = await createTask('bytedance/seedream', {
    prompt,
    image_size: 'square_hd',
  });
  return pollResult(taskId);
}
```

## Bash Quick Test

```bash
# Create task
curl -X POST "https://api.kie.ai/api/v1/jobs/createTask" \
  -H "Authorization: Bearer $KIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"bytedance/seedream","input":{"prompt":"A cat astronaut"}}'

# Poll result (replace TASK_ID)
curl "https://api.kie.ai/api/v1/jobs/recordInfo?taskId=TASK_ID" \
  -H "Authorization: Bearer $KIE_API_KEY"
```

## Popular Models

**Image:** `bytedance/seedream` (v3/v4), `flux-2/pro`, `google/imagen4`, `ideogram/v3`, `grok-imagine/text-to-image`

**Video:** `kling/v2-1-pro`, `sora2/pro`, `hailuo/2-3-pro`, `wan/2-2-turbo`, `bytedance/v1-pro`

**Audio:** `elevenlabs/text-to-speech`, `suno/v4`

Full list: [kie.ai/market](https://kie.ai/market)

## Common Mistakes

| Error | Cause | Fix |
|-------|-------|-----|
| 401 Unauthorized | Invalid API key | Check key at kie.ai/api-key |
| 402 Insufficient Credits | No credits | Top up at kie.ai |
| 200 but no result | Didn't poll | Use `recordInfo` endpoint |
| `resultJson` is string | Forgot JSON.parse | `JSON.parse(data.resultJson)` |
| Timeout | Long generation | Increase maxAttempts or use webhook |
| 429 Rate Limited | >20 req/10s | Add delay between requests |

## Webhook (Alternative to Polling)

```typescript
// In createTask, add callBackUrl:
await createTask('bytedance/seedream', { prompt }, 'https://your-server.com/webhook');

// Your webhook endpoint receives POST:
// { taskId, state, resultJson, ... }
```

## Links

- Market: [kie.ai/market](https://kie.ai/market)
- Pricing: [kie.ai/pricing](https://kie.ai/pricing)
- API Keys: [kie.ai/api-key](https://kie.ai/api-key)
- Logs: [kie.ai/logs](https://kie.ai/logs)
- Docs: [docs.kie.ai](https://docs.kie.ai)