image-generator

画像生成スキル

汎用画像生成サービスです。複数の AI モデルに対応しており、他のスキルから直接呼び出せます。

機能

• 🎨 複数の AI モデルに対応（ModelScope、Gemini、RunningHub など）
• 📦 ライブラリとして他のスキルからインポートして呼び出し可能
• ⚙️ 柔軟な設定システム
• 🔄 非同期タスクに対応（ModelScope、RunningHub）
• 💾 生成した画像を自動保存
• 🛡️ エラー処理と再試行の仕組み
• 🧪 テストモードに対応（API Key 不要）

使用方法

方法 1：コマンドラインから直接呼び出す

# 基本用法（默认使用 gemini）
python3 ~/.claude/skills/image-generator/generate_image.py "A golden cat"

# 指定 API 类型
python3 ~/.claude/skills/image-generator/generate_image.py "A golden cat" --api-type modelscope

# RunningHub 文生图
python3 ~/.claude/skills/image-generator/generate_image.py \
  "一只金色的猫在阳光下打盹" \
  --api-type runninghub

# 指定输出路径
python3 ~/.claude/skills/image-generator/generate_image.py "A golden cat" --output /path/to/image.jpg

# 参考图编辑/身份保持（Gemini 图片模型）
python3 ~/.claude/skills/image-generator/generate_image.py \
  "保留人物身份，改为正面摄影棚头肩照" \
  --reference-image /path/to/person.png \
  --size 1024x1280 \
  --output /path/to/portrait.png

# 指定模型
python3 ~/.claude/skills/image-generator/generate_image.py "A golden cat" --model "Tongyi-MAI/Z-Image-Turbo"

# 测试模式（无需 API Key）
python3 ~/.claude/skills/image-generator/generate_image.py "A golden cat" --test

方法 2：他のスキルからインポートして呼び出す

import sys
from pathlib import Path

# 添加 image-generator skill 到路径
image_gen_path = Path.home() / ".claude/skills/image-generator"
sys.path.insert(0, str(image_gen_path))

from generate_image import ImageGenerator

# 创建生成器实例（不传 api_type 时从 config.json 的 default_api 读取）
generator = ImageGenerator()

# 生成图片
image_path = generator.generate(
    prompt="A beautiful landscape",
    output_path="/path/to/output.jpg"
)

print(f"图片已生成: {image_path}")

# RunningHub 文生图示例
from generate_image import ImageGenerator

generator = ImageGenerator(api_type="runninghub")
image_path = generator.generate(
    prompt="一只金色的猫在阳光下打盹",
    output_path="/path/to/output.jpg"
)

設定

初回使用時の設定

1. 設定テンプレートファイルをコピーします：

cp ~/.claude/skills/image-generator/config.json.example ~/.claude/skills/image-generator/config.json

2. 設定ファイルを編集し、API Key を入力します：

設定ファイルの場所：~/.claude/skills/image-generator/config.json

{
  "default_api": "runninghub",
  "modelscope": {
    "base_url": "https://api-inference.modelscope.cn/",
    "api_key": "your-modelscope-token-here",
    "model": "Tongyi-MAI/Z-Image-Turbo",
    "timeout": 300,
    "poll_interval": 5
  },
  "gemini": {
    "api_key": "your-gemini-api-key-here",
    "model": "gemini-3-pro-image-preview",
    "api_url": "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
    "timeout": 120,
    "size": "1024x1024",
    "quality": "standard"
  },
  "runninghub": {
    "base_url": "https://www.runninghub.cn/openapi/v2",
    "api_key": "your-runninghub-api-key-here",
    "model": "rhart-image-n-g31-flash/text-to-image",
    "timeout": 300,
    "poll_interval": 5,
    "resolution": "2k"
  },
  "output_dir": "~/Downloads/shell/work/generated_images",
  "image_format": "jpg",
  "quality": 95
}

設定パラメーターの説明

共通設定：

• default_api：デフォルトで使用する API（modelscope、gemini、または runninghub）
• output_dir：画像の出力ディレクトリ
• image_format：画像形式（jpg、png、webp）
• quality：画像品質（1～100）

ModelScope の設定：

• base_url：ModelScope API のアドレス
• api_key：ModelScope API Token（https://modelscope.cn から取得）
• model：使用するモデル名
• timeout：リクエストのタイムアウト時間（秒）
• poll_interval：ポーリング間隔（秒）

Gemini の設定：

• api_key：Google Gemini API Key（https://ai.google.dev から取得）
• model：使用するモデル名（例：gemini-3-pro-image-preview）
• api_url：API エンドポイントのアドレス
• timeout：リクエストのタイムアウト時間（秒）
• size：画像サイズ（例：1024x1024）
• quality：生成品質（standard または high）

