kie-ruby 0.1.0 → 0.2.0

data/docs/api/suno/task-status.md

@@ -0,0 +1,150 @@
+# Suno タスクステータス API
+
+音楽生成タスクのステータスと結果を取得する API。
+
+## エンドポイント
+
+```
+GET /api/v1/generate/{taskId}
+```
+
+## パスパラメータ
+
+| パラメータ | 型 | 説明 |
+|-----------|-----|------|
+| `taskId` | string | 音楽生成タスクの一意識別子 |
+
+## レスポンス
+
+### 成功時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "parentMusicId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
+    "param": "{\"model\":\"V4_5\",\"prompt\":\"...\"}",
+    "status": "SUCCESS",
+    "type": "chirp-v4",
+    "operationType": "generate",
+    "response": {
+      "sunoData": [
+        {
+          "audioUrl": "https://...",
+          "streamAudioUrl": "https://...",
+          "imageUrl": "https://...",
+          "prompt": "A happy pop song",
+          "modelName": "V4_5",
+          "title": "Summer Days",
+          "tags": "pop, happy",
+          "createTime": 1704067200000,
+          "duration": 180.5
+        }
+      ]
+    }
+  }
+}
+```
+
+### エラー時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "status": "GENERATE_AUDIO_FAILED",
+    "errorCode": 408,
+    "errorMessage": "Generation timeout"
+  }
+}
+```
+
+## タスクステータス
+
+| ステータス | 説明 | 終了状態 |
+|-----------|------|----------|
+| `PENDING` | 処理待ち | No |
+| `TEXT_SUCCESS` | テキスト処理完了 | No |
+| `FIRST_SUCCESS` | 最初の生成完了 | No |
+| `SUCCESS` | 生成完了 | Yes (成功) |
+| `CREATE_TASK_FAILED` | タスク作成失敗 | Yes (失敗) |
+| `GENERATE_AUDIO_FAILED` | 音声生成失敗 | Yes (失敗) |
+| `CALLBACK_EXCEPTION` | コールバック例外 | Yes (失敗) |
+| `SENSITIVE_WORD_ERROR` | 禁止ワード検出 | Yes (失敗) |
+
+## レスポンスフィールド
+
+### メインフィールド
+
+| フィールド | 型 | 説明 |
+|-----------|-----|------|
+| `taskId` | string | タスク ID |
+| `parentMusicId` | string | 拡張元の音楽 ID（extend 操作時） |
+| `param` | string | 生成に使用したパラメータ（JSON 文字列） |
+| `status` | string | タスクステータス |
+| `type` | string | タスクタイプ（`chirp-v3-5`, `chirp-v4`） |
+| `operationType` | string | 操作タイプ |
+| `errorCode` | integer | エラーコード（失敗時） |
+| `errorMessage` | string | エラーメッセージ（失敗時） |
+
+### operationType
+
+| 値 | 説明 |
+|----|------|
+| `generate` | 新規生成 |
+| `extend` | 楽曲の延長 |
+| `upload_cover` | カバー画像アップロード |
+| `upload_extend` | 拡張用アップロード |
+
+### sunoData フィールド
+
+| フィールド | 型 | 説明 |
+|-----------|-----|------|
+| `audioUrl` | string | 音声ファイル URL |
+| `streamAudioUrl` | string | ストリーミング用 URL |
+| `imageUrl` | string | カバー画像 URL |
+| `prompt` | string | 使用したプロンプト |
+| `modelName` | string | モデル名 |
+| `title` | string | 楽曲タイトル |
+| `tags` | string | 音楽のタグ |
+| `createTime` | integer | 作成日時（Unix ミリ秒） |
+| `duration` | number | 楽曲の長さ（秒） |
+
+## Ruby クライアントでの使用
+
+```ruby
+client = Kie::Client.new(api_key: "your-api-key")
+
+# 生成タスクを作成
+task = client.generate(
+  model: "V4_5",
+  input: {
+    prompt: "A happy pop song",
+    custom_mode: false,
+    instrumental: false
+  }
+)
+
+# ステータスを確認
+status = task.status  # => "PENDING"
+
+# 完了まで待機（ポーリング）
+result = task.wait
+
+# 結果を取得
+if result["status"] == "SUCCESS"
+  audio_url = result.dig("response", "sunoData", 0, "audioUrl")
+  puts "Generated: #{audio_url}"
+else
+  puts "Failed: #{result['errorMessage']}"
+end
+```
+
+## 関連ドキュメント
+
+- [音楽生成 API](./generate.md)
+- [API 共通仕様](../overview.md)

