kie-ruby 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6dd09714cf184a6e1d88ece305cbe3a9172fd1c78654f2f51ae63cc3bf31e45a
-  data.tar.gz: 0aca4c4baa773b8624fde53c8b07461a265da97690e7887fda4b794042f569a3
+  metadata.gz: 9326141b2852ca727f590ad08f9d5a68a86bf22c74e1ced750af84c061680fca
+  data.tar.gz: 00dd702a9e12f1df1b9673d3cc241a9ba1a222015b3028e1e97d663e2cfffdaf
 SHA512:
-  metadata.gz: fc5f8f445fab1a86fa92b9e36d5487bc02bc7d84aa1132051216fdaf77b4b3ae4bc318d60db5e67cce8392b60de31a03cc5068731ce7711604608a3b9fce0de0
-  data.tar.gz: ab44c6a1c1f46c6d8ddc09eda3815ba0a144c01c5c82129a14498bada390f46bde281222108d6da01ab214551b063e572ec9992bbdf7c2b9b048813c9fde7606
+  metadata.gz: 74eb2a06b59d1e56142f65773c0640b92e54bc00c889473f0ea89093ff22d5f2758245cb6f2e414a9ebf25cfde968ac6b077b2b9b189bf02d53772ce21990a8f
+  data.tar.gz: 94550ab428f669f33ce8c26e0a126623f8dd6e58aa52f2dfd80a004bcfe2827d8a00834f331fdb43d7c7025be810ccdc2a4152a7bb191269d046b69d31818d55

data/.claude/commands/add-model.md

