kie-ruby 0.1.0 → 0.2.0

data/docs/api/general/flux-2-pro-image-to-image.md

@@ -0,0 +1,257 @@
+# Flux 2 Pro Image-to-Image API
+
+Flux 2 Pro Image-to-Image 画像変換 API。
+
+## 概要
+
+Flux 2 Pro Image-to-Image は参照画像に基づいて新しい画像を生成するモデル。1-8 枚の入力画像とテキストプロンプトを組み合わせて、画像を変換・生成する。
+
+## タスク作成
+
+### エンドポイント
+
+```
+POST /api/v1/jobs/createTask
+```
+
+### リクエストパラメータ
+
+#### トップレベル
+
+| パラメータ | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| `model` | string | Yes | `"flux-2/pro-image-to-image"` 固定 |
+| `input` | object | Yes | 入力パラメータ |
+| `callBackUrl` | string | No | タスク完了時の Webhook URL |
+
+#### input オブジェクト
+
+| パラメータ | 型 | 必須 | デフォルト | 説明 |
+|-----------|-----|------|-----------|------|
+| `prompt` | string | Yes | - | 変換指示（3-5,000 文字） |
+| `input_urls` | array | Yes | - | 参照画像 URL（1-8 枚） |
+| `aspect_ratio` | string | No | `"4:3"` | 出力アスペクト比 |
+| `resolution` | string | No | `"1K"` | 出力解像度 |
+
+### aspect_ratio の値
+
+| 値 | 説明 |
+|----|------|
+| `1:1` | 正方形 |
+| `4:3` | 横長（4:3） |
+| `3:4` | 縦長（3:4） |
+| `16:9` | 横長（16:9、ワイドスクリーン） |
+| `9:16` | 縦長（9:16、スマートフォン向け） |
+| `3:2` | 横長（3:2、クラシック） |
+| `2:3` | 縦長（2:3、クラシックポートレート） |
+| `auto` | 最初の入力画像に合わせる |
+
+### resolution の値
+
+| 値 | 説明 |
+|----|------|
+| `1K` | 1K 解像度（標準） |
+| `2K` | 2K 解像度（高解像度） |
+
+### 入力画像の仕様
+
+| 項目 | 制限 |
+|------|------|
+| 画像枚数 | 1-8 枚 |
+| 最大ファイルサイズ | 10 MB / 枚 |
+| 対応形式 | JPEG, PNG, WebP |
+
+### リクエスト例
+
+#### 基本的な画像変換
+
+```json
+{
+  "model": "flux-2/pro-image-to-image",
+  "input": {
+    "prompt": "Change the outfit to a formal suit",
+    "input_urls": [
+      "https://example.com/person.jpg"
+    ]
+  }
+}
+```
+
+#### 複数画像を参照した変換
+
+```json
+{
+  "model": "flux-2/pro-image-to-image",
+  "input": {
+    "prompt": "Combine elements from both images into a new design",
+    "input_urls": [
+      "https://example.com/reference1.jpg",
+      "https://example.com/reference2.jpg"
+    ],
+    "aspect_ratio": "16:9",
+    "resolution": "2K"
+  },
+  "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": "flux-2/pro-image-to-image",
+    "state": "success",
+    "param": "{\"prompt\":\"...\",\"input_urls\":[...]}",
+    "resultJson": "{\"resultUrls\":[\"https://...\"]}",
+    "costTime": 15000,
+    "createTime": 1704067200000,
+    "completeTime": 1704067215000
+  }
+}
+```
+
+#### 処理中
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "flux-2/pro-image-to-image",
+    "state": "waiting"
+  }
+}
+```
+
+#### 失敗時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "flux-2/pro-image-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: "flux-2/pro-image-to-image",
+  input: {
+    prompt: "Transform this person into wearing a vintage dress",
+    input_urls: ["https://example.com/photo.jpg"]
+  }
+)
+
+# パラメータ指定
+task = client.general.generate(
+  model: "flux-2/pro-image-to-image",
+  input: {
+    prompt: "Merge the styles of these two images",
+    input_urls: [
+      "https://example.com/style1.jpg",
+      "https://example.com/style2.jpg"
+    ]
+  },
+  aspect_ratio: "16:9",
+  resolution: "2K"
+)
+
+# 結果を取得
+task.wait
+
+if task.success?
+  image_url = task.urls.first
+  puts "Generated: #{image_url}"
+else
+  puts "Failed: #{task.error_message}"
+end
+```
+
+## コード参照
+
+モデル定義は以下のファイルで管理されている：
+
+- `lib/kie/models/flux_2_pro_image_to_image.rb`
+
+## 関連ドキュメント
+
+- [API 共通仕様](../overview.md)
+- [Seedream 4.5 Edit API](seedream-4-5-edit.md)

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