data/docs/development/INDEX.md

@@ -1,3 +1,4 @@
 # Development Documents
 
 - `technical-design.md`: アーキテクチャ、技術設計、開発環境
+- `adding-new-model.md`: 新モデル追加時の変更対象ファイルと手順

data/docs/development/adding-new-model.md

@@ -0,0 +1,195 @@
+# 新モデル追加ガイド
+
+このドキュメントでは、Kie.ai Ruby Client に新しいモデルを追加する際に変更が必要なファイルと手順を説明します。
+
+## 変更対象ファイル一覧
+
+### 1. コード変更（必須）
+
+| ファイル | 変更内容 |
+|:---------|:---------|
+| `lib/kie/models/<model_name>.rb` | モデル定義ファイルの新規作成 |
+| `lib/kie.rb` | require 文の追加 |
+
+### 2. テスト変更（必須）
+
+| ファイル | 変更内容 |
+|:---------|:---------|
+| `spec/kie/models/<model_name>_spec.rb` | モデルスペックの新規作成 |
+| `spec/integration/model_routing_spec.rb` | ルーティングテストへの追加 |
+
+### 3. ドキュメント変更（必須）
+
+| ファイル | 変更内容 |
+|:---------|:---------|
+| `README.md` | Supported Models テーブルへの追加 |
+| `docs/api/<category>/<model>.md` | API 仕様ドキュメントの新規作成 |
+| `docs/api/<category>/INDEX.md` | INDEX への参照追加 |
+
+## 詳細手順
+
+### Step 1: モデル定義ファイルの作成
+
+`lib/kie/models/<model_name>.rb` を作成します。
+
+**Suno モデルの場合:**
+
+```ruby
+# frozen_string_literal: true
+
+Kie::ModelRegistry.register(
+  Kie::ModelDefinition.new(
+    name: "<MODEL_NAME>",
+    category: :suno,
+    input_constraints: {
+      prompt: { type: :string, max_length: 3000, max_length_non_custom: 500 },
+      style: { type: :string, max_length: 200 },
+      title: { type: :string, max_length: 80 }
+    },
+    parameters: {}
+  )
+)
+```
+
+**General モデルの場合:**
+
+```ruby
+# frozen_string_literal: true
+
+Kie::ModelRegistry.register(
+  Kie::ModelDefinition.new(
+    name: "<model-name>",
+    category: :general,
+    input_constraints: {
+      prompt: { type: :string, max_length: 20_000, required: true },
+      images: { type: :array, max_items: 8, max_file_size: 30_000_000, formats: %w[jpeg png webp], required: false }
+    },
+    parameters: {
+      aspect_ratio: { type: :enum, values: %w[1:1 16:9], default: "1:1" },
+      resolution: { type: :enum, values: %w[1K 2K 4K], default: "1K" },
+      output_format: { type: :enum, values: %w[png jpg], default: "png" }
+    }
+  )
+)
+```
+
+### Step 2: lib/kie.rb への require 追加
+
+`lib/kie.rb` の末尾にある「Model definitions」セクションに追加します。
+
+```ruby
+# Model definitions
+require_relative "kie/models/nano_banana_pro"
+require_relative "kie/models/suno_v4"
+# ... 既存のモデル ...
+require_relative "kie/models/<model_name>"  # ← 追加
+```
+
+### Step 3: モデルスペックの作成
+
+`spec/kie/models/<model_name>_spec.rb` を作成します。
+
+```ruby
+# frozen_string_literal: true
+
+RSpec.describe "<MODEL_NAME> model definition" do
+  subject(:definition) { Kie::ModelRegistry.find("<MODEL_NAME>") }
+
+  it "is registered in ModelRegistry" do
+    expect(Kie::ModelRegistry.registered?("<MODEL_NAME>")).to be true
+  end
+
+  describe "basic attributes" do
+    it "has correct name" do
+      expect(definition.name).to eq("<MODEL_NAME>")
+    end
+
+    it "has correct category" do
+      expect(definition.category).to eq(:<category>)  # :suno or :general
+    end
+  end
+
+  describe "input constraints" do
+    # モデル固有の制約をテスト
+  end
+end
+```
+
+### Step 4: ルーティングテストへの追加
+
+`spec/integration/model_routing_spec.rb` の `expected_models` ハッシュに追加します。
+
+```ruby
+let(:expected_models) do
+  {
+    "nano-banana-pro" => :general,
+    "V4" => :suno,
+    # ... 既存のモデル ...
+    "<MODEL_NAME>" => :<category>  # ← 追加
+  }
+end
+```
+
+Suno モデルの場合は `shared_examples` のコンテキストも追加します。
+
+```ruby
+context "with <MODEL_NAME> model" do
+  include_examples "suno model routing", "<MODEL_NAME>"
+end
+```
+
+### Step 5: README の更新
+
+`README.md` の Supported Models セクションに追加します。
+
+**Suno モデルの場合:**
+
+```markdown
+### Suno Models (Music Generation)
+
+| Model | Description |
+|:------|:------------|
+| `V4` | Suno V4 |
+| ... |
+| `<MODEL_NAME>` | <Description> |  <!-- 追加 -->
+```
+
+**General モデルの場合:**
+
+```markdown
+### General Models (Image Generation)
+
+| Model | Description |
+|:------|:------------|
+| `nano-banana-pro` | High-quality image generation |
+| `<model-name>` | <Description> |  <!-- 追加 -->
+```
+
+### Step 6: API ドキュメントの作成
+
+`docs/api/<category>/<model>.md` を作成し、`docs/api/<category>/INDEX.md` に参照を追加します。
+
+## チェックリスト
+
+新モデル追加時は以下を確認してください:
+
+### コード
+
+- [ ] `lib/kie/models/<model_name>.rb` - モデル定義作成
+- [ ] `lib/kie.rb` - require 追加
+
+### テスト
+
+- [ ] `spec/kie/models/<model_name>_spec.rb` - スペック作成
+- [ ] `spec/integration/model_routing_spec.rb` - ルーティングテスト追加
+
+### ドキュメント
+
+- [ ] `README.md` - Supported Models 更新
+- [ ] `docs/api/<category>/<model>.md` - API 仕様作成
+- [ ] `docs/api/<category>/INDEX.md` - INDEX 更新
+
+### 検証
+
+- [ ] 全テスト通過確認: `bundle exec rspec`
+- [ ] Lint 通過確認: `bundle exec rubocop`

