AI Image Generation

Gere imagens usando a API Together AI. Suporta proporções personalizadas, caminhos de salvamento e geração em lote.

Documentação

Serviço de Geração de Imagens com IA

Serviço de geração de imagens baseado na Volcano Engine (Doubao da Douyin), projetado especificamente para integração com o serviço MCP do Cursor. Suporta proporções de imagem personalizadas, caminhos de salvamento e outros recursos, fornecendo capacidade de geração de imagens de alta qualidade.

Recursos

Suporte à geração de imagens de alta qualidade
Suporte a várias proporções comuns (1:1, 4:3, 16:9, 3:4, 9:16)
Modelo Doubao da Volcano Engine (doubao-seedream-3-0-t2i-250415)
Repetição automática e tratamento detalhado de erros
Validação completa de caminhos e permissões
Mensagens de erro e logs detalhados
Suporte a processamento assíncrono

Preparação do Ambiente

1. Ambiente Python

Python 3.10+
Endereço de download: https://www.python.org/downloads/
Recomenda-se usar pyenv para gerenciar a versão do Python:

# macOS 安装 pyenv
brew install pyenv

# 安装 Python
pyenv install 3.13.2
pyenv global 3.13.2

2. Ambiente Nodejs

Endereço de download: https://nodejs.org/zh-cn

3. Ferramenta de gerenciamento de pacotes uv

uv é um gerenciador de pacotes Python rápido, que precisa ser instalado primeiro:

# macOS 安装 uv
brew install uv

# 或者使用 pip 安装
pip install uv

4. Chave de API da Volcano Engine

Acesse Serviço de modelos Ark da Volcano Engine
Registre-se/faça login na conta
Crie uma nova chave de API
Copie e salve a chave, com formato como: YOUR_API_KEY

5. Cursor

Baixe e instale o Cursor IDE
Certifique-se de que o Cursor esteja configurado corretamente com o ambiente Python

Instalação e Configuração

1. Clonar o projeto

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

2. Instalar dependências (cd para mcp_generate_images para instalar)

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

Ou use o arquivo requirements.txt:

pip install -r requirements.txt

Se houver problemas de certificado, use:

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

dica: certifique-se de que a instalação foi bem-sucedida, caso contrário, a configuração do serviço MCP exibirá erro.

3. Configurar a chave de API

Defina as variáveis de ambiente (método recomendado):

export ARK_API_KEY=your_api_key_here

Ou adicione em ~/.bashrc ou ~/.zshrc:

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

Verifique se a variável de ambiente foi definida:

echo $ARK_API_KEY

4. Configurar o serviço

Em mcp_server.py, você pode modificar as seguintes configurações:

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

Executar o serviço

Execução em modo de desenvolvimento (com interface de depuração):

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

Uso no Cursor

1. Adicionar o serviço MCP no Cursor

Na configuração MCP do Cursor, adicione:

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

3. Exemplo de execução bem-sucedida do serviço

4. Uso no modo agente do Cursor Composer

Descrição dos Parâmetros

A ferramenta de geração de imagens suporta os seguintes parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
prompt	string	Sim	Prompt de geração da imagem, recomendado não exceder 500 caracteres
file_name	string	Sim	Nome do arquivo a ser salvo (sem caminho, se não houver extensão, usa .png por padrão)
save_folder	string	Sim	Caminho absoluto do diretório de salvamento
aspect_ratio	string	Não	Proporção da imagem, suporta '1:1', '4:3', '16:9', '3:4', '9:16'. Padrão: '1:1'

Exemplo 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"
)

Observações de Uso

Modelo: Usa o modelo Doubao da Volcano Engine (doubao-seedream-3-0-t2i-250415), suporta tamanho máximo de 1024x1024.
Proporção: Recomenda-se usar proporção 1:1 (imagem quadrada), por exemplo 512x512 ou 1024x1024, para obter melhores resultados e velocidade de geração.
Prompt: Prompts simples e claros geralmente produzem melhores resultados, tente não exceder 500 caracteres. Suporta prompts em chinês.
Problemas de timeout: Para prompts complexos ou imagens não quadradas, a geração pode levar mais tempo, às vezes causando erros de timeout.
Limite da API: A API da Volcano Engine gera apenas uma imagem por vez, diferente da geração em lote anterior.

Solução de Problemas

Se encontrar problemas, verifique:

Se o serviço está em execução corretamente
Se o caminho de salvamento está correto (deve ser um caminho absoluto)
Se as permissões do diretório estão corretas
Se a conexão de rede está funcionando
Se a chave de API é válida
Se o ambiente Python está configurado corretamente
Se o uv foi instalado corretamente
Se os pacotes de dependência foram instalados completamente

Erros Comuns e Soluções

Mensagem de Erro	Causa Possível	Solução
"Falha ao gerar imagem: timeout da solicitação da API"	Problema de rede ou solicitação demorada demais	Use prompts mais simples, verifique a conexão de rede
"Falha ao gerar imagem: limite de frequência da API"	Limite de frequência da API da Volcano Engine	Aguarde alguns minutos e tente novamente
"Falha ao gerar imagem: falha de autenticação da API"	Chave de API inválida	Verifique e atualize a chave de API da Volcano Engine
"Sem permissão para salvar imagem em..."	Problema de permissão do diretório	Certifique-se de que o diretório existe e tem permissão de escrita
"Proporção não suportada"	Uso de proporção não suportada	Use proporções suportadas: '1:1', '4:3', '16:9', '3:4', '9:16'
"Falha ao baixar imagens geradas"	Falha no download da imagem	Verifique a conexão de rede, certifique-se de que consegue acessar a URL da imagem da Volcano Engine