kie-ruby 0.1.0 → 0.2.0

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

@@ -0,0 +1,245 @@
+# Grok Imagine Text-to-Video API
+
+Grok Imagine Text-to-Video 動画生成 API。
+
+## 概要
+
+Grok Imagine Text-to-Video はテキストプロンプトから直接動画を生成するモデル。入力画像なしでテキスト指示のみから動画を作成する。
+
+## タスク作成
+
+### エンドポイント
+
+```
+POST /api/v1/jobs/createTask
+```
+
+### リクエストパラメータ
+
+#### トップレベル
+
+| パラメータ | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| `model` | string | Yes | `"grok-imagine/text-to-video"` 固定 |
+| `input` | object | Yes | 入力パラメータ |
+| `callBackUrl` | string | No | タスク完了時の Webhook URL |
+
+#### input オブジェクト
+
+| パラメータ | 型 | 必須 | デフォルト | 説明 |
+|-----------|-----|------|-----------|------|
+| `prompt` | string | Yes | - | 動画の説明（最大 5,000 文字） |
+
+#### パラメータ
+
+| パラメータ | 型 | 必須 | デフォルト | 説明 |
+|-----------|-----|------|-----------|------|
+| `aspect_ratio` | string | No | `"2:3"` | アスペクト比 |
+| `mode` | string | No | `"normal"` | 生成モード |
+
+#### aspect_ratio の値
+
+| 値 | 説明 |
+|----|------|
+| `2:3` | 縦長（デフォルト） |
+| `3:2` | 横長 |
+| `1:1` | 正方形 |
+| `9:16` | 縦長（スマートフォン向け） |
+| `16:9` | 横長（ワイドスクリーン） |
+
+#### mode の値
+
+| 値 | 説明 |
+|----|------|
+| `fun` | 楽しい・カジュアルなスタイル |
+| `normal` | 標準的なスタイル |
+| `spicy` | より大胆なスタイル |
+
+### リクエスト例
+
+#### 基本的な使用
+
+```json
+{
+  "model": "grok-imagine/text-to-video",
+  "input": {
+    "prompt": "A cat playing piano in a jazz club"
+  }
+}
+```
+
+#### すべてのパラメータを指定
+
+```json
+{
+  "model": "grok-imagine/text-to-video",
+  "input": {
+    "prompt": "A beautiful sunset over the ocean with waves gently crashing on the shore"
+  },
+  "aspect_ratio": "16:9",
+  "mode": "normal",
+  "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-video",
+    "state": "success",
+    "param": "{\"prompt\":\"...\"}",
+    "resultJson": "{\"resultUrls\":[\"https://...\"]}",
+    "costTime": 30000,
+    "createTime": 1704067200000,
+    "completeTime": 1704067230000
+  }
+}
+```
+
+#### 処理中
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "grok-imagine/text-to-video",
+    "state": "waiting"
+  }
+}
+```
+
+#### 失敗時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "grok-imagine/text-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")
+
+# 基本的な動画生成
+task = client.general.generate(
+  model: "grok-imagine/text-to-video",
+  input: {
+    prompt: "A peaceful forest with sunlight filtering through the trees"
+  }
+)
+
+# パラメータを指定した動画生成
+task = client.general.generate(
+  model: "grok-imagine/text-to-video",
+  input: {
+    prompt: "A futuristic city at night with neon lights and flying cars"
+  },
+  aspect_ratio: "16:9",
+  mode: "fun"
+)
+
+# 結果を取得
+task.wait
+
+if task.success?
+  video_url = task.urls.first
+  puts "Generated: #{video_url}"
+else
+  puts "Failed: #{task.error_message}"
+end
+```
+
+## 注意事項
+
+1. **プロンプト必須**: image-to-video とは異なり、prompt は必須パラメータ
+2. **動画出力**: 結果 URL は動画ファイル（MP4 等）を指す
+3. **アスペクト比**: image-to-video とは異なり、aspect_ratio パラメータをサポート
+
+## コード参照
+
+モデル定義は以下のファイルで管理されている：
+
+- `lib/kie/models/grok_imagine_text_to_video.rb`
+
+## 関連ドキュメント
+
+- [API 共通仕様](../overview.md)
+- [Grok Imagine Image-to-Video API](grok-imagine-image-to-video.md)

data/docs/api/general/grok-imagine-upscale.md

