kie-ruby 0.1.0 → 0.2.0

data/docs/api/general/grok-imagine-image-to-video.md

@@ -0,0 +1,257 @@
+# Grok Imagine Image-to-Video API
+
+Grok Imagine Image-to-Video 動画生成 API。
+
+## 概要
+
+Grok Imagine Image-to-Video は静止画像から動画を生成するモデル。入力画像とオプションのモーションプロンプトを組み合わせて、画像をアニメーション化する。
+
+### 入力方法
+
+このモデルは2つの入力方法をサポートしており、**相互排他的**である：
+
+1. **外部画像 URL**（`image_urls`）: 任意の外部画像 URL を指定
+2. **Grok タスク参照**（`task_id` + `index`）: 過去の Grok 生成タスクの画像を参照
+
+## タスク作成
+
+### エンドポイント
+
+```
+POST /api/v1/jobs/createTask
+```
+
+### リクエストパラメータ
+
+#### トップレベル
+
+| パラメータ | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| `model` | string | Yes | `"grok-imagine/image-to-video"` 固定 |
+| `input` | object | Yes | 入力パラメータ |
+| `callBackUrl` | string | No | タスク完了時の Webhook URL |
+
+#### input オブジェクト
+
+| パラメータ | 型 | 必須 | デフォルト | 説明 |
+|-----------|-----|------|-----------|------|
+| `prompt` | string | No | - | モーション指示（最大 5,000 文字） |
+| `image_urls` | array | No* | - | 入力画像 URL（最大 1 枚） |
+| `task_id` | string | No* | - | 参照する Grok タスク ID（最大 100 文字） |
+| `index` | number | No | - | 参照タスクの画像インデックス（0-5） |
+| `mode` | string | No | `"normal"` | 生成モード |
+
+*注意: `image_urls` と `task_id` は相互排他的。どちらか一方を指定する。
+
+#### mode の値
+
+| 値 | 説明 |
+|----|------|
+| `fun` | 楽しい・カジュアルなアニメーション |
+| `normal` | 標準的なアニメーション |
+| `spicy` | より大胆なアニメーション（外部画像使用時は `normal` に自動切替） |
+
+### 入力画像の仕様
+
+| 項目 | 制限 |
+|------|------|
+| 画像枚数 | 最大 1 枚 |
+| 最大ファイルサイズ | 10 MB |
+| 対応形式 | JPEG, PNG, WebP |
+
+### リクエスト例
+
+#### 外部画像 URL を使用
+
+```json
+{
+  "model": "grok-imagine/image-to-video",
+  "input": {
+    "prompt": "Make the person wave their hand gently",
+    "image_urls": [
+      "https://example.com/person.jpg"
+    ],
+    "mode": "normal"
+  }
+}
+```
+
+#### Grok タスク参照を使用
+
+```json
+{
+  "model": "grok-imagine/image-to-video",
+  "input": {
+    "prompt": "Add a gentle breeze effect to the scene",
+    "task_id": "previous-grok-task-id",
+    "index": 0,
+    "mode": "fun"
+  },
+  "callBackUrl": "https://example.com/webhook"
+}
+```
+
+### レスポンス
+
+#### 成功時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+  }
+}
+```
+
+#### エラー時
+
+```json
+{
+  "code": 400,
+  "msg": "Invalid parameters"
+}
+```
+
+## タスクステータス取得
+
+### エンドポイント
+
+```
+GET /api/v1/jobs/queryTask?taskId={taskId}
+```
+
+### クエリパラメータ
+
+| パラメータ | 型 | 説明 |
+|-----------|-----|------|
+| `taskId` | string | タスク ID |
+
+### レスポンス
+
+#### 成功時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "grok-imagine/image-to-video",
+    "state": "success",
+    "param": "{\"prompt\":\"...\",\"image_urls\":[...]}",
+    "resultJson": "{\"resultUrls\":[\"https://...\"]}",
+    "costTime": 30000,
+    "createTime": 1704067200000,
+    "completeTime": 1704067230000
+  }
+}
+```
+
+#### 処理中
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "grok-imagine/image-to-video",
+    "state": "waiting"
+  }
+}
+```
+
+#### 失敗時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "grok-imagine/image-to-video",
+    "state": "fail",
+    "failCode": "CONTENT_POLICY_VIOLATION",
+    "failMsg": "The prompt violates content policy"
+  }
+}
+```
+
+### タスクステータス
+
+| ステータス | 説明 | 終了状態 |
+|-----------|------|----------|
+| `waiting` | 処理待ち | No |
+| `success` | 完了 | Yes (成功) |
+| `fail` | 失敗 | Yes (失敗) |
+
+### レスポンスフィールド
+
+| フィールド | 型 | 説明 |
+|-----------|-----|------|
+| `taskId` | string | タスク ID |
+| `model` | string | モデル名 |
+| `state` | string | タスクステータス |
+| `param` | string | リクエストパラメータ（JSON 文字列） |
+| `resultJson` | string | 結果（JSON 文字列、成功時のみ） |
+| `failCode` | string | エラーコード（失敗時） |
+| `failMsg` | string | エラーメッセージ（失敗時） |
+| `costTime` | integer | 処理時間（ミリ秒） |
+| `createTime` | integer | 作成日時（Unix ミリ秒） |
+| `completeTime` | integer | 完了日時（Unix ミリ秒） |
+
+## Ruby クライアントでの使用
+
+```ruby
+client = Kie::Client.new(api_key: "your-api-key")
+
+# 外部画像 URL を使用した動画生成
+task = client.general.generate(
+  model: "grok-imagine/image-to-video",
+  input: {
+    prompt: "Make the character dance gracefully",
+    image_urls: ["https://example.com/character.jpg"]
+  },
+  mode: "fun"
+)
+
+# Grok タスク参照を使用した動画生成
+task = client.general.generate(
+  model: "grok-imagine/image-to-video",
+  input: {
+    prompt: "Add a cinematic camera movement",
+    task_id: "previous-task-id",
+    index: 2
+  },
+  mode: "normal"
+)
+
+# 結果を取得
+task.wait
+
+if task.success?
+  video_url = task.urls.first
+  puts "Generated: #{video_url}"
+else
+  puts "Failed: #{task.error_message}"
+end
+```
+
+## 注意事項
+
+1. **相互排他的入力**: `image_urls` と `task_id` は同時に指定できない
+2. **spicy モードの制限**: 外部画像使用時、`spicy` モードは自動的に `normal` に切り替わる
+3. **動画出力**: 結果 URL は動画ファイル（MP4 等）を指す
+
+## コード参照
+
+モデル定義は以下のファイルで管理されている：
+
+- `lib/kie/models/grok_imagine_image_to_video.rb`
+
+## 関連ドキュメント
+
+- [API 共通仕様](../overview.md)
+- [Flux 2 Pro Image-to-Image API](flux-2-pro-image-to-image.md)