@@ -0,0 +1,232 @@
+# Grok Imagine Image-to-Image API
+
+Grok Imagine Image-to-Image 画像変換 API。
+
+## 概要
+
+Grok Imagine Image-to-Image は入力画像とオプションのスタイル/コンテンツプロンプトに基づいて新しい画像を生成する画像変換モデル。シンプルな入力構造で、追加パラメータなしで使用可能。
+
+## タスク作成
+
+### エンドポイント
+
+```
+POST /api/v1/jobs/createTask
+```
+
+### リクエストパラメータ
+
+#### トップレベル
+
+| パラメータ | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| `model` | string | Yes | `"grok-imagine/image-to-image"` 固定 |
+| `input` | object | Yes | 入力パラメータ |
+| `callBackUrl` | string | No | タスク完了時の Webhook URL |
+
+#### input オブジェクト
+
+| パラメータ | 型 | 必須 | デフォルト | 説明 |
+|-----------|-----|------|-----------|------|
+| `prompt` | string | No | - | スタイル/コンテンツ指示（最大 390,000 文字） |
+| `image_urls` | array | Yes | - | 入力画像 URL（1 枚） |
+
+### 入力画像の仕様
+
+| 項目 | 制限 |
+|------|------|
+| 画像枚数 | 1 枚 |
+| 最大ファイルサイズ | 10 MB |
+| 対応形式 | JPEG, PNG, WebP |
+
+### リクエスト例
+
+#### プロンプトなし（画像のみ）
+
+```json
+{
+  "model": "grok-imagine/image-to-image",
+  "input": {
+    "image_urls": [
+      "https://example.com/source.jpg"
+    ]
+  }
+}
+```
+
+#### プロンプト付き
+
+```json
+{
+  "model": "grok-imagine/image-to-image",
+  "input": {
+    "prompt": "Transform into a watercolor painting style",
+    "image_urls": [
+      "https://example.com/source.jpg"
+    ]
+  },
+  "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-image",
+    "state": "success",
+    "param": "{\"prompt\":\"...\",\"image_urls\":[...]}",
+    "resultJson": "{\"resultUrls\":[\"https://...\"]}",
+    "costTime": 15000,
+    "createTime": 1704067200000,
+    "completeTime": 1704067215000
+  }
+}
+```
+
+#### 処理中
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "grok-imagine/image-to-image",
+    "state": "waiting"
+  }
+}
+```
+
+#### 失敗時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "grok-imagine/image-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/image-to-image",
+  input: {
+    image_urls: ["https://example.com/photo.jpg"]
+  }
+)
+
+# プロンプト付き画像変換
+task = client.general.generate(
+  model: "grok-imagine/image-to-image",
+  input: {
+    prompt: "Convert to anime style with vibrant colors",
+    image_urls: ["https://example.com/photo.jpg"]
+  }
+)
+
+# 結果を取得
+task.wait
+
+if task.success?
+  image_url = task.urls.first
+  puts "Generated: #{image_url}"
+else
+  puts "Failed: #{task.error_message}"
+end
+```
+
+## 注意事項
+
+1. **必須入力**: `image_urls` は必須パラメータ
+2. **単一画像**: 入力画像は 1 枚のみ
+3. **シンプル設計**: パラメータ（`aspect_ratio`, `resolution` 等）は不要
+4. **大容量プロンプト**: 最大 390,000 文字のプロンプトをサポート
+
+## コード参照
+
+モデル定義は以下のファイルで管理されている：
+
+- `lib/kie/models/grok_imagine_image_to_image.rb`
+
+## 関連ドキュメント
+
+- [API 共通仕様](../overview.md)
+- [Grok Imagine Image-to-Video API](grok-imagine-image-to-video.md)