kie-ruby 0.1.0 → 0.2.0

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

@@ -0,0 +1,257 @@
+# Flux 2 Flex Image-to-Image API
+
+Flux 2 Flex Image-to-Image 画像変換 API。
+
+## 概要
+
+Flux 2 Flex Image-to-Image は参照画像に基づいて新しい画像を生成するモデル。1-8 枚の入力画像とテキストプロンプトを組み合わせて、柔軟な画像変換・生成を行う。
+
+## タスク作成
+
+### エンドポイント
+
+```
+POST /api/v1/jobs/createTask
+```
+
+### リクエストパラメータ
+
+#### トップレベル
+
+| パラメータ | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| `model` | string | Yes | `"flux-2/flex-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 | `"1:1"` | 出力アスペクト比 |
+| `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/flex-image-to-image",
+  "input": {
+    "prompt": "Change the outfit to a formal suit",
+    "input_urls": [
+      "https://example.com/person.jpg"
+    ]
+  }
+}
+```
+
+#### 複数画像を参照した変換
+
+```json
+{
+  "model": "flux-2/flex-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/flex-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/flex-image-to-image",
+    "state": "waiting"
+  }
+}
+```
+
+#### 失敗時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "flux-2/flex-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/flex-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/flex-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_flex_image_to_image.rb`
+
+## 関連ドキュメント
+
+- [API 共通仕様](../overview.md)
+- [Flux 2 Pro Image-to-Image API](flux-2-pro-image-to-image.md)

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

@@ -0,0 +1,237 @@
+# Flux 2 Flex Text-to-Image API
+
+Flux 2 Flex Text-to-Image 画像生成 API。
+
+## 概要
+
+Flux 2 Flex Text-to-Image はテキストプロンプトから画像を生成するモデル。入力画像を必要としない純粋な text-to-image モデル。
+
+## タスク作成
+
+### エンドポイント
+
+```
+POST /api/v1/jobs/createTask
+```
+
+### リクエストパラメータ
+
+#### トップレベル
+
+| パラメータ | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| `model` | string | Yes | `"flux-2/flex-text-to-image"` 固定 |
+| `input` | object | Yes | 入力パラメータ |
+| `callBackUrl` | string | No | タスク完了時の Webhook URL |
+
+#### input オブジェクト
+
+| パラメータ | 型 | 必須 | デフォルト | 説明 |
+|-----------|-----|------|-----------|------|
+| `prompt` | string | Yes | - | 画像生成指示（3-5,000 文字） |
+| `aspect_ratio` | string | No | `"1:1"` | 出力アスペクト比 |
+| `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` | 自動（入力画像必要。text-to-image では使用非推奨） |
+
+### resolution の値
+
+| 値 | 説明 |
+|----|------|
+| `1K` | 1K 解像度（標準） |
+| `2K` | 2K 解像度（高解像度） |
+
+### リクエスト例
+
+#### 基本的な画像生成
+
+```json
+{
+  "model": "flux-2/flex-text-to-image",
+  "input": {
+    "prompt": "A serene mountain landscape at sunset with golden light"
+  }
+}
+```
+
+#### パラメータ指定
+
+```json
+{
+  "model": "flux-2/flex-text-to-image",
+  "input": {
+    "prompt": "A futuristic cityscape with flying cars and neon lights",
+    "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/flex-text-to-image",
+    "state": "success",
+    "param": "{\"prompt\":\"...\"}",
+    "resultJson": "{\"resultUrls\":[\"https://...\"]}",
+    "costTime": 15000,
+    "createTime": 1704067200000,
+    "completeTime": 1704067215000
+  }
+}
+```
+
+#### 処理中
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "flux-2/flex-text-to-image",
+    "state": "waiting"
+  }
+}
+```
+
+#### 失敗時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "flux-2/flex-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: "flux-2/flex-text-to-image",
+  input: {
+    prompt: "A beautiful sunset over the ocean with vibrant colors"
+  }
+)
+
+# パラメータ指定
+task = client.general.generate(
+  model: "flux-2/flex-text-to-image",
+  input: {
+    prompt: "An astronaut riding a horse on Mars"
+  },
+  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_flex_text_to_image.rb`
+
+## 関連ドキュメント
+
+- [API 共通仕様](../overview.md)
+- [Flux 2 Flex Image-to-Image API](flux-2-flex-image-to-image.md)
+- [Flux 2 Pro Image-to-Image API](flux-2-pro-image-to-image.md)