kie-ruby 0.1.0 → 0.2.0

data/docs/api/general/seedream-4-5-text-to-image.md

@@ -0,0 +1,245 @@
+# Seedream 4.5 Text-to-Image API
+
+Seedream 4.5 Text-to-Image 画像生成 API。
+
+## 概要
+
+Seedream 4.5 Text-to-Image はテキストプロンプトから高品質な画像を生成するモデル。入力画像を必要としない純粋な text-to-image 生成が可能。
+
+## タスク作成
+
+### エンドポイント
+
+```
+POST /api/v1/jobs/createTask
+```
+
+### リクエストパラメータ
+
+#### トップレベル
+
+| パラメータ | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| `model` | string | Yes | `"seedream/4.5-text-to-image"` 固定 |
+| `input` | object | Yes | 生成パラメータ |
+| `callBackUrl` | string | No | タスク完了時の Webhook URL |
+
+#### input オブジェクト
+
+| パラメータ | 型 | 必須 | デフォルト | 説明 |
+|-----------|-----|------|-----------|------|
+| `prompt` | string | Yes | - | 画像の説明（最大 3,000 文字） |
+| `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 解像度（高品質） |
+
+### リクエスト例
+
+#### 基本的な画像生成
+
+```json
+{
+  "model": "seedream/4.5-text-to-image",
+  "input": {
+    "prompt": "A serene Japanese garden with cherry blossoms in spring"
+  }
+}
+```
+
+#### 詳細なパラメータ指定
+
+```json
+{
+  "model": "seedream/4.5-text-to-image",
+  "input": {
+    "prompt": "A futuristic cityscape at sunset with flying cars and neon lights",
+    "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-text-to-image",
+    "state": "success",
+    "param": "{\"prompt\":\"...\"}",
+    "resultJson": "{\"resultUrls\":[\"https://...\"]}",
+    "costTime": 12000,
+    "createTime": 1704067200000,
+    "completeTime": 1704067212000
+  }
+}
+```
+
+#### 処理中
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "seedream/4.5-text-to-image",
+    "state": "waiting"
+  }
+}
+```
+
+#### 失敗時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "model": "seedream/4.5-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: "seedream/4.5-text-to-image",
+  input: {
+    prompt: "A majestic mountain landscape at dawn"
+  }
+)
+
+# パラメータ指定
+task = client.general.generate(
+  model: "seedream/4.5-text-to-image",
+  input: {
+    prompt: "An abstract digital art piece with vibrant colors"
+  },
+  aspect_ratio: "16:9",
+  quality: "high"
+)
+
+# 結果を取得
+task.wait
+
+if task.success?
+  image_url = task.urls.first
+  puts "Generated: #{image_url}"
+else
+  puts "Failed: #{task.error_message}"
+end
+```
+
+## seedream/4.5-edit との違い
+
+| 項目 | seedream/4.5-text-to-image | seedream/4.5-edit |
+|------|---------------------------|-------------------|
+| 入力画像 | 不要 | 必須 |
+| 用途 | テキストから新規画像生成 | 既存画像の編集・変換 |
+| prompt | 画像の説明 | 編集指示 |
+
+## コード参照
+
+モデル定義は以下のファイルで管理されている：
+
+- `lib/kie/models/seedream_4_5_text_to_image.rb`
+
+## 関連ドキュメント
+
+- [API 共通仕様](../overview.md)
+- [Seedream 4.5 Edit API](seedream-4-5-edit.md)
+- [Nano Banana Pro API](nano-banana-pro.md)

data/docs/api/overview.md

@@ -0,0 +1,92 @@
+# API 共通仕様
+
+Kie.ai API の共通仕様について説明する。
+
+## 認証
+
+すべての API リクエストには Bearer トークンによる認証が必要。
+
+```
+Authorization: Bearer <API_KEY>
+```
+
+## 共通レスポンス形式
+
+### 成功レスポンス
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+  }
+}
+```
+
+### エラーレスポンス
+
+```json
+{
+  "code": 400,
+  "msg": "Invalid parameters"
+}
+```
+
+## ステータスコード
+
+| コード | 説明 | Ruby クラス |
+|--------|------|-------------|
+| 200 | 成功 | - |
+| 400 | パラメータエラー | `Kie::InvalidParametersError` |
+| 402 | クレジット不足 | `Kie::InsufficientCreditsError` |
+| 422 | バリデーションエラー | `Kie::InvalidParametersError` |
+| 429 | レート制限 | `Kie::RateLimitError` |
+
+## コールバック URL
+
+非同期処理の完了通知を受け取るための Webhook URL。
+
+### 仕様
+
+- パラメータ名: `callBackUrl` (Suno) / `callBackUrl` (General)
+- 形式: 有効な HTTP/HTTPS URL
+- タスク完了時に POST リクエストが送信される
+
+### コールバックペイロード例
+
+```json
+{
+  "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "status": "SUCCESS",
+  "data": { ... }
+}
+```
+
+## タスクステータス
+
+### Suno タスクステータス
+
+| ステータス | 説明 |
+|-----------|------|
+| `PENDING` | 処理待ち |
+| `TEXT_SUCCESS` | テキスト処理完了 |
+| `FIRST_SUCCESS` | 最初の生成完了 |
+| `SUCCESS` | 完了 |
+| `CREATE_TASK_FAILED` | タスク作成失敗 |
+| `GENERATE_AUDIO_FAILED` | 音声生成失敗 |
+| `CALLBACK_EXCEPTION` | コールバック例外 |
+| `SENSITIVE_WORD_ERROR` | 禁止ワード検出 |
+
+### General タスクステータス
+
+| ステータス | 説明 |
+|-----------|------|
+| `waiting` | 処理待ち |
+| `success` | 完了 |
+| `fail` | 失敗 |
+
+## 関連ドキュメント
+
+- [Suno API](./suno/INDEX.md)
+- [General API](./general/INDEX.md)

