Venice MCP Server | Documentação da API Venice

O Venice MCP Server é o servidor oficial do Model Context Protocol para a Venice. Ele expõe a API Venice (chat, imagem, vídeo, áudio, música, embeddings, web augment, personagens, RPC cripto e atestação TEE), além de operações de conta (faturamento e chaves de API), como 45 ferramentas que qualquer agente compatível com MCP pode chamar.

GitHub: veniceai/venice-mcp-server

Publicado como @veniceai/mcp-server no npm. Licença MIT.

45 ferramentas

Toda modalidade da Venice, além de ferramentas de faturamento, chaves de API e TEE

Qualquer host MCP

Claude Desktop, Cursor, ChatGPT, LM Studio, Continue e mais

Autenticação por carteira (opcional)

Use uma chave de API, ou pague por chamada com uma carteira assinada por SIWE via x402

Início rápido

Obtenha uma chave de API Venice

Gere uma em venice.ai/settings/api. Veja o guia de chave de API para instruções passo a passo.

Adicione a Venice à configuração do seu host MCP

Cole isto no arquivo de configuração do seu host MCP:

{
  "mcpServers": {
    "venice": {
      "command": "npx",
      "args": ["-y", "@veniceai/[email protected]"],
      "env": { "VENICE_API_KEY": "<your-venice-api-key>" }
    }
  }
}

Caminhos comuns de configuração:

Host	Caminho
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Cursor	`~/.cursor/mcp.json`
LM Studio	`mcp.json` (a partir das configurações de MCP do app)

Reinicie seu host MCP

Seu agente agora tem chat, imagem, vídeo, música, TTS, ASR e mais 39 ferramentas Venice disponíveis.

A maioria dos hosts MCP só passa variáveis de ambiente que estão explicitamente listadas no bloco env. Variáveis de ambiente do sistema não são herdadas. Se você vir erros 402 com uma chave de API definida, verifique novamente se VENICE_API_KEY está dentro de env na sua configuração.

O que você obtém

