mcpField
K
kie-ai

kie-ai

github.com/thepexcelCreative & media39 installs
Repository

About kie-ai

A skill for generating images and videos through Kie.ai REST APIs, including Grok Imagine and Veo3 models. It documents task creation, status polling, file uploads, downloads, and batch-generation precautions for creative workflows.

Key features

  1. 01Grok Imagine image generation
  2. 02Veo3 video generation
  3. 03Task status polling
  4. 04Image upload and result downloads
  5. 05Batch generation guidance

Use cases

  1. 01Creating images from text prompts
  2. 02Styling or editing a reference image
  3. 03Generating video from text or uploaded images
  4. 04Running multiple generation requests

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/thepexcel/agent-skills --skill kie-ai

After installing, type/kie-aiin Claude Code to confirm it loaded.

Details

From the project README

kie-ai — Grok Imagine ผ่าน Kie.ai API

Gen image/video ผ่าน Kie.ai REST API — proxy สำหรับ Grok Imagine models

Path Shortcuts

OUT    = D:/ClaudeMediaGen/output-fal   # ใช้ร่วมกับ fal output
BASE   = https://api.kie.ai/api/v1/jobs

Environment Variables

Varที่อยู่วิธีอ่าน
KIE_API_KEYWindows User Envos.environ["KIE_API_KEY"] (set via setx หรือ [Environment]::SetEnvironmentVariable)

Model Selection

Model IDTypeBest ForOutput
grok-imagine/text-to-imagetext2imgAesthetic/cinematic images, Thai prompt ได้ดี3 รูป/request
grok-imagine/image-to-imageimg2imgแก้ไข/ปรับ style จากรูปต้นแบบTBD
grok-imagine/image-to-videoimg2vidสร้างวีดีโอจากรูปนิ่งTBD
grok-imagine/upscaleupscaleเพิ่ม resolution วีดีโอTBD
veo3_fastvideoVideo fast, รองรับ i2v (REFERENCE_2_VIDEO)video + audio
veo3_qualityvideoVideo quality สูงสุดvideo + audio
veo3_litevideoVideo ประหยัดสุดvideo + audio

หมายเหตุ: text-to-image + veo3_fast ทดสอบแล้ว ใช้งานได้จริง / model อื่นๆ มีใน docs แต่ยังไม่ได้ทดสอบ Veo3 ใช้คนละ endpoint — ดู section "Veo3 Video Generation" และ "API Endpoints Summary" ด้านล่าง

Aspect Ratios

Valueใช้เมื่อ
2:3Portrait (default สำหรับรูปคน)
3:2Landscape
1:1Square
16:9Wide cinematic
9:16Story/Reels format

API Flow — 3 ขั้นตอน

1. Create Task
POST {BASE}/createTask
Authorization: Bearer <KIE_API_KEY>
Content-Type: application/json

Body:
{
  "model": "grok-imagine/text-to-image",
  "input": {
    "prompt": "...",
    "aspect_ratio": "2:3"
  }
}

Response: { "code": 200, "data": { "taskId": "..." } }
  • ตรวจ code == 200 ก่อน ถ้าไม่ใช่ = error
  • เก็บ taskId ไว้ poll
2. Poll Task Status
GET {BASE}/recordInfo?taskId=<taskId>
Authorization: Bearer <KIE_API_KEY>

Task States:

StateความหมายAction
waitingอยู่ในคิวรอต่อ
queuingอยู่ในคิวรอต่อ
generatingกำลัง genรอต่อ
successเสร็จแล้วดึง URL
failล้มเหลวอ่าน failMsg + failCode

Poll strategy: ทุก 5 วินาที, timeout 5 นาที (60 รอบ)

เมื่อ success:

  • data.resultJson เป็น JSON string → ต้อง parse อีกรอบ
  • ภายในมี resultUrls: [url1, url2, url3] — ได้ 3 รูปต่อ 1 request
3. Download Images

สำคัญ: URL ต้องใส่ headers พิเศษ ไม่งั้นจะโดน block

Headers สำหรับ download:
  User-Agent: Mozilla/5.0
  Referer: https://kie.ai/

Naming convention:

kie_grok_{taskId_last8}_{index}.jpg

Output directory: D:/ClaudeMediaGen/output-fal/

Prompt Rules

Grok prompt syntax rules have moved to the shared model-card. See grok-image.md for:

  • Hybrid prompt strategy (English + Thai)
  • Forbidden words
  • Subject short / Scene long rule
  • ห้ามบอก body size

Implementation Guide

สร้าง gen script ใน Python
  1. อ่าน API key จาก os.environ["KIE_API_KEY"] (Windows User Env — set ครั้งเดียวทั่วเครื่อง)
  2. Create task → POST /createTask → เก็บ taskId
  3. Poll → GET /recordInfo?taskId= → วน loop ทุก 5s จนได้ success หรือ fail
  4. Parse result → data.resultJson เป็น string → json.loads() → resultUrls
  5. Download → ใส่ User-Agent + Referer headers → save เป็น .jpg
  6. สร้าง .txt คู่ → save prompt text ข้างรูปทุกครั้ง (เพื่อ traceability)