data/docs/development/technical-design.md

@@ -67,11 +67,5 @@ GitHub Actions による自動化：
 - SimpleCov によるカバレッジ測定
 
 ### 拡張方法
-新モデル追加は定義ファイルの編集のみ：
-```yaml
-model_name: "new-model"
-format_type: "Standard"
-validations:
-  input_length: 1000
-  aspect_ratios: ["16:9", "1:1"]
-```
+
+新モデルを追加する際の詳細な手順は [adding-new-model.md](./adding-new-model.md) を参照してください。

data/lib/kie/models/flux_2_flex_image_to_image.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+Kie::ModelRegistry.register(
+  Kie::ModelDefinition.new(
+    name: "flux-2/flex-image-to-image",
+    category: :general,
+    input_constraints: {
+      prompt: { type: :string, max_length: 5_000, required: true },
+      input_urls: { type: :array, max_items: 8, max_file_size: 10_000_000, formats: %w[jpeg png webp], required: true }
+    },
+    parameters: {
+      aspect_ratio: { type: :enum, values: %w[1:1 4:3 3:4 16:9 9:16 3:2 2:3 auto], default: "1:1" },
+      resolution: { type: :enum, values: %w[1K 2K], default: "1K" }
+    }
+  )
+)

data/lib/kie/models/flux_2_flex_text_to_image.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+Kie::ModelRegistry.register(
+  Kie::ModelDefinition.new(
+    name: "flux-2/flex-text-to-image",
+    category: :general,
+    input_constraints: {
+      prompt: { type: :string, max_length: 5_000, required: true }
+    },
+    parameters: {
+      aspect_ratio: { type: :enum, values: %w[1:1 4:3 3:4 16:9 9:16 3:2 2:3 auto], default: "1:1" },
+      resolution: { type: :enum, values: %w[1K 2K], default: "1K" }
+    }
+  )
+)