45 ferramentas abrangendo cada modalidade Venice, além de operações de conta, 3 recursos (venice://models, venice://styles, venice://voices) e 3 templates de prompt (pesquisa sem censura, escrita criativa NSFW, explorador de estilos de imagem). Cada ferramenta declara anotações explícitas readOnlyHint, destructiveHint, idempotentHint e openWorldHint, para que os hosts possam executar consultas sem pedir permissão e solicitar confirmação antes de qualquer ação destrutiva, como limpeza de mídia ou um relay cripto.

Chat e embeddings

Ferramenta	Descrição
`venice_chat`	Chat completion compatível com OpenAI contra o catálogo LLM completo da Venice, com blocos de texto/imagem/áudio/vídeo/arquivo, saídas estruturadas, ferramentas de função, cache de prompt e controles de raciocínio. As chamadas são em texto simples e sem streaming.
`venice_responses`	Responses API sem estado e compatível com OpenAI, com entrada de texto/imagem e controles de raciocínio. Esta ferramenta não expõe campos de chamada de ferramentas, e modelos E2EE não são suportados.
`venice_embeddings`	Calcula embeddings para entrada de texto.
`venice_chat_with_character`	Conversa com um personagem Venice por slug.

Imagem

Ferramenta	Descrição
`venice_image_generate`	Gera uma imagem (Flux 2, Lustify SDXL, Anime/WAI, Qwen Image, GPT Image, Nano Banana Pro e mais), com proporção ou largura/altura, níveis de qualidade, aprimoramento de prompt, referências de estilo, pesquisa na web e variantes.
`venice_image_edit`	Edita uma imagem com um prompt.
`venice_image_multi_edit`	Edita até 8 imagens juntas com um único prompt (composição / outpainting).
`venice_image_upscale`	Faz upscale de uma imagem de 2 a 4×, com um controle de `creativity`.
`venice_image_remove_bg`	Remove o fundo de uma imagem.
`venice_image_styles`	Lista presets de estilo de imagem.

Vídeo

Ferramenta	Descrição
`venice_video_generate`	Enfileira uma geração de vídeo (Sora 2, Veo 3.1, Kling, Wan, LTX 2, Seedance, Runway Gen-4 e mais) com entradas de imagem, vídeo, áudio, referência e elementos.
`venice_video_status`	Verifica o status de um job de vídeo enfileirado (`POST /video/retrieve`).
`venice_video_complete`	Marca um vídeo concluído como baixado e exclui sua mídia no servidor. Informa a exclusão somente quando a Venice a confirma.
`venice_video_quote`	Obtém uma cotação de preço antes de enfileirar.

Áudio (TTS / ASR)

Ferramenta	Descrição
`venice_tts`	Texto para fala com vozes clonadas, temperatura e tags de emoção. O streaming é armazenado em buffer em um único resultado de áudio completo.
`venice_asr`	Transcreve áudio a partir de uma URL, com timestamps opcionais por palavra/caractere. Transcrições grandes são paginadas por meio de um handle de sessão.
`venice_voice_clone`	Lista vozes ativas específicas do modelo, ou clona uma voz a partir de uma URL de amostra (retorna um handle `vv_<id>` para `venice_tts`).
`venice_audio_quote`	Obtém uma cotação de preço para geração de música.

Música

Ferramenta	Descrição
`venice_music_generate`	Enfileira geração de música (`ace-step-15`, `elevenlabs-music`, `minimax-music-v2/v25/v26`, `stable-audio-25`, `mmaudio-v2-text-to-audio`, `elevenlabs-sound-effects-v2`) com controles de letra, instrumental, loop, voz, idioma, velocidade e duração.
`venice_music_status`	Verifica o status de um job de música enfileirado.
`venice_music_complete`	Marca um job de música concluído como baixado.

Web augment

Ferramenta	Descrição
`venice_web_search`	Pesquisa na web com Brave (padrão, Zero Data Retention) ou Google (intermediado e anonimizado pela Venice).
`venice_web_scrape`	Faz scraping de uma URL para markdown.
`venice_text_parser`	Extrai texto de PDF/DOCX/EPUB/PPTX/XLSX.

Catálogo e personagens

Ferramenta	Descrição
`venice_list_models`	Pagina pelo catálogo de modelos em tempo real de todos os tipos, com resumos compactos, preços e flags de capacidade.
`venice_model_details`	Obtém a linha completa de um modelo exato: restrições de `model_spec`, capacidades e preços.
`venice_model_traits`	Mapeia nomes de traits (`default`, `most_uncensored`, …) para os IDs de modelo atuais.
`venice_model_compatibility_mapping`	Mapeia nomes de modelos compatíveis para IDs de modelo da Venice.
`venice_list_characters`	Lista personagens públicos da Venice com filtros de pesquisa, tag, modelo e ordenação. Somente chave de API.
`venice_get_character`	Obtém um personagem público por slug. Somente chave de API.
`venice_character_reviews`	Lista avaliações públicas paginadas de um personagem. Somente chave de API.

Atestação TEE

Ferramenta	Descrição
`venice_tee_attestation`	Busca evidências de atestação de hardware (quote Intel TDX, evidências NVIDIA opcionais, chave de assinatura) para um modelo de texto compatível com TEE, usando seu próprio nonce de 32 bytes.
`venice_tee_signature`	Busca o payload de assinatura do enclave para o ID de uma requisição de chat TEE concluída.

As duas ferramentas TEE retornam apenas as evidências do provedor: elas não as verificam e não criptografam o chat. Verifique você mesmo o nonce ecoado, o estado do modo de depuração e o vínculo da chave de assinatura antes de confiar em um modelo TEE; veja Verificando a atestação TEE. enable_e2ee é rejeitado por este servidor.

Cripto

Ferramenta	Descrição
`venice_crypto_networks`	Lista os slugs de rede ativos aceitos pelo proxy RPC.
`venice_crypto_rpc`	Intermedeia uma requisição JSON-RPC, ou um lote de até 100, para Ethereum, Base, Arbitrum, Optimism, Polygon, Solana, Starknet, zkSync, Linea, BSC, Avalanche, Blast e mais.

Transmissões de transações (eth_sendRawTransaction, eth_sendUserOperation, sendTransaction da Solana, escritas na Starknet) devem ser enviadas como requisições individuais com uma idempotency_key, e a mesma chave deve ser reutilizada em caso de nova tentativa.

Faturamento (chaves admin)

Ferramenta	Descrição
`venice_billing_balance`	Disponibilidade atual de USD, DIEM e créditos incluídos.
`venice_billing_usage_analytics`	Uso agregado (beta) por data, modelo e chave de API (período retroativo ou intervalo personalizado).
`venice_billing_usage_history`	Uso detalhado com paginação por cursor e saída em JSON ou CSV.

As ferramentas de faturamento exigem uma chave de API ADMIN. Chaves de inferência não podem chamar esses endpoints, e o servidor falha localmente em vez de recorrer a um token de carteira.

Chaves de API

Ferramenta	Descrição
`venice_list_api_keys`	Lista os metadados das chaves ativas, incluindo apenas os seis últimos caracteres. Somente chave admin.
`venice_get_api_key`	Obtém metadados, uso, saldos e limites de taxa de uma chave pelo ID da chave. Somente chave admin.
`venice_api_key_rate_limits`	Saldos atuais, status de acesso, nível, expiração e limites de taxa específicos por modelo. Chave de inferência ou admin.
`venice_api_key_rate_limit_logs`	Os últimos 50 eventos de limite de taxa excedido (experimental). Somente chave admin.

Helpers de carteira x402

Relevante apenas se você se autenticar com uma carteira via x402 em vez de uma chave de API.

Ferramenta	Descrição
`venice_x402_balance`	Verifica saldo de crédito pré-pago x402 para um endereço de carteira EVM ou Solana.
`venice_x402_top_up_info`	Busca requisitos de recarga (rede, token USDC, receiver, valor mínimo). Não recebe argumentos.
`venice_x402_transactions`	Lista transações recentes de recarga e débito x402 para um endereço de carteira EVM ou Solana.

Configuração

O servidor é configurado inteiramente por variáveis de ambiente.

Modelos e requisições

Variável de ambiente	Padrão	Notas
`VENICE_API_KEY`	(nenhuma)	Sua chave de API Venice. A configuração mais simples.
`VENICE_DEFAULT_CHAT_MODEL`	`deepseek-v4-flash-0731`
`VENICE_DEFAULT_IMAGE_MODEL`	`flux-2-pro`
`VENICE_DEFAULT_TTS_MODEL`	`tts-kokoro`
`VENICE_DEFAULT_ASR_MODEL`	`openai/whisper-large-v3`
`VENICE_DISABLE_NSFW`	`0`	Defina como `1` para remover notas de capacidade NSFW das descrições das ferramentas.
`VENICE_HTTP_TIMEOUT_MS`	`60000`
`VENICE_SIWX_TOKEN`	(nenhum)	Token de auth para o modo carteira x402. Veja x402 abaixo.

Se ambos VENICE_API_KEY e VENICE_SIWX_TOKEN estiverem definidos, a chave de API prevalece na maioria das chamadas; veja Cobertura por modo de autenticação para as exceções.

Limites de tamanho de resposta

A mídia gerada é armazenada em buffer e incorporada ao resultado MCP em base64, então cada modalidade tem um limite de bytes.

Variável de ambiente	Padrão	Aplica-se a
`VENICE_MAX_IMAGE_RESPONSE_BYTES`	`33554432` (32 MiB)	`venice_image_generate`, `venice_image_edit`, `venice_image_multi_edit`, `venice_image_upscale`, `venice_image_remove_bg`
`VENICE_MAX_VIDEO_RESPONSE_BYTES`	`26214400` (25 MiB)	`venice_video_status`
`VENICE_MAX_AUDIO_RESPONSE_BYTES`	`33554432` (32 MiB)	`venice_tts`, `venice_music_status`

Um resultado de imagem ou TTS grande demais é descartado com um erro. Um resultado de vídeo ou música grande demais permanece na fila, então você pode chamar a ferramenta de status novamente com o mesmo ID de fila depois de aumentar o limite.

Servidor HTTP

Relevante apenas na implantação Streamable HTTP.

Variável de ambiente	Padrão	Notas
`PORT`	`3333`	Porta do listener HTTP.
`VENICE_MCP_HOST`	`127.0.0.1`	Endereço de bind. Defina como `0.0.0.0` para exposição na LAN ou em contêiner.
`VENICE_MCP_AUTH_TOKEN`	(nenhum)	Token Bearer para `/mcp`. Obrigatório quando ligado fora do loopback, caso em que deve ter pelo menos 16 caracteres. Depois de definido, também é exigido no loopback.
`VENICE_MCP_ALLOW_UNAUTHENTICATED_HTTP`	`0`	Válvula de escape para HTTP exposto sem autenticação. Use apenas atrás de um proxy autenticado e confiável.
`VENICE_MCP_MAX_SESSIONS`	`100`	Número máximo de sessões Streamable HTTP ativas.
`VENICE_MCP_SESSION_TTL_MS`	`1800000`	Tempo de vida de uma sessão ociosa antes da limpeza.

Comportamento da geração de mídia

A mídia concluída pode ser bytes ou uma URL. Jobs de vídeo e música retornam recursos MP4/áudio incorporados, ou JSON com um download_url que volta como um link de recurso. Baixe esse link primeiro e depois chame venice_video_complete ou venice_music_complete; a limpeza de mídia nunca é aplicada a um resultado com download_url, porque o link deixa de funcionar quando o arquivo é excluído.
Alguns modelos só retornam uma URL no momento do enfileiramento. Para os modelos VPS e Grok Imagine Private, capture o download_url retornado por venice_video_generate e passe-o para venice_video_status; um retrieve COMPLETED sem URL inline ainda gera um link utilizável.
O aprimoramento de prompt é informado de volta. Quando enhance_prompt é aplicado, os resultados de geração, edição e multi-edição de imagem incluem o prompt decodificado de URL que a Venice retornou.
A paginação do ASR é cobrada uma única vez. Transcrições com mais de 8.000 caracteres, ou com mais timestamps do que cabem em uma página (200 por array por padrão, até 500 com timestamp_limit), retornam um result_handle com a primeira página. Solicite as páginas seguintes com esse handle. Os handles ficam na memória por sessão MCP durante 10 minutos, e apenas os 16 mais recentes são mantidos.
O consentimento do Seedance não é uma forma de contornar políticas. Os modelos Seedance públicos atuais podem rejeitar de imediato mídias que contenham pessoas detectáveis. Quando uma resposta needs_consent é retornada, as três flags consents.seedance são declarações legais: defina-as como true somente depois que o usuário confirmar explicitamente cada declaração.

Modo carteira x402

A Venice suporta autenticação com um token de carteira Sign-In-With-X lastreado por crédito USDC pré-pago na Base ou Solana, além do fluxo normal de chave de API. Sem necessidade de e-mail, telefone ou KYC: sua carteira é a única identidade.

{
  "mcpServers": {
    "venice": {
      "command": "npx",
      "args": ["-y", "@veniceai/[email protected]"],
      "env": { "VENICE_SIWX_TOKEN": "<base64 Sign-In-With-X payload>" }
    }
  }
}

O servidor MCP encaminha VENICE_SIWX_TOKEN no cabeçalho SIGN-IN-WITH-X em cada chamada à API Venice. O servidor nunca vê sua chave privada. A assinatura da carteira e as autorizações de recarga em USDC acontecem na sua própria carteira.

Fluxo	O que acontece
Configuração única	Assine uma mensagem Sign-In-With-X em sua carteira → produz um token SIWX (JSON em base64).
Recarregar	`POST /api/v1/x402/top-up` retorna 402 + requisitos de pagamento. Assine um pagamento USDC para uma das opções de Base ou Solana retornadas, reenvie e a Venice credita seu saldo.
Cada chamada de inferência	O servidor MCP envia `SIGN-IN-WITH-X: <SIWX>`; a Venice debita seu saldo pré-pago.

A recarga mínima é de $5 USD. O saldo mínimo para chamar inferência é de $0.10. Uma vez recarregadas, as chamadas têm latência abaixo de 100ms porque a liquidação acontece off-chain em uma conta de crédito rápida.

Carteiras vinculadas a uma conta Venice com DIEM em staking consomem do saldo de staking em vez de créditos USDC, então não é necessária recarga.

A Venice não aceita cabeçalhos de pagamento nas rotas de inferência, então este servidor nunca envia um. PAYMENT-SIGNATURE pertence apenas a /x402/top-up, e o helper de recarga descobre os requisitos sem enviar um pagamento.

Cobertura por modo de autenticação

Alguns endpoints aceitam apenas um modo de autenticação:

Ferramenta	Chave de API	x402
Inferência, mídia, web augment, RPC cripto, chat com personagem	✓	✓
`venice_list_characters`, `venice_get_character`, `venice_character_reviews`	✓	✗
`venice_billing_*`, `venice_list_api_keys`, `venice_get_api_key`, `venice_api_key_rate_limit_logs`	✓ (admin)	✗
`venice_api_key_rate_limits`	✓ (qualquer chave)	✗
`venice_x402_balance`, `venice_x402_transactions`	✗	✓
`venice_x402_top_up_info`	✓	✓

Quando as duas credenciais estão definidas, a chave de API é usada em todas as chamadas autenticadas, exceto venice_x402_balance e venice_x402_transactions, que sempre enviam o token de carteira.

Auto-hospedagem (Streamable HTTP)

Para implantações de equipe ou workspace, execute o servidor MCP via HTTP em vez de stdio:

docker run -p 3333:3333 \
  -e VENICE_API_KEY=<your-venice-api-key> \
  -e VENICE_MCP_AUTH_TOKEN=<choose-a-long-random-token> \
  ghcr.io/veniceai/venice-mcp-server:latest

O servidor agora está disponível em http://localhost:3333/mcp. Clientes HTTP devem enviar Authorization: Bearer <VENICE_MCP_AUTH_TOKEN> e devem criar novas sessões sem um cabeçalho mcp-session-id, reutilizando depois o ID de sessão emitido pelo servidor.

/mcp é um endpoint de execução de ferramentas com credenciais: chamadores podem gastar a chave de API Venice configurada ou o saldo x402. Quando o modo HTTP é ligado a um endereço fora do loopback, a inicialização falha a menos que VENICE_MCP_AUTH_TOKEN esteja definido, ou que VENICE_MCP_ALLOW_UNAUTHENTICATED_HTTP=1 esteja definido atrás de um proxy autenticado e confiável. Para produção, fixe a versão do pacote npm explicitamente em vez de depender de latest.

Recursos

GitHub

Código-fonte, issues e releases

npm

@veniceai/mcp-server

Venice Skills

Skills complementares que ensinam aos agentes como usar essas ferramentas

Spec do MCP

Saiba mais sobre o Model Context Protocol

GitHub: veniceai/venice-mcp-server

45 ferramentas

Qualquer host MCP

Autenticação por carteira (opcional)

​Início rápido

​O que você obtém

​Chat e embeddings

​Imagem

​Vídeo

​Áudio (TTS / ASR)

​Música

​Web augment

​Catálogo e personagens

​Atestação TEE

​Cripto

​Faturamento (chaves admin)

​Chaves de API

​Helpers de carteira x402

​Configuração

​Modelos e requisições

​Limites de tamanho de resposta

​Servidor HTTP

​Comportamento da geração de mídia

​Modo carteira x402

​Cobertura por modo de autenticação

​Auto-hospedagem (Streamable HTTP)

​Recursos

GitHub

npm

Venice Skills

Spec do MCP

Início rápido

O que você obtém

Chat e embeddings

Imagem

Vídeo

Áudio (TTS / ASR)

Música

Web augment

Catálogo e personagens

Atestação TEE

Cripto

Faturamento (chaves admin)

Chaves de API

Helpers de carteira x402

Configuração

Modelos e requisições

Limites de tamanho de resposta

Servidor HTTP

Comportamento da geração de mídia

Modo carteira x402

Cobertura por modo de autenticação

Auto-hospedagem (Streamable HTTP)

Recursos