kie-ai（纪爱）

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

Model Selection

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

Aspect Ratios

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:

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"
}

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>

• 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

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