data/lib/kie/models/flux_2_pro_image_to_image.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+Kie::ModelRegistry.register(
+  Kie::ModelDefinition.new(
+    name: "flux-2/pro-image-to-image",
+    category: :general,
+    input_constraints: {
+      prompt: { type: :string, max_length: 5_000, required: true },
+      input_urls: { type: :array, max_items: 8, max_file_size: 10_000_000, formats: %w[jpeg png webp], required: true }
+    },
+    parameters: {
+      aspect_ratio: { type: :enum, values: %w[1:1 4:3 3:4 16:9 9:16 3:2 2:3 auto], default: "4:3" },
+      resolution: { type: :enum, values: %w[1K 2K], default: "1K" }
+    }
+  )
+)

data/lib/kie/models/grok_imagine_image_to_image.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+Kie::ModelRegistry.register(
+  Kie::ModelDefinition.new(
+    name: "grok-imagine/image-to-image",
+    category: :general,
+    input_constraints: {
+      prompt: { type: :string, max_length: 390_000, required: false },
+      image_urls: {
+        type: :array, max_items: 1, max_file_size: 10_000_000, formats: %w[jpeg png webp], required: true
+      }
+    },
+    parameters: {}
+  )
+)

data/lib/kie/models/grok_imagine_image_to_video.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+Kie::ModelRegistry.register(
+  Kie::ModelDefinition.new(
+    name: "grok-imagine/image-to-video",
+    category: :general,
+    input_constraints: {
+      prompt: { type: :string, max_length: 5_000, required: false },
+      image_urls: {
+        type: :array, max_items: 1, max_file_size: 10_000_000, formats: %w[jpeg png webp], required: false
+      },
+      task_id: { type: :string, max_length: 100, required: false },
+      index: { type: :number, min: 0, max: 5, required: false }
+    },
+    parameters: {
+      mode: { type: :enum, values: %w[fun normal spicy], default: "normal" }
+    }
+  )
+)

data/lib/kie/models/grok_imagine_text_to_image.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+Kie::ModelRegistry.register(
+  Kie::ModelDefinition.new(
+    name: "grok-imagine/text-to-image",
+    category: :general,
+    input_constraints: {
+      prompt: { type: :string, max_length: 5_000, required: true }
+    },
+    parameters: {
+      aspect_ratio: { type: :enum, values: %w[2:3 3:2 1:1 9:16 16:9], default: "3:2" }
+    }
+  )
+)

data/lib/kie/models/grok_imagine_text_to_video.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+Kie::ModelRegistry.register(
+  Kie::ModelDefinition.new(
+    name: "grok-imagine/text-to-video",
+    category: :general,
+    input_constraints: {
+      prompt: { type: :string, max_length: 5_000, required: true }
+    },
+    parameters: {
+      aspect_ratio: { type: :enum, values: %w[2:3 3:2 1:1 9:16 16:9], default: "2:3" },
+      mode: { type: :enum, values: %w[fun normal spicy], default: "normal" }
+    }
+  )
+)

data/lib/kie/models/grok_imagine_upscale.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+Kie::ModelRegistry.register(
+  Kie::ModelDefinition.new(
+    name: "grok-imagine/upscale",
+    category: :general,
+    input_constraints: {
+      task_id: { type: :string, max_length: 100, required: true }
+    },
+    parameters: {}
+  )
+)

data/lib/kie/models/seedream_4_5_edit.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+Kie::ModelRegistry.register(
+  Kie::ModelDefinition.new(
+    name: "seedream/4.5-edit",
+    category: :general,
+    input_constraints: {
+      prompt: { type: :string, max_length: 3_000, required: true },
+      image_urls: { type: :array, max_file_size: 10_000_000, formats: %w[jpeg png webp], required: true }
+    },
+    parameters: {
+      aspect_ratio: { type: :enum, values: %w[1:1 4:3 3:4 16:9 9:16 2:3 3:2 21:9], default: "1:1" },
+      quality: { type: :enum, values: %w[basic high], default: "basic" }
+    }
+  )
+)

