kie-ruby 0.1.0

data/README.md

@@ -0,0 +1,310 @@
+# kie-ruby
+
+[![CI](https://github.com/douhashi/kie-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/douhashi/kie-ruby/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/kie-ruby.svg)](https://badge.fury.io/rb/kie-ruby)
+
+A Ruby client library for interacting with the [Kie.ai](https://kie.ai) API. Supports both General models for image generation and Suno models for music generation.
+
+## Requirements
+
+- Ruby 3.0 or higher
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "kie-ruby"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install kie-ruby
+```
+
+## Quick Start
+
+### Setting up your API Key
+
+Get your API key from [Kie.ai](https://kie.ai) and configure it:
+
+**Option 1: Environment variable (Recommended)**
+
+```bash
+export KIE_API_KEY=your_api_key_here
+```
+
+```ruby
+require "kie"
+
+client = Kie::Client.new
+```
+
+**Option 2: Direct configuration**
+
+```ruby
+require "kie"
+
+client = Kie::Client.new(api_key: "your_api_key_here")
+```
+
+## Usage Examples
+
+### Image Generation (General API)
+
+Generate images using the `nano-banana-pro` model:
+
+```ruby
+require "kie"
+
+client = Kie::Client.new
+
+# Create an image generation task
+task = client.general.generate(
+  model: "nano-banana-pro",
+  input: { prompt: "A serene Japanese garden with cherry blossoms" },
+  aspect_ratio: "16:9",
+  resolution: "2K",
+  output_format: "png"
+)
+
+# Wait for completion (polls automatically)
+task.wait
+
+# Get the generated image URLs
+task.urls.each do |url|
+  puts url
+end
+```
+
+### Music Generation (Suno API)
+
+Generate music using the Suno V5 model:
+
+**Simple mode (describe the song):**
+
+```ruby
+require "kie"
+
+client = Kie::Client.new
+
+# Create a music generation task
+task = client.suno.generate(
+  model: "V5",
+  input: {
+    prompt: "An upbeat electronic dance track with energetic synths",
+    callback_url: "https://your-server.com/webhook"  # Optional webhook URL
+  }
+)
+
+# Wait for completion with progress monitoring
+task.wait(timeout: 600, interval: 5)
+
+# Get the generated audio and cover image URLs
+puts "Audio files:"
+task.audio_urls.each { |url| puts "  #{url}" }
+
+puts "Cover images:"
+task.image_urls.each { |url| puts "  #{url}" }
+```
+
+**Custom mode (specify lyrics and style):**
+
+```ruby
+task = client.suno.generate(
+  model: "V5",
+  input: {
+    custom_mode: true,
+    prompt: "[Verse]\nWalking through the city lights\n[Chorus]\nWe are alive tonight",
+    style: "Pop, Electronic, Upbeat",
+    title: "City Lights",
+    callback_url: "https://your-server.com/webhook"
+  }
+)
+
+task.wait(timeout: 600)
+
+task.audio_urls.each { |url| puts url }
+```
+
+### Monitoring Task Progress
+
+You can check task status manually instead of using `wait`:
+
+```ruby
+task = client.general.generate(model: "nano-banana-pro", input: { prompt: "A sunset" })
+
+loop do
+  task.refresh!
+
+  case task.status
+  when :processing
+    puts "Still processing..."
+  when :success
+    puts "Done! URLs: #{task.urls}"
+    break
+  when :failed
+    puts "Failed: #{task.error_message}"
+    break
+  end
+
+  sleep 3
+end
+```
+
+## Error Handling
+
+The library provides structured exception classes for different error scenarios:
+
+```ruby
+require "kie"
+
+client = Kie::Client.new
+
+begin
+  task = client.general.generate(
+    model: "nano-banana-pro",
+    input: { prompt: "A beautiful landscape" }
+  )
+  task.wait
+
+  puts task.urls
+rescue Kie::AuthenticationError => e
+  # Invalid or missing API key (HTTP 401)
+  puts "Authentication failed: #{e.message}"
+
+rescue Kie::InsufficientCreditsError => e
+  # Not enough credits (HTTP 402)
+  puts "Insufficient credits. Please top up your account."
+
+rescue Kie::RateLimitError => e
+  # Too many requests (HTTP 429)
+  puts "Rate limited. Please wait and retry."
+  sleep 10
+  retry
+
+rescue Kie::ContentPolicyError => e
+  # Content violates policy (e.g., SENSITIVE_WORD_ERROR)
+  puts "Content policy violation: #{e.message}"
+
+rescue Kie::TimeoutError => e
+  # Task did not complete within the timeout period
+  puts "Task timed out"
+
+rescue Kie::TaskFailedError => e
+  # Task failed during processing
+  puts "Task failed: #{e.message}"
+  puts "Fail code: #{e.fail_code}"
+
+rescue Kie::ApiError => e
+  # Other API errors
+  puts "API error (#{e.status_code}): #{e.message}"
+end
+```
+
+### Handling Task Failures Without Exceptions
+
+If you prefer to handle failures without exceptions:
+
+```ruby
+task = client.suno.generate(
+  model: "V5",
+  input: { prompt: "A jazz song", callback_url: "https://your-server.com/webhook" }
+)
+task.wait(raise_on_failure: false)
+
+if task.failed?
+  puts "Task failed: #{task.error_message}"
+else
+  puts "Success! #{task.urls}"
+end
+```
+
+## Supported Models
+
+### Suno Models (Music Generation)
+
+| Model | Description |
+|:------|:------------|
+| `V4` | Suno V4 |
+| `V4_5` | Suno V4.5 |
+| `V4_5PLUS` | Suno V4.5+ |
+| `V4_5ALL` | Suno V4.5 ALL |
+| `V5` | Suno V5 (Latest) |
+
+**Suno model input parameters:**
+
+| Parameter | Type | Description |
+|:----------|:-----|:------------|
+| `prompt` | String | Song description or lyrics (required) |
+| `callback_url` | String | Webhook URL for notifications (optional) |
+| `custom_mode` | Boolean | Enable custom mode for lyrics input |
+| `style` | String | Music style (custom mode only) |
+| `title` | String | Song title (custom mode only) |
+| `instrumental` | Boolean | Generate instrumental only |
+
+### General Models (Image Generation)
+
+| Model | Description |
+|:------|:------------|
+| `nano-banana-pro` | High-quality image generation |
+
+**General model parameters:**
+
+| Parameter | Values | Default |
+|:----------|:-------|:--------|
+| `aspect_ratio` | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`, `auto` | `1:1` |
+| `resolution` | `1K`, `2K`, `4K` | `1K` |
+| `output_format` | `png`, `jpg` | `png` |
+
+## Platform Limits
+
+| Item | Limit |
+|:-----|:------|
+| Rate limit | 20 requests per 10 seconds |
+| Concurrent tasks | 100 |
+| Polling rate | 3 requests per second per task |
+| File retention | 14 days |
+
+## Development
+
+### Setup
+
+After checking out the repo, run the setup script to install dependencies:
+
+```bash
+bin/setup
+```
+
+### Running Tests
+
+```bash
+bundle exec rspec
+```
+
+### Linting
+
+```bash
+bundle exec rubocop
+```
+
+### Interactive Console
+
+```bash
+bin/console
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/douhashi/kie-ruby.
+
+## License
+
+This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docs/business/INDEX.md

@@ -0,0 +1,3 @@
+# Business Documents
+
+- `overview.md`: プロジェクト概要、設計思想、プラットフォーム仕様

data/docs/business/overview.md

@@ -0,0 +1,35 @@
+# Kie.ai Ruby Client: プロジェクト概要
+
+## 背景
+Kie.ai は、Suno（音楽生成）、Grok Imagine（動画生成）、Nano Banana Pro（画像生成）など、多様な AI モデルを統合提供するプラットフォームです。API の進化過程で生じた「Suno（音楽生成用）」と「General（画像/動画生成用）」の2つのフォーマットが混在しており、本 Gem はその差異を抽象化し、Ruby らしい統一的なインターフェースを提供します。
+
+## 設計思想
+
+### 🎯 ミニマリスト原則
+- **Zero Bloat**: Zeitwerk や ActiveSupport 等の大型ライブラリを排除
+- **Explicit Over Implicit**: 依存関係を明示的に定義、副作用の最小化
+- **Lean & Robust**: 実行時依存は Faraday のみ
+
+### 💎 Ruby らしさの追求
+- `task.wait { |status| ... }` のようなブロック構文での進捗監視
+- DSL 的な記述を可能にする設計
+- 慣習に従った命名規則とメソッドチェーン
+
+### 🔍 透明性の確保
+- API エラーの詳細を構造化された例外として報告
+- デバッグしやすい透明性の高い実装
+- データ駆動型設計で新モデル追加を容易に
+
+## プラットフォーム仕様
+
+### 制約事項
+| 項目 | 仕様 |
+|:---|:---|
+| **データ保持** | 生成ファイル: 14日間 / ログ: 2ヶ月間 |
+| **レート制限** | 10秒間に20リクエスト / 並行100タスク |
+| **ポーリング** | 同一タスク: 1秒間に3リクエスト |
+| **処理方式** | 全タスク非同期（task_id による追跡） |
+
+### モデル分類
+- **Suno (音楽生成)**: V4, V4_5, V4_5ALL, V4_5PLUS, V5
+- **General (画像/動画生成)**: nano-banana-pro, grok-imagine/text-to-video 等

data/docs/development/INDEX.md

@@ -0,0 +1,3 @@
+# Development Documents
+
+- `technical-design.md`: アーキテクチャ、技術設計、開発環境

data/docs/development/technical-design.md

@@ -0,0 +1,77 @@
+# Kie.ai Ruby Client: 技術設計
+
+## アーキテクチャ
+
+### デュアルエンジン構造
+Suno と General の2つの API フォーマットをアダプター層で吸収：
+
+```
+User Code
+    ↓
+Kie::Client (統一インターフェース)
+    ↓
+ModelRegistry (ルーティング判定)
+   ／        ＼
+Suno API    General API
+ (音楽)      (画像等)
+```
+
+### 主要コンポーネント
+
+#### 1. Kie::ModelRegistry
+各モデルの API 系統を管理：
+- Suno: `/api/v1/generate`
+- General: `/api/v1/jobs/createTask`
+
+#### 2. Kie::Task
+レスポンス構造の正規化：
+- Suno: `data.response.sunoData[].audioUrl`
+- General: `data.resultJson` → parse → `resultUrls[]`
+
+#### 3. Kie::Poller
+指数バックオフによるポーリング：
+- 0-30秒: 2-3秒間隔
+- 30秒以降: 5-10秒間隔
+
+## エラーハンドリング
+
+### HTTP ステータス
+| コード | 意味 | 対処 |
+|:---|:---|:---|
+| 401 | 認証エラー | API キー確認 |
+| 402 | クレジット不足 | チャージ必要 |
+| 429 | レート制限 | リトライ |
+| 455 | メンテナンス | 待機 |
+
+### タスクエラー
+- Suno: `msg` フィールド
+- General: `failMsg` フィールド
+- 著作権/ポリシー違反は専用例外クラス
+
+## 開発環境
+
+### 依存関係
+**実行時:**
+- Faraday (HTTP 通信のみ)
+
+**開発時:**
+- RSpec (テスト)
+- WebMock (API モック)
+- RuboCop (コード品質)
+
+### CI/CD
+GitHub Actions による自動化：
+- Ruby 3.0〜3.3 での互換性テスト
+- RuboCop による静的解析
+- Bundler Audit によるセキュリティチェック
+- SimpleCov によるカバレッジ測定
+
+### 拡張方法
+新モデル追加は定義ファイルの編集のみ：
+```yaml
+model_name: "new-model"
+format_type: "Standard"
+validations:
+  input_length: 1000
+  aspect_ratios: ["16:9", "1:1"]
+```

data/docs/document_system.md

@@ -0,0 +1,58 @@
+You are part of a documentation-aware AI system.
+
+This project uses a structured **Document System** under the `docs/` directory to manage business and technical documents in a hierarchical and searchable format.
+
+## Folder Structure Overview
+
+```
+docs/
+├── business/                  # Business documents
+│   ├── INDEX.md              # Index file for this folder
+│   ├── overview.md           # Project overview
+│   └── model.md              # Business model description
+│
+├── development/              # Development-related documents
+│   ├── INDEX.md              # Index file for this folder
+│   ├── guideline.md          # Development guide
+│   └── coding-rule.md        # Coding standards
+│
+├── operations/               # (Planned) Operational documents
+│   ├── INDEX.md              # Index file for this folder
+│   ├── server.md             # Server operations
+│   └── monitoring.md         # Monitoring and incident response
+```
+
+## Document Characteristics
+
+- All documents are written in Markdown format.
+- Each directory contains an `INDEX.md` file listing:
+  - The filenames in the same directory
+  - A brief description for each
+
+Example:
+```markdown
+# Development Documents
+
+- `guideline.md`: A guide to the development workflow.
+- `coding-rule.md`: Coding standards for this project.
+```
+
+## Integration with CLAUDE.md
+
+The AI system does **not directly reference documents**. Instead, it recognizes document availability via `CLAUDE.md`, where paths are listed using the format:
+
+```
+@docs/development/INDEX.md
+```
+
+This tells the AI:  
+- The document exists  
+- It may be referenced when needed  
+- But the AI should **autonomously decide** which document to consult
+
+## Purpose
+
+The Document System allows AI agents to:
+- Navigate structured, maintainable documentation
+- Understand the project context through index files
+- Autonomously choose and reference relevant documents during tasks

data/lefthook.yml

@@ -0,0 +1,8 @@
+# Lefthook configuration
+# https://github.com/evilmartians/lefthook
+
+pre-commit:
+  commands:
+    rubocop:
+      glob: "*.rb"
+      run: .lefthook/rubocop-autofix.sh {staged_files}

data/lib/kie/client.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Kie
+  # HTTP client for Kie.ai API
+  class Client
+    BASE_URL = "https://api.kie.ai"
+
+    attr_reader :api_key
+
+    def initialize(api_key: nil)
+      @api_key = api_key || ENV.fetch("KIE_API_KEY", nil)
+
+      return unless @api_key.nil? || @api_key.empty?
+
+      raise ConfigurationError, "API key is required. Pass it as an argument or set KIE_API_KEY environment variable."
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: BASE_URL) do |conn|
+        conn.headers["Authorization"] = "Bearer #{api_key}"
+        conn.headers["Content-Type"] = "application/json"
+        conn.use Middleware::RaiseError
+      end
+    end
+
+    def general
+      @general ||= GeneralEngine.new(client: self)
+    end
+
+    def suno
+      @suno ||= SunoEngine.new(client: self)
+    end
+  end
+end

data/lib/kie/errors.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Kie
+  class ConfigurationError < Error; end
+  class UnknownModelError < Error; end
+  class ValidationError < Error; end
+
+  # Base class for API-related errors with HTTP status and response details
+  class ApiError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(message = nil, status_code: nil, response_body: nil)
+      super(message)
+      @status_code = status_code
+      @response_body = response_body
+    end
+  end
+
+  class TaskCreationError < ApiError; end
+  class NotFoundError < ApiError; end
+  class InsufficientCreditsError < ApiError; end
+  class RateLimitError < ApiError; end
+  class InvalidParametersError < ApiError; end
+  class AuthenticationError < ApiError; end
+  class ServerError < ApiError; end
+  class ServiceUnavailableError < ApiError; end
+
+  # Raised when an asynchronous task fails during execution
+  class TaskFailedError < ApiError
+    attr_reader :fail_code
+
+    def initialize(message = nil, fail_code: nil, status_code: nil, response_body: nil)
+      super(message, status_code: status_code, response_body: response_body)
+      @fail_code = fail_code
+    end
+  end
+
+  # Raised when content violates policy (SENSITIVE_WORD_ERROR, CONTENT_POLICY, etc.)
+  class ContentPolicyError < TaskFailedError; end
+
+  # Raised when a task wait operation times out
+  class TimeoutError < Error; end
+end

data/lib/kie/general_engine.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Kie
+  # Engine for General API endpoints (/api/v1/jobs/*)
+  class GeneralEngine
+    CREATE_TASK_ENDPOINT = "/api/v1/jobs/createTask"
+
+    def initialize(client:)
+      @client = client
+    end
+
+    def generate(model:, input:, **parameters)
+      definition = ModelRegistry.find(model)
+      response = @client.connection.post(CREATE_TASK_ENDPOINT) do |req|
+        req.body = build_request_body(definition, input, parameters)
+      end
+
+      handle_response(response)
+    end
+
+    private
+
+    def build_request_body(definition, input, parameters)
+      merged_input = input.merge(parameters)
+      merged_input[:callBackUrl] ||= "https://example.invalid/callback"
+
+      {
+        model: definition.name,
+        input: merged_input
+      }.to_json
+    end
+
+    def handle_response(response)
+      data = JSON.parse(response.body)
+      handle_api_error(data) unless data["code"] == 200
+
+      GeneralTask.new(client: @client, task_id: data["data"]["taskId"])
+    end
+
+    def handle_api_error(data)
+      error_class = error_class_for_code(data["code"])
+      raise error_class.new(data["msg"], status_code: data["code"], response_body: data.to_json)
+    end
+
+    def error_class_for_code(code)
+      case code
+      when 400 then InvalidParametersError
+      when 402 then InsufficientCreditsError
+      when 429 then RateLimitError
+      else ApiError
+      end
+    end
+  end
+end