kie-ruby 0.1.0 → 0.2.0

data/docs/api/general/nano-banana-pro.md

@@ -0,0 +1,275 @@
+# Nano Banana Pro API
+
+Nano Banana Pro 画像生成 API。
+
+## 概要
+
+Nano Banana Pro は高品質な画像生成モデル。テキストプロンプトから画像を生成し、参照画像による制御も可能。
+
+## タスク作成
+
+### エンドポイント
+
+```
+POST /api/v1/jobs/createTask
+```
+
+### リクエストパラメータ
+
+#### トップレベル
+
+| パラメータ | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| `model` | string | Yes | `"nano-banana-pro"` 固定 |
+| `input` | object | Yes | 生成パラメータ |
+| `callBackUrl` | string | No | タスク完了時の Webhook URL |
+
+#### input オブジェクト
+
+| パラメータ | 型 | 必須 | デフォルト | 説明 |
+|-----------|-----|------|-----------|------|
+| `prompt` | string | Yes | - | 画像の説明（最大 20,000 文字） |
+| `image_input` | array | No | `[]` | 参照画像 URL（最大 8 枚） |
+| `aspect_ratio` | string | No | `"1:1"` | アスペクト比 |
+| `resolution` | string | No | `"1K"` | 出力解像度 |
+| `output_format` | string | No | `"png"` | 出力形式 |
+
+### aspect_ratio の値
+
+| 値 | 説明 |
+|----|------|
+| `1:1` | 正方形 |
+| `2:3` | 縦長（2:3） |
+| `3:2` | 横長（3:2） |
+| `3:4` | 縦長（3:4） |
+| `4:3` | 横長（4:3） |
+| `4:5` | 縦長（4:5） |
+| `5:4` | 横長（5:4） |
+| `9:16` | 縦長（9:16、スマートフォン向け） |
+| `16:9` | 横長（16:9、ワイドスクリーン） |
+| `21:9` | 超横長（21:9、シネマスコープ） |
+| `auto` | 自動選択 |
+
+### resolution の値
+
+| 値 | 説明 |
+|----|------|
+| `1K` | 1K 解像度（標準） |
+| `2K` | 2K 解像度（高品質） |
+| `4K` | 4K 解像度（最高品質） |
+
+### output_format の値
+
+| 値 | 説明 |
+|----|------|
+| `png` | PNG 形式（可逆圧縮） |
+| `jpg` | JPEG 形式（非可逆圧縮） |
+
+### 参照画像の仕様
+
+| 項目 | 制限 |
+|------|------|
+| 最大枚数 | 8 枚 |
+| 最大ファイルサイズ | 30 MB / 枚 |
+| 対応形式 | JPEG, PNG, WebP |
+
+### リクエスト例
+
+#### 基本的な画像生成
+
+```json
+{
+  "model": "nano-banana-pro",
+  "input": {
+    "prompt": "A beautiful sunset over the ocean, vibrant colors, photorealistic"
+  }
+}
+```
+
+#### 詳細なパラメータ指定
+
+```json
+{
+  "model": "nano-banana-pro",
+  "input": {
+    "prompt": "A modern minimalist living room with natural lighting",
+    "aspect_ratio": "16:9",
+    "resolution": "2K",
+    "output_format": "jpg"
+  },
+  "callBackUrl": "https://example.com/webhook"
+}
+```
+
+#### 参照画像を使用
+
+```json
+{
+  "model": "nano-banana-pro",
+  "input": {
+    "prompt": "Transform this photo into a watercolor painting style",
+    "image_input": [
+      "https://example.com/reference-image.jpg"
+    ],
+    "aspect_ratio": "auto"
+  }
+}
+```
+
+### レスポンス
+
+#### 成功時
+
+```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": "nano-banana-pro",
+    "state": "success",
+    "param": "{\"prompt\":\"...\",\"aspect_ratio\":\"16:9\"}",
+    "resultJson": "{\"resultUrls\":[\"https://...\"]}",
+    "costTime": 12500,
+    "createTime": 1704067200000,
+    "completeTime": 1704067212500
+  }
+}
+```
+
+#### 処理中
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "nano-banana-pro",
+    "state": "waiting"
+  }
+}
+```
+
+#### 失敗時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "nano-banana-pro",
+    "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.generate(
+  model: "nano-banana-pro",
+  input: {
+    prompt: "A beautiful landscape"
+  }
+)
+
+# パラメータ指定
+task = client.generate(
+  model: "nano-banana-pro",
+  input: {
+    prompt: "A modern cityscape at night"
+  },
+  aspect_ratio: "16:9",
+  resolution: "2K",
+  output_format: "jpg"
+)
+
+# 結果を取得
+result = task.wait
+
+if result["state"] == "success"
+  result_data = JSON.parse(result["resultJson"])
+  image_url = result_data["resultUrls"].first
+  puts "Generated: #{image_url}"
+else
+  puts "Failed: #{result['failMsg']}"
+end
+```
+
+## コード参照
+
+モデル定義は以下のファイルで管理されている：
+
+- `lib/kie/models/nano_banana_pro.rb`
+
+## 関連ドキュメント
+
+- [API 共通仕様](../overview.md)
+- [Suno API](../suno/INDEX.md)