@@ -0,0 +1,217 @@
+# Grok Imagine Upscale API
+
+Grok Imagine Upscale 画像アップスケーリング API。
+
+## 概要
+
+Grok Imagine Upscale は、Kie AI で生成された画像の解像度を向上させるモデル。外部画像の処理はサポートされておらず、Kie AI タスクの出力のみをアップスケールできる。
+
+### 特徴
+
+- **Kie AI タスク限定**: 外部画像 URL は使用不可。既存の Kie AI タスク ID を参照する必要がある
+- **シンプルな操作**: パラメータなし。入力は `task_id` のみ
+- **アスペクト比維持**: 元画像のアスペクト比を保持してアップスケール
+
+## タスク作成
+
+### エンドポイント
+
+```
+POST /api/v1/jobs/createTask
+```
+
+### リクエストパラメータ
+
+#### トップレベル
+
+| パラメータ | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| `model` | string | Yes | `"grok-imagine/upscale"` 固定 |
+| `input` | object | Yes | 入力パラメータ |
+| `callBackUrl` | string | No | タスク完了時の Webhook URL |
+
+#### input オブジェクト
+
+| パラメータ | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| `task_id` | string | Yes | 参照する Kie AI タスク ID（最大 100 文字） |
+
+### リクエスト例
+
+```json
+{
+  "model": "grok-imagine/upscale",
+  "input": {
+    "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+  }
+}
+```
+
+#### Webhook 付き
+
+```json
+{
+  "model": "grok-imagine/upscale",
+  "input": {
+    "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+  },
+  "callBackUrl": "https://example.com/webhook"
+}
+```
+
+### レスポンス
+
+#### 成功時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
+  }
+}
+```
+
+#### エラー時
+
+```json
+{
+  "code": 400,
+  "msg": "Invalid parameters"
+}
+```
+
+## タスクステータス取得
+
+### エンドポイント
+
+```
+GET /api/v1/jobs/queryTask?taskId={taskId}
+```
+
+### クエリパラメータ
+
+| パラメータ | 型 | 説明 |
+|-----------|-----|------|
+| `taskId` | string | タスク ID |
+
+### レスポンス
+
+#### 成功時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
+    "model": "grok-imagine/upscale",
+    "state": "success",
+    "param": "{\"task_id\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"}",
+    "resultJson": "{\"resultUrls\":[\"https://...\"]}",
+    "costTime": 15000,
+    "createTime": 1704067200000,
+    "completeTime": 1704067215000
+  }
+}
+```
+
+#### 処理中
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
+    "model": "grok-imagine/upscale",
+    "state": "waiting"
+  }
+}
+```
+
+#### 失敗時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
+    "model": "grok-imagine/upscale",
+    "state": "fail",
+    "failCode": "INVALID_TASK_ID",
+    "failMsg": "The referenced task does not exist"
+  }
+}
+```
+
+### タスクステータス
+
+| ステータス | 説明 | 終了状態 |
+|-----------|------|----------|
+| `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")
+
+# 1. まず画像を生成
+image_task = client.general.generate(
+  model: "grok-imagine/text-to-image",
+  input: { prompt: "A beautiful sunset over the ocean" }
+)
+image_task.wait
+
+# 2. 生成された画像をアップスケール
+upscale_task = client.general.generate(
+  model: "grok-imagine/upscale",
+  input: { task_id: image_task.task_id }
+)
+upscale_task.wait
+
+# 結果を取得
+if upscale_task.success?
+  upscaled_url = upscale_task.urls.first
+  puts "Upscaled: #{upscaled_url}"
+else
+  puts "Failed: #{upscale_task.error_message}"
+end
+```
+
+## 注意事項
+
+1. **Kie AI タスク限定**: 外部画像 URL は使用不可。`task_id` で既存のタスク出力を参照する必要がある
+2. **ワークフロー依存**: アップスケール前に参照タスクが成功している必要がある
+3. **パラメータなし**: アスペクト比や解像度の指定は不可。元画像の特性を維持してアップスケールされる
+
+## コード参照
+
+モデル定義は以下のファイルで管理されている：
+
+- `lib/kie/models/grok_imagine_upscale.rb`
+
+## 関連ドキュメント
+
+- [API 共通仕様](../overview.md)
+- [Grok Imagine Text-to-Image API](grok-imagine-text-to-image.md)
+- [Grok Imagine Image-to-Image API](grok-imagine-image-to-image.md)