Pixapi MCP

Gere imagens e vídeos a partir de agentes de IA: consulte preços de crédito e saldo em tempo real, inicie tarefas assíncronas de imagem ou vídeo e obtenha resultados via MCP.

GitHub

Documentação

pixapi-mcp

Use as ferramentas de geração de imagem e vídeo da Pixapi a partir de clientes MCP.

  • Site: Pixapi
  • Endpoint MCP remoto: https://api.pixapi.ai/mcp
  • Licença: MIT

Início rápido

Configure seu projeto automaticamente (Node.js 22+):

npx -y pixapi-mcp init --client codex

Substitua codex pelo seu cliente, ou use --client all para todos os cinco:

Cliente--clientArquivo de configuração
Claude Codeclaude-code.mcp.json
Cursorcursor.cursor/mcp.json
Codexcodex.codex/config.toml
VS Code / GitHub Copilotvscode.vscode/mcp.json
Gemini CLIgemini-cli.gemini/settings.json

Sem --client, o padrão é Claude Code e Cursor (--client both). Use --project /path/to/project para configurar outro projeto.

Recarregue seu cliente MCP e conecte-se a pixapi. Complete o login no navegador e o prompt de autorização na primeira vez. O cliente salva a sessão OAuth e a atualiza automaticamente; nenhuma chave de API ou edição de credenciais é necessária. O cliente pode pedir que você faça login novamente se a autorização for revogada ou expirar. Cada cliente gerencia sua própria sessão OAuth nativa.

init configura uma conexão HTTP remota direta por padrão. Se o seu cliente tiver uma interface "Adicionar servidor MCP", você também pode inserir a URL do endpoint lá sem instalar este pacote npm ou Node.js.

O Codex exige um projeto confiável. No VS Code, use MCP: List Servers para iniciar pixapi; no Gemini CLI, use /mcp para inspecioná-lo. Complete qualquer prompt de confiança ou login do cliente. init não altera as políticas de segurança do cliente.

Configuração gerada

Claude Code:

{"mcpServers":{"pixapi":{"type":"http","url":"https://api.pixapi.ai/mcp"}}}

O Cursor usa a mesma entrada mcpServers com url e sem o campo type. O VS Code usa servers com type: "http" e url. O Gemini CLI usa mcpServers com httpUrl.

Codex:

[mcp_servers.pixapi]
url = "https://api.pixapi.ai/mcp"

Executar init atualiza a entrada pixapi e preserva outros servidores e configurações. Comentários JSONC do VS Code são preservados. Configurações TOML do Codex são preservadas, mas comentários e formatação não são. Todas as configurações selecionadas são analisadas antes da gravação; uma falha no sistema de arquivos durante gravações pode ainda deixar alguns arquivos atualizados. Corrija o problema local e execute novamente init.

Ponte stdio local

Para clientes que precisam de stdio, configure a ponte explicitamente:

npx -y pixapi-mcp init --client cursor --transport stdio

A entrada gerada executa npx -y pixapi-mcp proxy sem credenciais. Instalações do pacote npm via registro também iniciam a ponte diretamente: nenhum comando init separado ou variável de ambiente é necessário.

A ponte completa o handshake MCP local imediatamente. Na primeira solicitação de ferramenta, ela abre a autorização no navegador e então encaminha ferramentas para a Pixapi. Conexões subsequentes reutilizam a sessão salva e atualizam tokens automaticamente. Para clientes com um timeout curto de descoberta de ferramentas, faça login uma vez antes:

npx -y pixapi-mcp login

Se um cliente expirar durante o login inicial no navegador, complete o login e reconecte o cliente. Nenhuma URL de autorização, código ou token é impressa na saída padrão ou de erro do MCP.

Sessões OAuth são armazenadas por endpoint em ~/.pixapi/oauth-<hash>.json. No macOS e Linux, o diretório usa o modo 0700 e os arquivos usam 0600. As gravações são atômicas; processos de ponte concorrentes compartilham um bloqueio de autorização. Verificadores PKCE e estado de callback são mantidos apenas em memória. O callback vincula-se ao loopback no mesmo host da ponte. Para um host headless ou remoto, prefira a conexão OAuth remota nativa do cliente.

Instalações existentes com chave de API

Configurações existentes com chave de API permanecem compatíveis. Para uma instalação explícita com chave de API, defina PIXAPI_API_KEY ao executar init; isso configura stdio e salva a chave de forma privada em ~/.pixapi/mcp-credentials.json. Um --transport remote explícito sempre seleciona OAuth nativo, mesmo se essa variável estiver definida. O proxy também aceita PIXAPI_API_KEY diretamente para implantações não assistidas.

O proxy dá prioridade a uma chave de ambiente explícita, depois a uma sessão OAuth salva e, por fim, a um arquivo de chave legado. Para migrar uma ponte existente para OAuth, execute pixapi-mcp login e remova qualquer substituição de PIXAPI_API_KEY do ambiente dela. Chaves e tokens nunca aparecem nas configurações de projeto geradas.