data/docs/api/general/seedream-4-5-edit.md

@@ -0,0 +1,252 @@
+# Seedream 4.5 Edit API
+
+Seedream 4.5 Edit 画像編集 API。
+
+## 概要
+
+Seedream 4.5 Edit は AI を活用した画像編集モデル。入力画像とテキストプロンプトに基づいて、画像を変換・編集する。
+
+## タスク作成
+
+### エンドポイント
+
+```
+POST /api/v1/jobs/createTask
+```
+
+### リクエストパラメータ
+
+#### トップレベル
+
+| パラメータ | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| `model` | string | Yes | `"seedream/4.5-edit"` 固定 |
+| `input` | object | Yes | 編集パラメータ |
+| `callBackUrl` | string | No | タスク完了時の Webhook URL |
+
+#### input オブジェクト
+
+| パラメータ | 型 | 必須 | デフォルト | 説明 |
+|-----------|-----|------|-----------|------|
+| `prompt` | string | Yes | - | 編集指示（最大 3,000 文字） |
+| `image_urls` | array | Yes | - | 編集対象の画像 URL |
+| `aspect_ratio` | string | No | `"1:1"` | 出力アスペクト比 |
+| `quality` | string | No | `"basic"` | 出力品質 |
+
+### aspect_ratio の値
+
+| 値 | 説明 |
+|----|------|
+| `1:1` | 正方形 |
+| `4:3` | 横長（4:3） |
+| `3:4` | 縦長（3:4） |
+| `16:9` | 横長（16:9、ワイドスクリーン） |
+| `9:16` | 縦長（9:16、スマートフォン向け） |
+| `2:3` | 縦長（2:3） |
+| `3:2` | 横長（3:2） |
+| `21:9` | 超横長（21:9、シネマスコープ） |
+
+### quality の値
+
+| 値 | 説明 |
+|----|------|
+| `basic` | 2K 解像度（標準品質） |
+| `high` | 4K 解像度（高品質） |
+
+### 入力画像の仕様
+
+| 項目 | 制限 |
+|------|------|
+| 最大ファイルサイズ | 10 MB / 枚 |
+| 対応形式 | JPEG, PNG, WebP |
+
+### リクエスト例
+
+#### 基本的な画像編集
+
+```json
+{
+  "model": "seedream/4.5-edit",
+  "input": {
+    "prompt": "Add a beautiful sunset sky to the background",
+    "image_urls": [
+      "https://example.com/original-image.jpg"
+    ]
+  }
+}
+```
+
+#### 詳細なパラメータ指定
+
+```json
+{
+  "model": "seedream/4.5-edit",
+  "input": {
+    "prompt": "Transform this photo into anime style illustration",
+    "image_urls": [
+      "https://example.com/photo.jpg"
+    ],
+    "aspect_ratio": "16:9",
+    "quality": "high"
+  },
+  "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": "seedream/4.5-edit",
+    "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": "seedream/4.5-edit",
+    "state": "waiting"
+  }
+}
+```
+
+#### 失敗時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "seedream/4.5-edit",
+    "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: "seedream/4.5-edit",
+  input: {
+    prompt: "Add cherry blossoms to the scene",
+    image_urls: ["https://example.com/landscape.jpg"]
+  }
+)
+
+# パラメータ指定
+task = client.general.generate(
+  model: "seedream/4.5-edit",
+  input: {
+    prompt: "Convert to watercolor painting style",
+    image_urls: ["https://example.com/photo.jpg"]
+  },
+  aspect_ratio: "16:9",
+  quality: "high"
+)
+
+# 結果を取得
+task.wait
+
+if task.success?
+  image_url = task.urls.first
+  puts "Edited: #{image_url}"
+else
+  puts "Failed: #{task.error_message}"
+end
+```
+
+## コード参照
+
+モデル定義は以下のファイルで管理されている：
+
+- `lib/kie/models/seedream_4_5_edit.rb`
+
+## 関連ドキュメント
+
+- [API 共通仕様](../overview.md)
+- [Nano Banana Pro API](nano-banana-pro.md)