Batch Generation
  • ส่ง request หลายตัวพร้อมกันได้ (ไม่มี rate limit ที่ทดสอบเจอ)
  • แต่ละ request ได้ 3 รูป → 10 requests = 30 รูป
  • ใช้ run_in_background: true สำหรับ parallel gen ใน Claude Code
Error Handling
  • code != 200 จาก createTask → แสดง error ทั้ง response
  • state == "fail" → อ่าน data.failMsg + data.failCode
  • Network error ขณะ poll → retry ได้เลย ไม่ต้อง re-create task
  • Download fail → retry พร้อม headers

Cost

  • ยังไม่มีข้อมูล cost per request จาก Kie.ai — ใช้ preview ก่อน batch เสมอ

Rules

  • Preview ก่อน batch — gen 1 request ก่อน (ได้ 3 รูป) ดู quality ก่อน gen เพิ่ม
  • ห้าม Read รูปที่ gen เสร็จ — เปลือง context มาก แจ้งแค่ path ไฟล์พอ
  • .txt คู่เสมอ — save prompt text คู่กับรูปทุกครั้ง
  • ห้าม Read output file ของ background task — สั่ง gen แล้วจบเลย

File Upload API (ทดสอบแล้ว)

ใช้ upload ไฟล์ (เช่น รูปสำหรับ image-to-video) ก่อนส่ง gen

POST https://kieai.redpandaai.co/api/file-stream-upload
Authorization: Bearer <KIE_API_KEY>
Content-Type: multipart/form-data

Parameters:
  file: (binary)
  uploadPath: (string)
  fileName: (string)

Response:
{
  "success": true,
  "data": {
    "downloadUrl": "https://tempfile.redpandaai.co/..."
  }
}

หมายเหตุ:

  • ใช้ curl multipart เท่านั้น (base64 upload ได้ 403)
  • ไฟล์ถูกลบอัตโนมัติหลัง 3 วัน
  • ต้อง upload ก่อนใช้ image-to-video (Veo3 REFERENCE_2_VIDEO)

Veo3 Video Generation (ทดสอบแล้ว)

Veo3 ใช้คนละ endpoint กับ Market API (Grok Imagine) — ทั้ง generate และ poll

Create Task
POST https://api.kie.ai/api/v1/veo/generate
Authorization: Bearer <KIE_API_KEY>
Content-Type: application/json

Body:
{
  "prompt": "...",
  "imageUrls": ["https://uploaded-url"],
  "model": "veo3_fast",
  "generationType": "REFERENCE_2_VIDEO",
  "aspect_ratio": "9:16"
}
Parameterค่าหมายเหตุ
modelveo3_fast, veo3_quality, veo3_litefast รองรับ i2v
generationTypeTEXT_2_VIDEO, REFERENCE_2_VIDEOREFERENCE_2_VIDEO ใช้ได้เฉพาะ veo3_fast
aspect_ratio16:9, 9:16, Auto—
imageUrlsarray of URLsต้อง upload ก่อนผ่าน file-stream-upload

Optional: enableTranslation, enableFallback, watermark, callBackUrl, seeds

Poll Status
GET https://api.kie.ai/api/v1/veo/record-info?taskId=<taskId>
Authorization: Bearer <KIE_API_KEY>
Fieldค่าความหมาย
successFlag0กำลัง generate
successFlag1สำเร็จ
successFlag2ล้มเหลว
successFlag3ล้มเหลว
  • Video URL อยู่ใน data.response.resultUrls[]
  • มี audio (hasAudioList: [true])
  • ใช้เวลาประมาณ 60-120 วินาที
Veo3 Flow: Upload → Generate → Poll
1. Upload image  → POST file-stream-upload → ได้ downloadUrl
2. Generate      → POST /veo/generate (ใส่ downloadUrl ใน imageUrls) → ได้ taskId
3. Poll          → GET /veo/record-info?taskId= → วน loop จน successFlag != 0
4. Download      → ดึง video จาก resultUrls[]

API Endpoints Summary

FeatureMarket API (Grok Imagine)Veo3 API
Create taskPOST /api/v1/jobs/createTaskPOST /api/v1/veo/generate
Poll statusGET /api/v1/jobs/recordInfoGET /api/v1/veo/record-info
File uploadPOST kieai.redpandaai.co/api/file-stream-upload(same)
Base URLhttps://api.kie.aihttps://api.kie.ai

Related Skills

  • /art-engine - upstream: model selection and prompt syntax translation
  • /fal-ai - alternative execution path for Grok (same model, different API - fal.ai direct vs Kie.ai proxy)
  • /art-director - upstream: creative brief crafting
  • /sira-image-prefer - taste DNA for prompt preferences

Comments

Markdown supported