Ferramentas disponíveis

Este pacote encaminha a lista de ferramentas ao vivo do endpoint MCP remoto da Pixapi. Após conectar, chame tools/list ou pixapi_get_pricing_and_balance para obter o catálogo atual.

pixapi_get_pricing_and_balance

Retorna seu saldo atual e os preços ao vivo de modelos de imagem/vídeo. Cada linha do catálogo inclui um type:

  • Imagens: text_to_image, image_to_image
  • Vídeos: text_to_video, image_to_video

Linhas marcadas com mcp_generate_supported=true podem ser chamadas por meio da ferramenta de geração correspondente.

pixapi_generate_image

Inicia uma tarefa assíncrona de imagem e retorna um task_id. Use type=text_to_image para uma solicitação apenas com prompt, ou type=image_to_image com o campo image. A ferramenta aceita os modelos de imagem do catálogo ao vivo, incluindo Gemini, GPT Image, Flux, Seedream, Qwen e Wan.

Esta chamada consome créditos da conta. Não é idempotente: repetir a mesma chamada cria outra tarefa e pode cobrar a conta novamente.

pixapi_generate_video

Inicia uma tarefa assíncrona de vídeo e retorna um task_id. Use type=text_to_video para uma solicitação apenas com prompt, ou type=image_to_video com o campo image. Passe seconds e resolution conforme exigido pelo modelo selecionado.

Esta chamada consome créditos da conta e não é idempotente.

pixapi_get_task

Recupera uma tarefa de imagem ou vídeo pertencente à conta autenticada. Faça polling desta ferramenta com o task_id retornado até que o status seja completed ou failed. Uma tarefa concluída inclui URLs de mídia.

Fluxo de agente recomendado:

  1. Chame pixapi_get_pricing_and_balance.
  2. Selecione uma linha do catálogo com mcp_generate_supported=true e verifique o saldo.
  3. Chame pixapi_generate_image ou pixapi_generate_video uma vez e guarde seu task_id.
  4. Faça polling de pixapi_get_task a cada poucos segundos.
  5. Retorne a URL do resultado quando a tarefa estiver concluída.

Referência da CLI

pixapi-mcp init [--client <name|all|both>] [--project <path>] [--transport <remote|stdio>]
pixapi-mcp login
pixapi-mcp proxy
pixapi-mcp --help

Sem argumentos, o pacote inicia o proxy stdio.

Solução de problemas

  • As ferramentas não aparecem: recarregue o cliente, habilite o servidor pixapi e complete a confiança do projeto e o login no navegador. Para stdio, garanta Node.js 22+ e npx disponíveis no host que executa a ponte.
  • Autorização negada ou expirada: tente o login novamente no cliente nativo, ou execute pixapi-mcp login para a ponte e complete a autorização no navegador.
  • Porta de callback indisponível: feche outro login Pixapi pendente e tente novamente.
  • Serviço indisponível: verifique sua conexão e tente novamente mais tarde. Respostas HTTP internas e detalhes de exceções são omitidos dos erros públicos.
  • Chave de API legada inválida: substitua a chave ou migre para OAuth como acima.

Segurança e limitações atuais

  • Não faça commit nem compartilhe arquivos em ~/.pixapi/.
  • Revogue credenciais não utilizadas ou expostas na sua conta Pixapi.
  • A ponte stdio encaminha apenas ferramentas. Recursos, prompts, amostragem e elicitação não são expostos por este pacote.
  • A geração de imagem e vídeo é assíncrona e não idempotente. A ponte tenta novamente uma vez a rejeição de autenticação HTTP; ela não tenta novamente falhas de rede ou erros de servidor que possam ter ocorrido após a execução de uma ferramenta.
  • Recarga de conta não é exposta como ferramenta MCP; complete o pagamento na Pixapi.

Para documentação do serviço, visite Documentação Pixapi.

Registro MCP oficial

Este servidor é publicado no Registro MCP oficial como io.github.Pixapi-AI/pixapi-mcp, com ambos os métodos de conexão declarados em server.json: o endpoint remoto e o pacote npm. Ambos suportam OAuth sem chave de API obrigatória a partir da versão 0.1.4.

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.Pixapi-AI/pixapi-mcp"

Defina versões correspondentes em package.json, package-lock.json e server.json antes de enviar a tag v* correspondente. O fluxo de trabalho de lançamento instala dependências bloqueadas, executa verificações e valida o manifesto do Registro antes de publicar. Execuções manuais também devem selecionar essa tag de lançamento. Uma nova execução compara a integridade do pacote npm existente e os metadados do Registro e publica apenas as etapas ausentes; conteúdos conflitantes exigem uma nova versão. A autenticação do Registro usa GitHub OIDC, sem token do Registro armazenado.