RunningHub の設定：

• base_url：RunningHub OpenAPI のアドレス
• api_key：RunningHub API Key
• model：使用するモデルのパス（例：rhart-image-n-g31-flash/text-to-image）
• timeout：リクエストのタイムアウト時間（秒）
• poll_interval：ポーリング間隔（秒）
• resolution：デフォルトの解像度（例：2k）

注意：

• config.json には機密情報である API Key が含まれるため、.gitignore で除外されています
• 実際の API Key を含む設定ファイルをバージョン管理にコミットしないでください
• テンプレートとして config.json.example を参照してください

対応モデル

ModelScope

• Tongyi-MAI/Z-Image-Turbo - 高速画像生成
• damo/text-to-image-synthesis - テキストから画像への生成
• その他の ModelScope 対応モデル

Gemini

• gemini-3-pro-image-preview - Gemini 3 Pro による画像生成
• その他の Gemini 対応モデル

RunningHub

• rhart-image-n-g31-flash/text-to-image - テキストから画像への生成（2K 解像度）
• その他の RunningHub OpenAPI 互換モデル

API パラメーター

generate() メソッド

generator.generate(
    prompt: str,                    # 图片描述（必需）
    output_path: str = None,         # 输出路径（可选）
    model: str = None,               # 指定模型（可选）
    size: str = "1024x1024",         # 图片尺寸
    quality: str = "standard",       # 生成质量
    style: str = None,               # 风格（可选）
    timeout: int = 300,              # 超时时间（秒）
    max_retries: int = 3,            # 最大重试次数
    test_mode: bool = False,         # 测试模式
    reference_images: list[str] = None # Gemini 参考图片，可传多张
) -> str                             # 返回图片路径

エラー処理

• 失敗したリクエストを自動で再試行します（最大 3 回）
• 詳細なエラーログを記録します
• 適切なフォールバック処理を行います

テストモード

API Key を設定せずに画像生成の流れをすばやくテストできるテストモードに対応しています：

# 命令行使用测试模式
python3 ~/.claude/skills/image-generator/generate_image.py "A golden cat" --test

# Python 代码中使用测试模式
generator = ImageGenerator(api_type="gemini")
image_path = generator.generate(
    prompt="A beautiful landscape",
    test_mode=True  # 启用测试模式
)

テストモードでは、プロンプトの内容を含むサンプル画像を生成します。開発時のデバッグや、ネットワークに接続できない環境での使用に適しています。

例

例 1：基本的な使用方法

python3 ~/.claude/skills/image-generator/generate_image.py "A futuristic city"

例 2：テストモード（API Key 不要）

python3 ~/.claude/skills/image-generator/generate_image.py "A golden cat" --test

例 3：Python での使用

from generate_image import ImageGenerator

gen = ImageGenerator()
image = gen.generate("A beautiful sunset over the ocean")
print(f"Generated: {image}")

例 4：他のスキルへの統合

# 在 write-article skill 中
from pathlib import Path
import sys

sys.path.insert(0, str(Path.home() / ".claude/skills/image-generator"))
from generate_image import ImageGenerator

def generate_article_cover(title):
    gen = ImageGenerator()
    cover_image = gen.generate(
        prompt=f"Professional article cover for: {title}",
        output_path=f"./covers/{title}.jpg"
    )
    return cover_image

注意事項

1. API Key の設定：

   • config.json に該当する API Key を設定する必要があります
   • API Key をバージョン管理にコミットしないでください

2. ネットワーク要件：

   • 安定したネットワーク接続が必要です
   • 一部の API では、インターネット接続に特別な設定が必要な場合があります

3. 生成時間：

   • ModelScope は通常 10～30 秒かかります
   • Gemini は通常 5～15 秒かかります
   • RunningHub は通常 15～30 秒かかります

4. コストに関する考慮事項：

   • 一部の API では料金が発生する場合があります
   • API の使用状況を監視することをおすすめします

5. 出力形式：

   • JPG、PNG、WebP などの形式に対応しています
   • デフォルトの出力形式は JPG です

トラブルシューティング

問題 1：API Key が無効

错误: Unauthorized
解决: 检查 config.json 中的 API Key 是否正确

問題 2：生成がタイムアウトする

错误: Timeout
解决: 增加 config.json 中的 timeout 值

問題 3：ネットワーク接続に失敗する

错误: Connection Error
解决: 检查网络连接，某些 API 可能需要科学上网

依存関係

• requests
• Pillow (PIL)
• その他のスキルの任意の依存関係

ライセンス

MIT