data/lib/kie/models/seedream_4_5_text_to_image.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+Kie::ModelRegistry.register(
+  Kie::ModelDefinition.new(
+    name: "seedream/4.5-text-to-image",
+    category: :general,
+    input_constraints: {
+      prompt: { type: :string, max_length: 3_000, required: true }
+    },
+    parameters: {
+      aspect_ratio: { type: :enum, values: %w[1:1 4:3 3:4 16:9 9:16 2:3 3:2 21:9], default: "1:1" },
+      quality: { type: :enum, values: %w[basic high], default: "basic" }
+    }
+  )
+)

data/lib/kie/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kie
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/kie.rb

@@ -24,3 +24,13 @@ require_relative "kie/models/suno_v4_5"
 require_relative "kie/models/suno_v4_5_plus"
 require_relative "kie/models/suno_v4_5_all"
 require_relative "kie/models/suno_v5"
+require_relative "kie/models/seedream_4_5_edit"
+require_relative "kie/models/seedream_4_5_text_to_image"
+require_relative "kie/models/flux_2_pro_image_to_image"
+require_relative "kie/models/flux_2_flex_image_to_image"
+require_relative "kie/models/flux_2_flex_text_to_image"
+require_relative "kie/models/grok_imagine_image_to_video"
+require_relative "kie/models/grok_imagine_text_to_video"
+require_relative "kie/models/grok_imagine_image_to_image"
+require_relative "kie/models/grok_imagine_text_to_image"
+require_relative "kie/models/grok_imagine_upscale"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kie-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Sho DOUHASHI
@@ -32,10 +32,13 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".claude/agents/project-environment-setup.md"
+- ".claude/commands/add-model.md"
+- ".claude/commands/release.md"
 - ".claude/commands/soba/implement.md"
 - ".claude/commands/soba/plan.md"
 - ".claude/commands/soba/review.md"
 - ".claude/commands/soba/revise.md"
+- ".claude/commands/update-model.md"
 - ".devcontainer/LICENSE"
 - ".devcontainer/README.md"
 - ".devcontainer/bin/devcontainer-common.sh"
@@ -55,9 +58,28 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- docs/api/INDEX.md
+- docs/api/general/INDEX.md
+- docs/api/general/flux-2-flex-image-to-image.md
+- docs/api/general/flux-2-flex-text-to-image.md
+- docs/api/general/flux-2-pro-image-to-image.md
+- docs/api/general/grok-imagine-image-to-image.md
+- docs/api/general/grok-imagine-image-to-video.md
+- docs/api/general/grok-imagine-text-to-image.md
+- docs/api/general/grok-imagine-text-to-video.md
+- docs/api/general/grok-imagine-upscale.md
+- docs/api/general/nano-banana-pro.md
+- docs/api/general/seedream-4-5-edit.md
+- docs/api/general/seedream-4-5-text-to-image.md
+- docs/api/overview.md
+- docs/api/suno/INDEX.md
+- docs/api/suno/generate.md
+- docs/api/suno/models.md
+- docs/api/suno/task-status.md
 - docs/business/INDEX.md
 - docs/business/overview.md
 - docs/development/INDEX.md
+- docs/development/adding-new-model.md
 - docs/development/technical-design.md
 - docs/document_system.md
 - lefthook.yml
@@ -69,7 +91,17 @@ files:
 - lib/kie/middleware/raise_error.rb
 - lib/kie/model_definition.rb
 - lib/kie/model_registry.rb
+- lib/kie/models/flux_2_flex_image_to_image.rb
+- lib/kie/models/flux_2_flex_text_to_image.rb
+- lib/kie/models/flux_2_pro_image_to_image.rb
+- lib/kie/models/grok_imagine_image_to_image.rb
+- lib/kie/models/grok_imagine_image_to_video.rb
+- lib/kie/models/grok_imagine_text_to_image.rb
+- lib/kie/models/grok_imagine_text_to_video.rb
+- lib/kie/models/grok_imagine_upscale.rb
 - lib/kie/models/nano_banana_pro.rb
+- lib/kie/models/seedream_4_5_edit.rb
+- lib/kie/models/seedream_4_5_text_to_image.rb
 - lib/kie/models/suno_v4.rb
 - lib/kie/models/suno_v4_5.rb
 - lib/kie/models/suno_v4_5_all.rb