AI 图像生成服务

AI 画像生成サービス

火山エンジン（抖音豆包）をベースにした画像生成サービスです。Cursor MCP サービスとの連携を目的として設計されています。画像のアスペクト比や保存先などをカスタマイズでき、高品質な画像を生成できます。

機能の特徴

• 高品質な画像生成に対応
• よく使われる複数のアスペクト比に対応（1:1、4:3、16:9、3:4、9:16）
• 火山エンジン豆包モデル（doubao-seedream-3-0-t2i-250415）
• 自動リトライと詳細なエラー処理
• 包括的なパスと権限の検証
• 詳細なエラーメッセージとログ
• 非同期処理に対応

環境の準備

1. Python 環境

• Python 3.10+

• ダウンロード先： https://www.python.org/downloads/

• pyenv での Python バージョン管理を推奨します：

# macOS 安装 pyenv
brew install pyenv

# 安装 Python
pyenv install 3.13.2
pyenv global 3.13.2

2. Nodejs 環境

• ダウンロード先： https://nodejs.org/zh-cn

3. uv パッケージ管理ツール

uv は高速な Python パッケージマネージャーです。事前にインストールしてください：

# macOS 安装 uv
brew install uv

# 或者使用 pip 安装
pip install uv

4. 火山エンジン API キー

1. 火山エンジン方舟大模型サービスにアクセスします
2. アカウントを登録／ログインします
3. 新しい API キーを作成します
4. キーをコピーして保存します。形式は次のとおりです：YOUR_API_KEY

5. Cursor

• Cursor IDEをダウンロードしてインストールします
• Cursor の Python 環境が正しく設定されていることを確認します

インストールと設定

1. プロジェクトをクローンする

git clone https://github.com/chenyeju295/mcp_generate_images.git
cd mcp_generate_images

2. 依存関係をインストールする（mcp_generate_images に移動してインストール）

python3 -m pip install fastmcp requests 'volcengine-python-sdk[ark]'

または、requirements.txt ファイルを使用します：

pip install -r requirements.txt

証明書に関する問題が発生した場合は、次の方法を使用できます：

python3 -m pip install fastmcp requests 'volcengine-python-sdk[ark]' --trusted-host pypi.org --trusted-host files.pythonhosted.org --upgrade --force-reinstall --no-cache-dir

ヒント：インストールが正常に完了していることを確認してください。完了していない場合、MCP サービスの設定時にエラーが表示されます。

3. API キーを設定する

環境変数を設定します（推奨）：

export ARK_API_KEY=your_api_key_here

または、~/.bashrc あるいは ~/.zshrc に追加します：

echo 'export ARK_API_KEY=your_api_key_here' >> ~/.zshrc
source ~/.zshrc

環境変数が設定されていることを確認します：

echo $ARK_API_KEY

4. サービスを設定する

mcp_server.py では、次の設定を変更できます：

CONFIG = {
    "api": {
        "base_url": "https://ark.cn-beijing.volces.com/api/v3",
        "model": "doubao-seedream-3-0-t2i-250415",
        "timeout": 120,
        "max_retries": 3,
        "retry_delay": 5
    },
    "image": {
        "max_width": 1024,   
        "max_height": 1024, 
        "default_width": 1024,
        "default_height": 1024,
        "max_batch_size": 1
    },
    "output": {
        "base_folder": "你的默认保存路径",
        "allowed_extensions": [".png", ".jpg", ".jpeg"],
        "default_extension": ".png"
    }
}

サービスの実行

開発モードで実行します（デバッグ画面付き）：

uv run --with fastmcp fastmcp dev /Users/username/Documents/mcp_generate_images/mcp_server.py

Cursor での使用

1. Cursor に MCP サービスを追加する

Cursor の MCP 設定に次の内容を追加します：

{
  "mcpServers": {
    "generate_images": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "/Users/chenyeju/Documents/github/mcp_generate_images/mcp_server.py"
      ]
    } 
  }
}

3. サービスが正常に実行されている例

4. Cursor Composer の agent モードで使用する

パラメーターの説明

画像生成ツールは、次のパラメーターに対応しています：

パラメーター名	種類	必須	説明
prompt	文字列	はい	画像生成プロンプトです。500文字以内を推奨します
file_name	文字列	はい	保存するファイル名です（パスを含みません。拡張子がない場合は、デフォルトで.pngが使用されます）
save_folder	文字列	はい	保存先ディレクトリの絶対パスです
aspect_ratio	文字列	いいえ	画像のアスペクト比です。'1:1'、'4:3'、'16:9'、'3:4'、'9:16' に対応しています。デフォルトは'1:1'です

使用例

生成一张宽高比为16:9的风景图片：

generate_image(
  prompt="A beautiful mountain landscape with sunset", 
  file_name="landscape.png", 
  save_folder="/Users/username/Documents/images", 
  aspect_ratio="16:9"
)

使用上の注意

1. モデル：火山エンジン豆包モデル（doubao-seedream-3-0-t2i-250415）を使用します。最大1024x1024のサイズに対応しています。
2. アスペクト比：最適な結果と生成速度を得るため、512x512や1024x1024など、1:1のアスペクト比（正方形の画像）を推奨します。
3. プロンプト：簡潔で明確なプロンプトほど、良い結果が得られる傾向があります。500文字以内を目安にしてください。中国語のプロンプトにも対応しています。
4. タイムアウトの問題：複雑なプロンプトや正方形でない画像の場合、生成に時間がかかり、タイムアウトエラーが発生することがあります。
5. API の制限：火山エンジン API では、一度に生成できる画像は1枚のみです。以前の一括生成とは異なります。

エラーのトラブルシューティング

問題が発生した場合は、次の項目を確認してください：

1. サービスが正常に実行されているか
2. 保存先のパスが正しいか（絶対パスである必要があります）
3. ディレクトリの権限が正しいか
4. ネットワーク接続が正常か
5. API キーが有効か
6. Python 環境が正しく設定されているか
7. uv が正しくインストールされているか
8. 依存パッケージがすべてインストールされているか

よくあるエラーと解決方法

エラーメッセージ	考えられる原因	解決方法
"未能生成图片: API 请求超时"	ネットワークの問題、またはリクエストに時間がかかりすぎています	より簡潔なプロンプトを使用し、ネットワーク接続を確認します
"未能生成图片: API 调用频率受限"	火山エンジン API の呼び出し頻度制限	数分待ってから再試行します
"未能生成图片: API 认证失败"	API キーが無効です	火山エンジン API キーを確認して更新します
"没有权限保存图片到..."	ディレクトリの権限に問題があります	ディレクトリが存在し、書き込み権限があることを確認します
"不支持的宽高比"	対応していないアスペクト比が指定されています	対応しているアスペクト比を使用します：'1:1'、'4:3'、'16:9'、'3:4'、'9:16'
"Failed to download generated images"	画像のダウンロードに失敗しました	ネットワーク接続を確認し、火山エンジンの画像 URL にアクセスできることを確認します