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_KEY	Windows User Env	os.environ["KIE_API_KEY"] (set via setx หรือ [Environment]::SetEnvironmentVariable)

Model Selection

Model ID	Type	Best For	Output
grok-imagine/text-to-image	text2img	Aesthetic/cinematic images, Thai prompt ได้ดี	3 รูป/request
grok-imagine/image-to-image	img2img	แก้ไข/ปรับ style จากรูปต้นแบบ	TBD
grok-imagine/image-to-video	img2vid	สร้างวีดีโอจากรูปนิ่ง	TBD
grok-imagine/upscale	upscale	เพิ่ม resolution วีดีโอ	TBD
veo3_fast	video	Video fast, รองรับ i2v (REFERENCE_2_VIDEO)	video + audio
veo3_quality	video	Video quality สูงสุด	video + audio
veo3_lite	video	Video ประหยัดสุด	video + audio

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

Aspect Ratios

Value	ใช้เมื่อ
2:3	Portrait (default สำหรับรูปคน)
3:2	Landscape
1:1	Square
16:9	Wide cinematic
9:16	Story/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	ค่า	หมายเหตุ
model	veo3_fast, veo3_quality, veo3_lite	fast รองรับ i2v
generationType	TEXT_2_VIDEO, REFERENCE_2_VIDEO	REFERENCE_2_VIDEO ใช้ได้เฉพาะ veo3_fast
aspect_ratio	16:9, 9:16, Auto	—
imageUrls	array 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	ค่า	ความหมาย
successFlag	0	กำลัง generate
successFlag	1	สำเร็จ
successFlag	2	ล้มเหลว
successFlag	3	ล้มเหลว

• 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

Feature	Market API (Grok Imagine)	Veo3 API
Create task	POST /api/v1/jobs/createTask	POST /api/v1/veo/generate
Poll status	GET /api/v1/jobs/recordInfo	GET /api/v1/veo/record-info
File upload	POST kieai.redpandaai.co/api/file-stream-upload	(same)
Base URL	https://api.kie.ai	https://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