AI Image Generation

Genera imágenes usando la API de Together AI. Admite relaciones de aspecto personalizadas, rutas de guardado y generación por lotes.

GitHub

Prueba este MCPPatrocinado

Documentación

Servicio de Generación de Imágenes con IA

Servicio de generación de imágenes basado en Volcano Engine (Doubao de Douyin), diseñado específicamente para integrarse con el servicio MCP de Cursor. Admite relaciones de aspecto personalizadas, rutas de guardado y otras funciones, proporcionando capacidades de generación de imágenes de alta calidad.

Características

Generación de imágenes de alta calidad
Soporte para múltiples relaciones de aspecto comunes (1:1, 4:3, 16:9, 3:4, 9:16)
Modelo Doubao de Volcano Engine (doubao-seedream-3-0-t2i-250415)
Reintentos automáticos y manejo detallado de errores
Validación completa de rutas y permisos
Mensajes de error detallados y registros
Soporte de procesamiento asíncrono

Preparación del Entorno

1. Entorno Python

Python 3.10+
Enlace de descarga: https://www.python.org/downloads/
Se recomienda usar pyenv para gestionar la versión de Python:

# macOS 安装 pyenv
brew install pyenv

# 安装 Python
pyenv install 3.13.2
pyenv global 3.13.2

2. Entorno Node.js

Enlace de descarga: https://nodejs.org/zh-cn

3. Herramienta de gestión de paquetes uv

uv es un gestor de paquetes de Python rápido, debe instalarse primero:

# macOS 安装 uv
brew install uv

# 或者使用 pip 安装
pip install uv

4. Clave API de Volcano Engine

Visite Servicio de modelos Ark de Volcano Engine
Regístrese / inicie sesión en su cuenta
Cree una nueva clave API
Copie y guarde la clave, con un formato como: YOUR_API_KEY

5. Cursor

Descargue e instale Cursor IDE
Asegúrese de que Cursor tenga configurado correctamente el entorno Python

Instalación y Configuración

1. Clonar el proyecto

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

2. Instalar dependencias (cd a mcp_generate_images para instalar)

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

O use el archivo requirements.txt:

pip install -r requirements.txt

Si aparecen problemas de certificados, puede usar:

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

Consejo: asegúrese de que la instalación sea exitosa; de lo contrario, la configuración del servicio MCP mostrará errores en rojo.

3. Configurar la clave API

Establezca las variables de entorno (método recomendado):

export ARK_API_KEY=your_api_key_here

O agregue en ~/.bashrc o ~/.zshrc:

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

Verifique que las variables de entorno estén configuradas:

echo $ARK_API_KEY

4. Configurar el servicio

En mcp_server.py puede modificar la siguiente configuración:

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"
    }
}

Ejecutar el Servicio

Modo de desarrollo (con interfaz de depuración):

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

Uso en Cursor

1. Introducir el servicio MCP en Cursor

Agregue en la configuración MCP de Cursor:

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

3. Ejemplo de servicio ejecutándose correctamente

4. Uso en modo agente de Cursor Composer

Descripción de Parámetros

La herramienta de generación de imágenes admite los siguientes parámetros:

Nombre del parámetro	Tipo	Obligatorio	Descripción
prompt	cadena	sí	Indicación para la generación de imágenes, se recomienda no superar los 500 caracteres
file_name	cadena	sí	Nombre del archivo a guardar (sin ruta; si no tiene extensión, se usará .png por defecto)
save_folder	cadena	sí	Ruta absoluta del directorio de guardado
aspect_ratio	cadena	no	Relación de aspecto de la imagen, admite '1:1', '4:3', '16:9', '3:4', '9:16'. El valor predeterminado es '1:1'

Ejemplo de Uso

生成一张宽高比为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"
)

Notas de Uso

Modelo: utiliza el modelo Doubao de Volcano Engine (doubao-seedream-3-0-t2i-250415), admite un tamaño máximo de 1024x1024.
Relación de aspecto: se recomienda usar una relación de aspecto de 1:1 (imagen cuadrada), por ejemplo 512x512 o 1024x1024, para obtener los mejores resultados y velocidad de generación.
Indicaciones: las indicaciones concisas y claras suelen dar mejores resultados; intente no superar los 500 caracteres. Admite indicaciones en chino.
Problemas de tiempo de espera: para indicaciones complejas o imágenes no cuadradas, la generación puede tardar más y a veces causar errores de tiempo de espera.
Límites de API: la API de Volcano Engine genera solo una imagen a la vez, a diferencia de la generación por lotes anterior.

Solución de Problemas

Si encuentra problemas, verifique:

Si el servicio se está ejecutando correctamente
Si la ruta de guardado es correcta (debe ser una ruta absoluta)
Si los permisos del directorio son correctos
Si la conexión de red es normal
Si la clave API es válida
Si el entorno Python está configurado correctamente
Si uv está instalado correctamente
Si los paquetes de dependencias están completamente instalados

Errores Comunes y Soluciones

Mensaje de error	Causa posible	Solución
"No se pudo generar la imagen: tiempo de espera de la solicitud API"	Problema de red o solicitud demasiado lenta	Use indicaciones más simples, verifique la conexión de red
"No se pudo generar la imagen: frecuencia de llamadas a la API limitada"	Límite de frecuencia de la API de Volcano Engine	Espere unos minutos e intente de nuevo
"No se pudo generar la imagen: fallo de autenticación de la API"	Clave API no válida	Verifique y actualice la clave API de Volcano Engine
"Sin permiso para guardar la imagen en..."	Problema de permisos del directorio	Asegúrese de que el directorio exista y tenga permisos de escritura
"Relación de aspecto no compatible"	Se usó una relación de aspecto no compatible	Use una relación de aspecto compatible: '1:1', '4:3', '16:9', '3:4', '9:16'
"Failed to download generated images"	Fallo en la descarga de imágenes	Verifique la conexión de red, asegúrese de poder acceder a la URL de imágenes de Volcano Engine