kie-ai

kie-ai — Kie.ai API 経由の Grok Imagine

Kie.ai REST API 経由で画像／動画を生成します — Grok Imagine モデル用のプロキシです。

パスのショートカット

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

環境変数

変数	場所	読み取り方法
KIE_API_KEY	Windows User Env	os.environ["KIE_API_KEY"]（setx または [Environment]::SetEnvironmentVariable で設定）

モデルの選択

モデル ID	種類	最適な用途	出力
grok-imagine/text-to-image	text2img	美的・シネマティックな画像。タイ語のプロンプトにも適しています	3 枚/request
grok-imagine/image-to-image	img2img	元画像をもとにした編集／スタイル調整	TBD
grok-imagine/image-to-video	img2vid	静止画から動画を生成	TBD
grok-imagine/upscale	upscale	動画の解像度を上げる	TBD
veo3_fast	video	高速動画生成。i2v（REFERENCE_2_VIDEO）に対応	動画 + 音声
veo3_quality	video	最高品質の動画	動画 + 音声
veo3_lite	video	最も低コストな動画	動画 + 音声

注意： text-to-image + veo3_fast はテスト済みで、実際に動作します／ほかのモデルはドキュメントに記載されていますが、未テストです。 Veo3 は別のエンドポイントを使用します — 以下の「Veo3 Video Generation」と「API Endpoints Summary」のセクションを参照してください。

アスペクト比

値	用途
2:3	ポートレート（人物画像のデフォルト）
3:2	ランドスケープ
1:1	正方形
16:9	ワイド・シネマティック
9:16	ストーリー／リール形式

API の流れ — 3 ステップ

1. タスクを作成

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 を確認します。そうでなければエラーです。
• taskId を保存してポーリングします。

2. タスクの状態をポーリング

GET {BASE}/recordInfo?taskId=<taskId>
Authorization: Bearer <KIE_API_KEY>

タスクの状態：

状態	意味	アクション
waiting	キュー内	待機を続ける
queuing	キュー内	待機を続ける
generating	生成中	待機を続ける
success	完了	URL を取得
fail	失敗	failMsg + failCode を読む

ポーリング戦略： 5 秒ごとに実行し、タイムアウトは 5 分（60 回）

成功時：

• data.resultJson は JSON 文字列です → もう一度パースする必要があります
• 内部に resultUrls: [url1, url2, url3] があります — 1 request あたり 3 枚取得できます

3. 画像をダウンロード

重要： URL には特別なヘッダーを指定する必要があります。指定しないとブロックされます。

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

命名規則：

kie_grok_{taskId_last8}_{index}.jpg

出力ディレクトリ： D:/ClaudeMediaGen/output-fal/

---

プロンプトのルール

Grok のプロンプト構文ルールは共有モデルカードに移動しました。 以下を参照してください：grok-image.md

• ハイブリッドプロンプト戦略（英語 + タイ語）
• 禁止ワード
• Subject は短く、Scene は長くするルール
• body size を指定しない

実装ガイド

Python で生成スクリプトを作成

1. os.environ["KIE_API_KEY"] から API キーを読み取ります（Windows User Env — マシン全体で一度だけ設定）
2. タスクを作成 → POST /createTask → taskId を保存
3. ポーリング → GET /recordInfo?taskId= → success または fail になるまで 5 秒ごとにループ
4. 結果をパース → data.resultJson は文字列です → json.loads() → resultUrls
5. ダウンロード → User-Agent + Referer ヘッダーを指定 → .jpg として保存
6. 対応する .txt を作成 → トレーサビリティのため、毎回プロンプトテキストを画像と一緒に保存

一括生成

• 複数のリクエストを同時に送信できます（テストではレート制限は確認されていません）
• 各リクエストで 3 枚取得できます → 10 requests = 30 枚
• Claude Code で並列生成するには run_in_background: true を使用します

エラー処理

• createTask から code != 200 が返った場合 → レスポンス全体を表示
• state == "fail" の場合 → data.failMsg + data.failCode を読む
• ポーリング中にネットワークエラーが発生した場合 → タスクを再作成せず、そのまま再試行できます
• ダウンロードに失敗した場合 → ヘッダーを指定して再試行

コスト

• Kie.ai のリクエストあたりのコスト情報はまだありません — 必ず一括生成の前にプレビューしてください

ルール

• 一括生成の前にプレビュー — まず 1 request 生成し（3 枚取得）、品質を確認してから追加生成します
• 生成済みの画像を Read しない — コンテキストを大量に消費するため、ファイルパスのみを伝えてください
• 必ず対応する .txt を作成 — 毎回、プロンプトテキストを画像と一緒に保存します
• バックグラウンドタスクの出力ファイルを Read しない — 生成を指示したら、そのまま終了します

ファイルアップロード API（テスト済み）

gen を送信する前にファイル（image-to-video 用の画像など）をアップロードします。

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 アップロードは 403 になります）
• ファイルは 3 日後に自動削除されます
• image-to-video（Veo3 REFERENCE_2_VIDEO）を使用する前にアップロードが必要です

Veo3 動画生成（テスト済み）

Veo3 は Market API（Grok Imagine）とは異なるエンドポイントを使用します — 生成とポーリングの両方

タスクの作成

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

パラメーター	値	備考
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	URL の配列	file-stream-upload 経由で事前にアップロードが必要です

オプション：enableTranslation、enableFallback、watermark、callBackUrl、seeds

ステータスのポーリング

GET https://api.kie.ai/api/v1/veo/record-info?taskId=<taskId>
Authorization: Bearer <KIE_API_KEY>

フィールド	値	意味
successFlag	0	生成中
successFlag	1	成功
successFlag	2	失敗
successFlag	3	失敗

• 動画 URL は data.response.resultUrls[] にあります
• 音声があります（hasAudioList: [true]）
• 所要時間は約 60-120 秒です

Veo3 のフロー：アップロード → 生成 → ポーリング

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 エンドポイントの概要

機能	Market API（Grok Imagine）	Veo3 API
タスクの作成	POST /api/v1/jobs/createTask	POST /api/v1/veo/generate
ステータスのポーリング	GET /api/v1/jobs/recordInfo	GET /api/v1/veo/record-info
ファイルアップロード	POST kieai.redpandaai.co/api/file-stream-upload	（同じ）
ベース URL	https://api.kie.ai	https://api.kie.ai

関連スキル

• /art-engine - 上流：モデル選択とプロンプト構文の翻訳
• /fal-ai - Grok の代替実行方法（同じモデル、異なる API - fal.ai への直接接続と Kie.ai プロキシ）
• /art-director - 上流：クリエイティブブリーフの作成
• /sira-image-prefer - プロンプトの好みに関するテイスト DNA