data/docs/api/suno/INDEX.md

@@ -0,0 +1,44 @@
+# Suno API
+
+Suno 音楽生成 API のドキュメント。
+
+## ドキュメント一覧
+
+- `generate.md`: 音楽生成 API（Generate Music）
+- `task-status.md`: タスクステータス取得 API
+- `models.md`: モデルバージョン別仕様
+
+## 概要
+
+Suno API は AI による音楽生成を提供する。テキストプロンプトから楽曲を生成し、非同期でタスク結果を取得する。
+
+### エンドポイント
+
+| 操作 | エンドポイント | メソッド |
+|------|---------------|---------|
+| 音楽生成 | `/api/v1/generate` | POST |
+| ステータス取得 | `/api/v1/generate/{taskId}` | GET |
+
+### Ruby クライアントでの使用例
+
+```ruby
+client = Kie::Client.new(api_key: "your-api-key")
+
+# 音楽を生成
+task = client.generate(
+  model: "V4_5",
+  input: {
+    prompt: "A happy pop song about summer",
+    custom_mode: false,
+    instrumental: false
+  }
+)
+
+# 結果を取得
+result = task.wait
+```
+
+## 関連ドキュメント
+
+- [API 共通仕様](../overview.md)
+- [General API](../general/INDEX.md)

data/docs/api/suno/generate.md

@@ -0,0 +1,154 @@
+# Suno Generate Music API
+
+音楽を生成する API。
+
+## エンドポイント
+
+```
+POST /api/v1/generate
+```
+
+## リクエストパラメータ
+
+### 必須パラメータ
+
+| パラメータ | 型 | 説明 |
+|-----------|-----|------|
+| `model` | string | モデルバージョン。[モデル一覧](./models.md)を参照 |
+| `customMode` | boolean | カスタムモードの有効化。詳細な制御が可能になる |
+| `instrumental` | boolean | `true` の場合、ボーカルなしの楽曲を生成 |
+| `prompt` | string | 楽曲の説明またはリリック。文字数制限は[モデル別仕様](./models.md)を参照 |
+
+### 条件付き必須パラメータ
+
+`customMode: true` の場合に必要。
+
+| パラメータ | 型 | 説明 |
+|-----------|-----|------|
+| `style` | string | 音楽のジャンルや雰囲気。文字数制限は[モデル別仕様](./models.md)を参照 |
+| `title` | string | 楽曲タイトル（最大 80 文字） |
+
+### オプションパラメータ
+
+| パラメータ | 型 | 値 | 説明 |
+|-----------|-----|-----|------|
+| `callBackUrl` | string | URL | タスク完了時の Webhook URL |
+| `negativeTags` | string | - | 除外するスタイルや特性 |
+| `vocalGender` | string | `m`, `f` | ボーカルの性別（`customMode: true` 時のみ有効） |
+| `styleWeight` | number | 0–1 | スタイル適用の強度（小数点以下 2 桁） |
+| `weirdnessConstraint` | number | 0–1 | 創造的逸脱の制御（小数点以下 2 桁） |
+| `audioWeight` | number | 0–1 | オーディオ特性のバランス（小数点以下 2 桁） |
+| `personaId` | string | - | カスタムペルソナ ID（`customMode: true` 時のみ有効） |
+
+## リクエスト例
+
+### シンプルモード
+
+```json
+{
+  "model": "V4_5",
+  "customMode": false,
+  "instrumental": false,
+  "prompt": "A happy pop song about summer vacation",
+  "callBackUrl": "https://example.com/webhook"
+}
+```
+
+### カスタムモード
+
+```json
+{
+  "model": "V5",
+  "customMode": true,
+  "instrumental": false,
+  "prompt": "[Verse 1]\nSunshine on the beach...\n[Chorus]\nSummer days are here...",
+  "style": "upbeat pop, acoustic guitar, summer vibes",
+  "title": "Summer Days",
+  "negativeTags": "sad, melancholic",
+  "vocalGender": "f",
+  "callBackUrl": "https://example.com/webhook"
+}
+```
+
+### インストゥルメンタル
+
+```json
+{
+  "model": "V4_5",
+  "customMode": true,
+  "instrumental": true,
+  "prompt": "Background music for a video game",
+  "style": "orchestral, epic, cinematic",
+  "title": "Epic Adventure",
+  "callBackUrl": "https://example.com/webhook"
+}
+```
+
+## レスポンス
+
+### 成功時
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+  }
+}
+```
+
+### エラー時
+
+```json
+{
+  "code": 400,
+  "msg": "Invalid parameters"
+}
+```
+
+## 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
+  }
+)
+
+# カスタムモード
+task = client.generate(
+  model: "V5",
+  input: {
+    prompt: "[Verse]\nLyrics here...",
+    custom_mode: true,
+    instrumental: false,
+    style: "pop, acoustic",
+    title: "My Song",
+    negative_tags: "sad",
+    vocal_gender: "f"
+  }
+)
+```
+
+## バリデーション
+
+クライアントライブラリは以下のバリデーションを実行する：
+
+- `prompt` の文字数がモデル・モードの制限内か
+- `style` の文字数がモデルの制限内か（`customMode: true` 時）
+- `title` が 80 文字以内か（`customMode: true` 時）
+
+バリデーションエラー時は `Kie::ValidationError` が発生する。
+
+## 関連ドキュメント
+
+- [モデルバージョン別仕様](./models.md)
+- [タスクステータス取得](./task-status.md)
+- [API 共通仕様](../overview.md)