data/docs/api/general/grok-imagine-text-to-image.md

@@ -0,0 +1,237 @@
+# Grok Imagine Text-to-Image API
+
+Grok Imagine Text-to-Image 画像生成 API。
+
+## 概要
+
+Grok Imagine Text-to-Image はテキストプロンプトから画像を生成するモデル。1 リクエストにつき 6 枚の画像を生成する特徴を持つ。
+
+## タスク作成
+
+### エンドポイント
+
+```
+POST /api/v1/jobs/createTask
+```
+
+### リクエストパラメータ
+
+#### トップレベル
+
+| パラメータ | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| `model` | string | Yes | `"grok-imagine/text-to-image"` 固定 |
+| `input` | object | Yes | 入力パラメータ |
+| `callBackUrl` | string | No | タスク完了時の Webhook URL |
+
+#### input オブジェクト
+
+| パラメータ | 型 | 必須 | デフォルト | 説明 |
+|-----------|-----|------|-----------|------|
+| `prompt` | string | Yes | - | 画像の説明（最大 5,000 文字） |
+
+#### パラメータ
+
+| パラメータ | 型 | 必須 | デフォルト | 説明 |
+|-----------|-----|------|-----------|------|
+| `aspect_ratio` | string | No | `"3:2"` | アスペクト比 |
+
+#### aspect_ratio の値
+
+| 値 | 説明 |
+|----|------|
+| `2:3` | 縦長 |
+| `3:2` | 横長（デフォルト） |
+| `1:1` | 正方形 |
+| `9:16` | 縦長（スマートフォン向け） |
+| `16:9` | 横長（ワイドスクリーン） |
+
+### リクエスト例
+
+#### 基本的な使用
+
+```json
+{
+  "model": "grok-imagine/text-to-image",
+  "input": {
+    "prompt": "A futuristic city at sunset with flying cars"
+  }
+}
+```
+
+#### すべてのパラメータを指定
+
+```json
+{
+  "model": "grok-imagine/text-to-image",
+  "input": {
+    "prompt": "A serene Japanese garden with cherry blossoms in full bloom"
+  },
+  "aspect_ratio": "16:9",
+  "callBackUrl": "https://example.com/webhook"
+}
+```
+
+### レスポンス
+
+#### 成功時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+  }
+}
+```
+
+#### エラー時
+
+```json
+{
+  "code": 400,
+  "msg": "Invalid parameters"
+}
+```
+
+## タスクステータス取得
+
+### エンドポイント
+
+```
+GET /api/v1/jobs/queryTask?taskId={taskId}
+```
+
+### クエリパラメータ
+
+| パラメータ | 型 | 説明 |
+|-----------|-----|------|
+| `taskId` | string | タスク ID |
+
+### レスポンス
+
+#### 成功時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "grok-imagine/text-to-image",
+    "state": "success",
+    "param": "{\"prompt\":\"...\"}",
+    "resultJson": "{\"resultUrls\":[\"https://...\",\"https://...\",\"https://...\",\"https://...\",\"https://...\",\"https://...\"]}",
+    "costTime": 15000,
+    "createTime": 1704067200000,
+    "completeTime": 1704067215000
+  }
+}
+```
+
+#### 処理中
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "grok-imagine/text-to-image",
+    "state": "waiting"
+  }
+}
+```
+
+#### 失敗時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "grok-imagine/text-to-image",
+    "state": "fail",
+    "failCode": "CONTENT_POLICY_VIOLATION",
+    "failMsg": "The prompt violates content policy"
+  }
+}
+```
+
+### タスクステータス
+
+| ステータス | 説明 | 終了状態 |
+|-----------|------|----------|
+| `waiting` | 処理待ち | No |
+| `success` | 完了 | Yes (成功) |
+| `fail` | 失敗 | Yes (失敗) |
+
+### レスポンスフィールド
+
+| フィールド | 型 | 説明 |
+|-----------|-----|------|
+| `taskId` | string | タスク ID |
+| `model` | string | モデル名 |
+| `state` | string | タスクステータス |
+| `param` | string | リクエストパラメータ（JSON 文字列） |
+| `resultJson` | string | 結果（JSON 文字列、成功時のみ） |
+| `failCode` | string | エラーコード（失敗時） |
+| `failMsg` | string | エラーメッセージ（失敗時） |
+| `costTime` | integer | 処理時間（ミリ秒） |
+| `createTime` | integer | 作成日時（Unix ミリ秒） |
+| `completeTime` | integer | 完了日時（Unix ミリ秒） |
+
+## Ruby クライアントでの使用
+
+```ruby
+client = Kie::Client.new(api_key: "your-api-key")
+
+# 基本的な画像生成
+task = client.general.generate(
+  model: "grok-imagine/text-to-image",
+  input: {
+    prompt: "A majestic mountain landscape at dawn"
+  }
+)
+
+# パラメータを指定した画像生成
+task = client.general.generate(
+  model: "grok-imagine/text-to-image",
+  input: {
+    prompt: "A cyberpunk cityscape with neon lights and rain"
+  },
+  aspect_ratio: "16:9"
+)
+
+# 結果を取得
+task.wait
+
+if task.success?
+  # 6 枚の画像 URL を取得
+  task.urls.each_with_index do |url, index|
+    puts "Image #{index + 1}: #{url}"
+  end
+else
+  puts "Failed: #{task.error_message}"
+end
+```
+
+## 注意事項
+
+1. **6 枚同時生成**: 1 リクエストにつき 6 枚の画像を生成。resultUrls 配列には 6 つの URL が含まれる
+2. **mode パラメータなし**: text-to-video とは異なり、mode（fun/normal/spicy）パラメータは存在しない
+3. **デフォルトアスペクト比**: `3:2`（text-to-video のデフォルト `2:3` とは異なる）
+
+## コード参照
+
+モデル定義は以下のファイルで管理されている：
+
+- `lib/kie/models/grok_imagine_text_to_image.rb`
+
+## 関連ドキュメント
+
+- [API 共通仕様](../overview.md)
+- [Grok Imagine Text-to-Video API](grok-imagine-text-to-video.md)
+- [Grok Imagine Image-to-Image API](grok-imagine-image-to-image.md)