@@ -0,0 +1,155 @@
+---
+allowed-tools: TodoWrite, TodoRead, Bash, Read, Grep, Glob, WebFetch, AskUserQuestion
+description: "Create GitHub Issue for adding new model"
+---
+
+## Overview
+
+Create a GitHub Issue for adding a new model to the Kie.ai Ruby Client.
+
+---
+
+## Arguments
+
+- `$ARGUMENTS`: API documentation URL (e.g., https://kie.ai/model/seedream/4.5-edit.md)
+
+If no URL is provided, ask the user using AskUserQuestion.
+
+---
+
+## Critical Notes
+
+1. **List ALL change targets without omissions** - Refer to `docs/development/adding-new-model.md` and list every required file
+2. **Always include the API documentation URL** - The URL must be included in the Issue body exactly as provided
+3. **Always reference the guide document** - Include `docs/development/adding-new-model.md` in the Issue body
+
+---
+
+## Execution Steps
+
+### 1. Validate Arguments
+
+- Check if `$ARGUMENTS` contains a valid URL
+- If not provided or invalid, use AskUserQuestion to ask for the API documentation URL
+
+### 2. Read the Adding Model Guide
+
+- Read `docs/development/adding-new-model.md`
+- Extract the checklist of all files that need to be created/modified
+
+### 3. Fetch API Documentation
+
+- Use WebFetch to retrieve the API documentation from the provided URL
+- Extract:
+  - Model name
+  - Category (suno, general, etc.)
+  - Input constraints
+  - Parameters
+  - Any other relevant specifications
+
+### 4. Investigate Existing Implementations
+
+- Search for similar model implementations in `lib/kie/models/`
+- Check corresponding specs in `spec/kie/models/`
+- Understand the patterns used for similar model types
+
+### 5. Determine Implementation Approach
+
+Based on the API documentation and existing implementations:
+- Identify which category the model belongs to
+- List specific files to create/modify with details
+- Note any special considerations or deviations from standard patterns
+
+### 6. Create Issue Body
+
+Save the issue body to `.tmp/issue-add-model-<model-name>.md`
+
+Use the following template:
+
+```markdown
+# Add Model: <MODEL_NAME>
+
+## Overview
+
+Add support for the `<MODEL_NAME>` model to the Kie.ai Ruby Client.
+
+## API Documentation
+
+- <API_DOCUMENTATION_URL>
+
+## Reference
+
+- Implementation guide: `docs/development/adding-new-model.md`
+
+## Change Targets
+
+### Code Changes (Required)
+
+| File | Action | Description |
+|:-----|:-------|:------------|
+| `lib/kie/models/<model_name>.rb` | Create | Model definition |
+| `lib/kie.rb` | Modify | Add require statement |
+
+### Test Changes (Required)
+
+| File | Action | Description |
+|:-----|:-------|:------------|
+| `spec/kie/models/<model_name>_spec.rb` | Create | Model spec |
+| `spec/integration/model_routing_spec.rb` | Modify | Add routing test |
+
+### Documentation Changes (Required)
+
+| File | Action | Description |
+|:-----|:-------|:------------|
+| `README.md` | Modify | Add to Supported Models table |
+| `docs/api/<category>/<model>.md` | Create | API specification |
+| `docs/api/<category>/INDEX.md` | Modify | Add reference |
+
+## Implementation Notes
+
+<Notes about implementation approach based on investigation>
+
+## Model Specifications
+
+Based on the API documentation:
+
+- **Category**: <category>
+- **Input Constraints**: <details>
+- **Parameters**: <details>
+
+## Checklist
+
+- [ ] Model definition file created
+- [ ] require added to lib/kie.rb
+- [ ] Model spec created
+- [ ] Routing test updated
+- [ ] README updated
+- [ ] API documentation created
+- [ ] API INDEX updated
+- [ ] All tests pass (`bundle exec rspec`)
+- [ ] Lint passes (`bundle exec rubocop`)
+```
+
+### 7. Create GitHub Issue
+
+```bash
+gh issue create \
+  --title "Add Model: <MODEL_NAME>" \
+  --label "soba:todo" \
+  --body-file .tmp/issue-add-model-<model-name>.md
+```
+
+### 8. Report Result
+
+Display the created Issue URL to the user.
+
+---
+
+## Validation
+
+Before creating the issue, verify:
+
+- [ ] API documentation URL is included in the issue body
+- [ ] `docs/development/adding-new-model.md` is referenced
+- [ ] All files from the checklist are listed as change targets
+- [ ] Model specifications are extracted from the API documentation

data/.claude/commands/release.md

@@ -0,0 +1,118 @@
+---
+allowed-tools: TodoWrite, Bash, Read, Edit, Write, AskUserQuestion
+description: "Create a PR to bump version for release"
+---
+
+## Overview
+
+Create a Pull Request to bump the gem version for release.
+
+---
+
+## Arguments
+
+- `$ARGUMENTS`: Version number (e.g., `0.2.0`, `1.0.0`)
+
+If no version is provided, ask the user using AskUserQuestion.
+
+---
+
+## Execution Steps
+
+### 1. Validate Arguments
+
+- Check if `$ARGUMENTS` contains a valid semver version (e.g., `0.2.0`)
+- Do NOT include `v` prefix - just the version number
+- If not provided or invalid, use AskUserQuestion to ask for the version
+
+### 2. Check Current State
+
+```bash
+git status
+git branch --show-current
+```
+
+- Ensure working directory is clean
+- Ensure on `main` branch
+
+If not clean or not on main, warn the user and ask how to proceed.
+
+### 3. Read Current Version
+
+- Read `lib/kie/version.rb`
+- Extract current version
+- Validate that new version is greater than current version
+
+### 4. Create Release Branch
+
+```bash
+git checkout -b release/v<VERSION>
+```
+
+### 5. Update Version File
+
+Edit `lib/kie/version.rb` to update the VERSION constant:
+
+```ruby
+VERSION = "<NEW_VERSION>"
+```
+
+### 6. Update Gemfile.lock
+
+```bash
+bundle install
+```
+
+This updates the gem version in `Gemfile.lock` to match the new version.
+
+### 7. Verify the Changes
+
+- Read `lib/kie/version.rb` to confirm the change was applied correctly
+- Verify `Gemfile.lock` contains the new version
+
+### 8. Commit and Push
+
+```bash
+git add lib/kie/version.rb Gemfile.lock
+git commit -m "chore: bump version to <VERSION>"
+git push -u origin release/v<VERSION>
+```
+
+### 9. Create Pull Request
+
+```bash
+gh pr create \
+  --title "chore: bump version to <VERSION>" \
+  --body "$(cat <<'EOF'
+## Summary
+
+- Bump version to `<VERSION>` for release
+
+## After Merge
+
+1. Go to GitHub Releases
+2. Create a new release with tag `v<VERSION>`
+3. The gem will be automatically published to RubyGems
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+### 10. Report Result
+
+Display:
+- PR URL
+- Next steps (merge PR, then create GitHub Release with tag `v<VERSION>`)
+
+---
+
+## Validation
+
+Before creating the PR, verify:
+
+- [ ] Version follows semver format
+- [ ] New version is greater than current version
+- [ ] `lib/kie/version.rb` has been updated correctly
+- [ ] `Gemfile.lock` has been updated correctly
+- [ ] Branch is pushed to remote

data/.claude/commands/update-model.md

@@ -0,0 +1,177 @@
+---
+allowed-tools: TodoWrite, TodoRead, Bash, Read, Grep, Glob, WebFetch, AskUserQuestion
+description: "Create GitHub Issue for updating existing model"
+---
+
+## Overview
+
+Create a GitHub Issue for updating an existing model in the Kie.ai Ruby Client when the API specification has changed.
+
+---
+
+## Arguments
+
+- `$ARGUMENTS`: Model name (e.g., `nano-banana-pro`) or API documentation URL (e.g., https://kie.ai/model/seedream/4.5-edit.md)
+
+If no argument is provided, ask the user using AskUserQuestion.
+
+---
+
+## Critical Notes
+
+1. **Compare current implementation with latest API documentation** - Identify all differences
+2. **List ALL change targets without omissions** - Include all files that need modification
+3. **Always include the API documentation URL** - The URL must be included in the Issue body
+4. **Preserve backward compatibility considerations** - Note any breaking changes
+
+---
+
+## Execution Steps
+
+### 1. Validate Arguments
+
+- Check if `$ARGUMENTS` is provided
+- If it's a URL, extract the model name from it
+- If it's a model name, construct the API documentation URL or ask the user
+- If not provided, use AskUserQuestion to ask for the model name or URL
+
+### 2. Find Existing Implementation
+
+- Search for the model definition in `lib/kie/models/`
+- Read the current model definition file
+- Read the corresponding spec file in `spec/kie/models/`
+- Read the API documentation in `docs/api/<category>/`
+- Note all current specifications:
+  - Input constraints
+  - Parameters
+  - Category
+
+### 3. Fetch Latest API Documentation
+
+- Use WebFetch to retrieve the latest API documentation
+- Extract:
+  - Model name
+  - Category (suno, general, etc.)
+  - Input constraints
+  - Parameters
+  - Any other relevant specifications
+
+### 4. Compare and Identify Changes
+
+Compare the current implementation with the latest API documentation:
+- New parameters added
+- Parameters removed
+- Parameter types changed
+- Input constraints changed
+- Default values changed
+- Any other specification changes
+
+### 5. Determine Update Scope
+
+Based on the comparison:
+- List all files that need to be modified
+- Categorize changes as:
+  - **Breaking**: Changes that may affect existing users
+  - **Non-breaking**: Additive changes or internal improvements
+- Note any migration considerations
+
+### 6. Create Issue Body
+
+Save the issue body to `.tmp/issue-update-model-<model-name>.md`
+
+Use the following template:
+
+```markdown
+# Update Model: <MODEL_NAME>
+
+## Overview
+
+Update the `<MODEL_NAME>` model implementation to match the latest API specification.
+
+## API Documentation
+
+- <API_DOCUMENTATION_URL>
+
+## Reference
+
+- Implementation guide: `docs/development/adding-new-model.md`
+
+## Current vs New Specification
+
+### Input Constraints
+
+| Constraint | Current | New | Change Type |
+|:-----------|:--------|:----|:------------|
+| prompt.max_length | <current> | <new> | <breaking/non-breaking> |
+| ... | ... | ... | ... |
+
+### Parameters
+
+| Parameter | Current | New | Change Type |
+|:----------|:--------|:----|:------------|
+| aspect_ratio.values | <current> | <new> | <breaking/non-breaking> |
+| ... | ... | ... | ... |
+
+## Change Targets
+
+### Code Changes (Required)
+
+| File | Action | Description |
+|:-----|:-------|:------------|
+| `lib/kie/models/<model_name>.rb` | Modify | Update model definition |
+
+### Test Changes (Required)
+
+| File | Action | Description |
+|:-----|:-------|:------------|
+| `spec/kie/models/<model_name>_spec.rb` | Modify | Update spec for new constraints |
+
+### Documentation Changes (Required)
+
+| File | Action | Description |
+|:-----|:-------|:------------|
+| `docs/api/<category>/<model>.md` | Modify | Update API specification |
+
+## Breaking Changes
+
+<List any breaking changes and migration notes, or "None" if no breaking changes>
+
+## Implementation Notes
+
+<Notes about implementation approach>
+
+## Checklist
+
+- [ ] Model definition updated (`lib/kie/models/<model_name>.rb`)
+- [ ] Model spec updated (`spec/kie/models/<model_name>_spec.rb`)
+- [ ] API documentation updated (`docs/api/<category>/<model>.md`)
+- [ ] README updated (if needed)
+- [ ] All tests pass (`bundle exec rspec`)
+- [ ] Lint passes (`bundle exec rubocop`)
+```
+
+### 7. Create GitHub Issue
+
+```bash
+gh issue create \
+  --title "Update Model: <MODEL_NAME>" \
+  --label "soba:todo" \
+  --body-file .tmp/issue-update-model-<model-name>.md
+```
+
+### 8. Report Result
+
+Display the created Issue URL to the user.
+
+---
+
+## Validation
+
+Before creating the issue, verify:
+
+- [ ] Current implementation has been read and analyzed
+- [ ] Latest API documentation has been fetched
+- [ ] All differences have been identified and listed
+- [ ] Breaking changes are clearly marked
+- [ ] All affected files are listed as change targets
+- [ ] API documentation URL is included in the issue body

data/CLAUDE.md

@@ -17,4 +17,5 @@
 
 - Business: @docs/business/INDEX.md
 - Development: @docs/development/INDEX.md
+- API: @docs/api/INDEX.md
 

data/README.md

@@ -255,8 +255,18 @@ end
 | Model | Description |
 |:------|:------------|
 | `nano-banana-pro` | High-quality image generation |
-
-**General model parameters:**
+| `seedream/4.5-edit` | AI-powered image editing |
+| `seedream/4.5-text-to-image` | High-quality text-to-image generation |
+| `flux-2/pro-image-to-image` | Reference-based image-to-image generation |
+| `flux-2/flex-image-to-image` | Flexible reference-based image-to-image generation |
+| `flux-2/flex-text-to-image` | Flexible text-to-image generation |
+| `grok-imagine/image-to-video` | Image-to-video generation |
+| `grok-imagine/text-to-video` | Text-to-video generation |
+| `grok-imagine/image-to-image` | Image-to-image transformation |
+| `grok-imagine/text-to-image` | Text-to-image generation (6 images per request) |
+| `grok-imagine/upscale` | Upscale Kie AI-generated images |
+
+**nano-banana-pro parameters:**
 
 | Parameter | Values | Default |
 |:----------|:-------|:--------|
@@ -264,6 +274,131 @@ end
 | `resolution` | `1K`, `2K`, `4K` | `1K` |
 | `output_format` | `png`, `jpg` | `png` |
 
+**seedream/4.5-edit parameters:**
+
+| Parameter | Values | Default |
+|:----------|:-------|:--------|
+| `aspect_ratio` | `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `2:3`, `3:2`, `21:9` | `1:1` |
+| `quality` | `basic` (2K), `high` (4K) | `basic` |
+
+**seedream/4.5-edit input:**
+
+| Parameter | Type | Description |
+|:----------|:-----|:------------|
+| `prompt` | String | Edit instructions (max 3000 chars, required) |
+| `image_urls` | Array | Input image URLs (required) |
+
+**seedream/4.5-text-to-image parameters:**
+
+| Parameter | Values | Default |
+|:----------|:-------|:--------|
+| `aspect_ratio` | `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `2:3`, `3:2`, `21:9` | `1:1` |
+| `quality` | `basic` (2K), `high` (4K) | `basic` |
+
+**seedream/4.5-text-to-image input:**
+
+| Parameter | Type | Description |
+|:----------|:-----|:------------|
+| `prompt` | String | Image description (max 3000 chars, required) |
+
+**flux-2/pro-image-to-image parameters:**
+
+| Parameter | Values | Default |
+|:----------|:-------|:--------|
+| `aspect_ratio` | `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `auto` | `4:3` |
+| `resolution` | `1K`, `2K` | `1K` |
+
+**flux-2/pro-image-to-image input:**
+
+| Parameter | Type | Description |
+|:----------|:-----|:------------|
+| `prompt` | String | Transformation instructions (max 5000 chars, required) |
+| `input_urls` | Array | Reference image URLs (1-8 images, max 10MB each, required) |
+
+**flux-2/flex-image-to-image parameters:**
+
+| Parameter | Values | Default |
+|:----------|:-------|:--------|
+| `aspect_ratio` | `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `auto` | `1:1` |
+| `resolution` | `1K`, `2K` | `1K` |
+
+**flux-2/flex-image-to-image input:**
+
+| Parameter | Type | Description |
+|:----------|:-----|:------------|
+| `prompt` | String | Transformation instructions (max 5000 chars, required) |
+| `input_urls` | Array | Reference image URLs (1-8 images, max 10MB each, required) |
+
+**flux-2/flex-text-to-image parameters:**
+
+| Parameter | Values | Default |
+|:----------|:-------|:--------|
+| `aspect_ratio` | `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `auto` | `1:1` |
+| `resolution` | `1K`, `2K` | `1K` |
+
+**flux-2/flex-text-to-image input:**
+
+| Parameter | Type | Description |
+|:----------|:-----|:------------|
+| `prompt` | String | Image description (max 5000 chars, required) |
+
+**grok-imagine/image-to-video parameters:**
+
+| Parameter | Values | Default |
+|:----------|:-------|:--------|
+| `mode` | `fun`, `normal`, `spicy` | `normal` |
+
+**grok-imagine/image-to-video input:**
+
+| Parameter | Type | Description |
+|:----------|:-----|:------------|
+| `prompt` | String | Motion description (max 5000 chars, optional) |
+| `image_urls` | Array | Source image URL (max 1 image, max 10MB, optional) |
+| `task_id` | String | Reference to prior Grok task (max 100 chars, optional) |
+| `index` | Number | Image index from referenced task (0-5, optional) |
+
+Note: `image_urls` and `task_id`+`index` are mutually exclusive input methods.
+
+**grok-imagine/text-to-video parameters:**
+
+| Parameter | Values | Default |
+|:----------|:-------|:--------|
+| `aspect_ratio` | `2:3`, `3:2`, `1:1`, `9:16`, `16:9` | `2:3` |
+| `mode` | `fun`, `normal`, `spicy` | `normal` |
+
+**grok-imagine/text-to-video input:**
+
+| Parameter | Type | Description |
+|:----------|:-----|:------------|
+| `prompt` | String | Video description (max 5000 chars, required) |
+
+**grok-imagine/image-to-image input:**
+
+| Parameter | Type | Description |
+|:----------|:-----|:------------|
+| `prompt` | String | Style/content description (max 390,000 chars, optional) |
+| `image_urls` | Array | Source image URL (1 image, max 10MB, required) |
+
+**grok-imagine/text-to-image parameters:**
+
+| Parameter | Values | Default |
+|:----------|:-------|:--------|
+| `aspect_ratio` | `2:3`, `3:2`, `1:1`, `9:16`, `16:9` | `3:2` |
+
+**grok-imagine/text-to-image input:**
+
+| Parameter | Type | Description |
+|:----------|:-----|:------------|
+| `prompt` | String | Image description (max 5000 chars, required) |
+
+**grok-imagine/upscale input:**
+
+| Parameter | Type | Description |
+|:----------|:-----|:------------|
+| `task_id` | String | Reference to prior Kie AI task (max 100 chars, required) |
+
+Note: This model only works with Kie AI-generated images. External image URLs are not supported.
+
 ## Platform Limits
 
 | Item | Limit |

data/docs/api/INDEX.md

@@ -0,0 +1,12 @@
+# API Documents
+
+Kie.ai API のリファレンスドキュメント。
+
+## 概要
+
+- `overview.md`: API 共通仕様（レスポンス形式、ステータスコード、コールバック）
+
+## カテゴリ別
+
+- `suno/INDEX.md`: Suno 音楽生成 API
+- `general/INDEX.md`: General API（画像生成等）

data/docs/api/general/INDEX.md

@@ -0,0 +1,59 @@
+# General API
+
+General API（画像生成等）のドキュメント。
+
+## ドキュメント一覧
+
+- `nano-banana-pro.md`: Nano Banana Pro 画像生成 API
+- `seedream-4-5-edit.md`: Seedream 4.5 Edit 画像編集 API
+- `seedream-4-5-text-to-image.md`: Seedream 4.5 Text-to-Image 画像生成 API
+- `flux-2-pro-image-to-image.md`: Flux 2 Pro Image-to-Image 画像変換 API
+- `flux-2-flex-image-to-image.md`: Flux 2 Flex Image-to-Image 画像変換 API
+- `flux-2-flex-text-to-image.md`: Flux 2 Flex Text-to-Image 画像生成 API
+- `grok-imagine-image-to-video.md`: Grok Imagine Image-to-Video 動画生成 API
+- `grok-imagine-text-to-video.md`: Grok Imagine Text-to-Video 動画生成 API
+- `grok-imagine-image-to-image.md`: Grok Imagine Image-to-Image 画像変換 API
+- `grok-imagine-text-to-image.md`: Grok Imagine Text-to-Image 画像生成 API
+- `grok-imagine-upscale.md`: Grok Imagine Upscale 画像アップスケーリング API
+
+## 概要
+
+General API は汎用的な生成タスクを提供する。現在は画像生成モデル Nano Banana Pro、画像編集モデル Seedream 4.5 Edit、テキストから画像を生成する Seedream 4.5 Text-to-Image、参照画像から画像を生成する Flux 2 Pro Image-to-Image および Flux 2 Flex Image-to-Image、テキストから画像を生成する Flux 2 Flex Text-to-Image、静止画から動画を生成する Grok Imagine Image-to-Video、テキストから動画を生成する Grok Imagine Text-to-Video、画像から画像を変換する Grok Imagine Image-to-Image、テキストから 6 枚の画像を生成する Grok Imagine Text-to-Image、Kie AI 生成画像をアップスケールする Grok Imagine Upscale に対応。
+
+### エンドポイント
+
+| 操作 | エンドポイント | メソッド |
+|------|---------------|---------|
+| タスク作成 | `/api/v1/jobs/createTask` | POST |
+| ステータス取得 | `/api/v1/jobs/queryTask` | GET |
+
+### Ruby クライアントでの使用例
+
+```ruby
+client = Kie::Client.new(api_key: "your-api-key")
+
+# 画像を生成
+task = client.generate(
+  model: "nano-banana-pro",
+  input: {
+    prompt: "A beautiful sunset over the ocean"
+  },
+  aspect_ratio: "16:9",
+  resolution: "2K"
+)
+
+# 結果を取得
+result = task.wait
+```
+
+## 今後の拡張予定
+
+新しいモデルが追加された場合、このディレクトリに個別のドキュメントを追加する。
+
+例：
+- `flux-pro.md`: Flux Pro API（予定）
+
+## 関連ドキュメント
+
+- [API 共通仕様](../overview.md)
+- [Suno API](../suno/INDEX.md)