data/docs/api/suno/models.md

@@ -0,0 +1,95 @@
+# Suno モデルバージョン別仕様
+
+Suno API で使用可能なモデルバージョンとその仕様。
+
+## 利用可能なモデル
+
+| モデル | 説明 |
+|--------|------|
+| `V4` | 基本モデル |
+| `V4_5` | V4 の改良版 |
+| `V4_5PLUS` | V4.5 の高品質版 |
+| `V4_5ALL` | V4.5 の全機能版 |
+| `V5` | 最新モデル |
+
+## 文字数制限
+
+### prompt
+
+| モデル | シンプルモード | カスタムモード |
+|--------|----------------|----------------|
+| V4 | 500 文字 | 3,000 文字 |
+| V4_5 | 500 文字 | 5,000 文字 |
+| V4_5PLUS | 500 文字 | 5,000 文字 |
+| V4_5ALL | 500 文字 | 5,000 文字 |
+| V5 | 500 文字 | 5,000 文字 |
+
+### style（カスタムモード時）
+
+| モデル | 最大文字数 |
+|--------|-----------|
+| V4 | 200 文字 |
+| V4_5 | 1,000 文字 |
+| V4_5PLUS | 1,000 文字 |
+| V4_5ALL | 1,000 文字 |
+| V5 | 1,000 文字 |
+
+### title
+
+全モデル共通: **最大 80 文字**
+
+## モード別の動作
+
+### シンプルモード (`customMode: false`)
+
+- `prompt` のみで楽曲を生成
+- AI が自動的にスタイルとタイトルを決定
+- prompt の最大文字数: 500 文字
+
+### カスタムモード (`customMode: true`)
+
+- `style` と `title` が指定可能（必須）
+- `prompt` にリリック構造を含められる（`[Verse]`, `[Chorus]` など）
+- 詳細な音楽生成パラメータを制御可能
+- `vocalGender`, `personaId` が有効になる
+
+## コード参照
+
+モデル定義は以下のファイルで管理されている：
+
+- `lib/kie/models/suno_v4.rb`
+- `lib/kie/models/suno_v4_5.rb`
+- `lib/kie/models/suno_v4_5_plus.rb`
+- `lib/kie/models/suno_v4_5_all.rb`
+- `lib/kie/models/suno_v5.rb`
+
+## Ruby クライアントでの使用
+
+```ruby
+# V4 モデル（基本）
+task = client.generate(
+  model: "V4",
+  input: {
+    prompt: "A jazz song",
+    custom_mode: false,
+    instrumental: false
+  }
+)
+
+# V5 モデル（最新）でカスタムモード
+task = client.generate(
+  model: "V5",
+  input: {
+    prompt: "[Verse 1]\n長いリリック...\n[Chorus]\n...",
+    custom_mode: true,
+    instrumental: false,
+    style: "詳細なスタイル指定（最大1000文字）",
+    title: "楽曲タイトル"
+  }
+)
+```
+
+## 関連ドキュメント
+
+- [音楽生成 API](./generate.md)
+- [タスクステータス取得](./task-status.md)