Venice MCP Server | Venice API Docs

Il Venice MCP Server è il server ufficiale Model Context Protocol per Venice. Espone l’API Venice (chat, image, video, audio, music, embeddings, web augment, characters, crypto RPC e attestation TEE) più le operazioni sull’account (fatturazione e API key) come 45 tool che qualsiasi agente compatibile con MCP può chiamare.

GitHub: veniceai/venice-mcp-server

Pubblicato come @veniceai/mcp-server su npm. Licenza MIT.

45 tool

Ogni modalità Venice più i tool per fatturazione, API key e TEE

Qualsiasi host MCP

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

Wallet auth (opzionale)

Porta una API key, oppure paga per chiamata con un wallet firmato SIWE tramite x402

Avvio rapido

Ottieni una API key Venice

Generane una da venice.ai/settings/api. Consulta la guida sulle API key per istruzioni passo passo.

Aggiungi Venice alla configurazione del tuo host MCP

Inserisci questo nel file di configurazione del tuo host MCP:

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

Percorsi di configurazione comuni:

Host	Percorso
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` (dalle impostazioni MCP dell’app)

Riavvia il tuo host MCP

Il tuo agente ora ha disponibili chat, image, video, music, TTS, ASR e altri 39 tool Venice.

La maggior parte degli host MCP passa solo variabili d’ambiente esplicitamente elencate nel blocco env. Le variabili d’ambiente a livello di sistema non vengono ereditate. Se vedi errori 402 con una API key impostata, controlla due volte che VENICE_API_KEY sia all’interno di env nella tua configurazione.

Cosa ottieni

45 tool che coprono ogni modalità Venice più le operazioni sull’account, 3 resource (venice://models, venice://styles, venice://voices) e 3 template di prompt (ricerca senza censura, scrittura creativa NSFW, esploratore di stili per immagini). Ogni tool dichiara esplicitamente le annotazioni readOnlyHint, destructiveHint, idempotentHint e openWorldHint, così gli host possono eseguire le consultazioni senza chiedere conferma e richiederla invece prima di qualsiasi operazione distruttiva, come la pulizia dei media o un relay crypto.

Chat ed embeddings

Tool	Descrizione
`venice_chat`	Chat completion compatibile con OpenAI sull’intero catalogo LLM di Venice, con blocchi di testo/immagine/audio/video/file, output strutturati, function tool, prompt caching e controlli di reasoning. Le chiamate sono in chiaro e non in streaming.
`venice_responses`	API Responses stateless e compatibile con OpenAI, con input di testo/immagine e controlli di reasoning. Questo tool non espone i campi per il tool calling e i modelli E2EE non sono supportati.
`venice_embeddings`	Calcola gli embedding per testo in input.
`venice_chat_with_character`	Chatta con un personaggio Venice tramite slug.

Image

Tool	Descrizione
`venice_image_generate`	Genera un’immagine (Flux 2, Lustify SDXL, Anime/WAI, Qwen Image, GPT Image, Nano Banana Pro e altri), con aspect ratio o larghezza/altezza, livelli di qualità, miglioramento del prompt, riferimenti di stile, ricerca web e varianti.
`venice_image_edit`	Modifica un’immagine con un prompt.
`venice_image_multi_edit`	Modifica fino a 8 immagini insieme con un solo prompt (composizione / outpainting).
`venice_image_upscale`	Esegui l’upscale di un’immagine di 2–4×, con un controllo `creativity`.
`venice_image_remove_bg`	Rimuovi lo sfondo di un’immagine.
`venice_image_styles`	Elenca i preset di stile dell’immagine.

Video

Tool	Descrizione
`venice_video_generate`	Metti in coda una generazione video (Sora 2, Veo 3.1, Kling, Wan, LTX 2, Seedance, Runway Gen-4 e altri) con input di immagini, video, audio, riferimenti ed elementi.
`venice_video_status`	Controlla lo stato di un job video in coda (`POST /video/retrieve`).
`venice_video_complete`	Contrassegna un video completato come scaricato ed elimina il relativo media lato server. Segnala l’eliminazione solo quando Venice la conferma.
`venice_video_quote`	Ottieni un preventivo prima della messa in coda.

Audio (TTS / ASR)

Tool	Descrizione
`venice_tts`	Text-to-speech con voci clonate, temperatura e tag di emozione. Lo streaming viene bufferizzato in un unico risultato audio completo.
`venice_asr`	Trascrivi audio da un URL, con timestamp opzionali per parola/carattere. Le trascrizioni lunghe vengono paginate tramite un handle di sessione.
`venice_voice_clone`	Elenca le voci live specifiche del modello, oppure clona una voce da un URL di campione (restituisce un handle `vv_<id>` per `venice_tts`).
`venice_audio_quote`	Ottieni un preventivo per la generazione musicale.

Musica

Tool	Descrizione
`venice_music_generate`	Metti in coda la generazione musicale (`ace-step-15`, `elevenlabs-music`, `minimax-music-v2/v25/v26`, `stable-audio-25`, `mmaudio-v2-text-to-audio`, `elevenlabs-sound-effects-v2`) con controlli per testi, strumentale, loop, voce, lingua, velocità e durata.
`venice_music_status`	Controlla lo stato di un job musicale in coda.
`venice_music_complete`	Contrassegna un job musicale completato come scaricato.

Web augment

Tool	Descrizione
`venice_web_search`	Cerca sul web con Brave (predefinito, Zero Data Retention) o Google (tramite proxy e anonimizzato da Venice).
`venice_web_scrape`	Esegui lo scraping di un URL in markdown.
`venice_text_parser`	Estrai testo da PDF/DOCX/EPUB/PPTX/XLSX.

Catalogo e personaggi

Tool	Descrizione
`venice_list_models`	Sfoglia pagina per pagina il catalogo modelli live di ogni tipo, con riepiloghi compatti, prezzi e flag di capacità.
`venice_model_details`	Ottieni la riga completa di un modello specifico: vincoli `model_spec`, capacità e prezzi.
`venice_model_traits`	Mappa i nomi dei trait (`default`, `most_uncensored`, …) agli ID dei modelli attuali.
`venice_model_compatibility_mapping`	Mappa i nomi di modelli compatibili agli ID dei modelli Venice.
`venice_list_characters`	Elenca i personaggi Venice pubblici con filtri di ricerca, tag, modello e ordinamento. Solo API key.
`venice_get_character`	Ottieni un personaggio pubblico tramite slug. Solo API key.
`venice_character_reviews`	Elenca le recensioni pubbliche paginate di un personaggio. Solo API key.

Attestation TEE

Tool	Descrizione
`venice_tee_attestation`	Recupera le prove di attestation hardware (quote Intel TDX, prove NVIDIA opzionali, chiave di firma) per un modello di testo con supporto TEE, usando un tuo nonce da 32 byte.
`venice_tee_signature`	Recupera il payload della firma dell’enclave per l’ID di una richiesta chat TEE completata.

Entrambi i tool TEE restituiscono solo le prove del provider: non le verificano e non cifrano la chat. Verifica tu stesso il nonce restituito, lo stato della modalità debug e il binding della chiave di firma prima di fidarti di un modello TEE; consulta Verifica dell’attestation TEE. enable_e2ee viene rifiutato da questo server.

Crypto

Tool	Descrizione
`venice_crypto_networks`	Elenca gli slug di rete live accettati dal proxy RPC.
`venice_crypto_rpc`	Inoltra una richiesta JSON-RPC, o un batch fino a 100, a Ethereum, Base, Arbitrum, Optimism, Polygon, Solana, Starknet, zkSync, Linea, BSC, Avalanche, Blast e altri.

I broadcast di transazioni (eth_sendRawTransaction, eth_sendUserOperation, sendTransaction di Solana, scritture Starknet) devono essere inviati come richieste singole con una idempotency_key, e la stessa chiave deve essere riutilizzata in caso di nuovo tentativo.

Fatturazione (chiavi admin)

Tool	Descrizione
`venice_billing_balance`	Disponibilità attuale di USD, DIEM e crediti inclusi.
`venice_billing_usage_analytics`	Utilizzo aggregato in beta per data, modello e API key (periodo a ritroso o intervallo personalizzato).
`venice_billing_usage_history`	Utilizzo dettagliato con paginazione a cursore e output JSON o CSV.

I tool di fatturazione richiedono una API key ADMIN. Le chiavi di inferenza non possono chiamare questi endpoint e il server fallisce localmente invece di ripiegare su un token wallet.

API key

Tool	Descrizione
`venice_list_api_keys`	Elenca i metadati delle chiavi attive, inclusi solo gli ultimi sei caratteri. Solo chiave admin.
`venice_get_api_key`	Ottieni metadati, utilizzo, saldi e rate limit di una chiave tramite il suo ID. Solo chiave admin.
`venice_api_key_rate_limits`	Saldi attuali, stato di accesso, tier, scadenza e rate limit specifici per modello. Chiave di inferenza o admin.
`venice_api_key_rate_limit_logs`	Gli ultimi 50 eventi di superamento dei rate limit (sperimentale). Solo chiave admin.

Helper wallet x402

Rilevante solo se ti autentichi con un wallet tramite x402 invece che con una API key.

Tool	Descrizione
`venice_x402_balance`	Controlla il saldo di credito x402 prepagato per un indirizzo wallet EVM o Solana.
`venice_x402_top_up_info`	Recupera i requisiti di ricarica (rete, token USDC, ricevitore, importo minimo). Non accetta argomenti.
`venice_x402_transactions`	Elenca le ricariche x402 recenti e le transazioni di addebito per un indirizzo wallet EVM o Solana.

Configurazione

Il server è configurato interamente tramite variabili d’ambiente.

Modelli e richieste

Variabile d’ambiente	Default	Note
`VENICE_API_KEY`	(nessuno)	La tua API key Venice. La configurazione più semplice.
`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`	Imposta a `1` per rimuovere le note sulla capacità NSFW dalle descrizioni dei tool.
`VENICE_HTTP_TIMEOUT_MS`	`60000`
`VENICE_SIWX_TOKEN`	(nessuno)	Token di autenticazione in modalità wallet x402. Consulta x402 più sotto.

Se sono impostati sia VENICE_API_KEY sia VENICE_SIWX_TOKEN, l’API key vince nella maggior parte delle chiamate; consulta Copertura delle modalità di autenticazione per le eccezioni.

Limiti di dimensione delle risposte

I media generati vengono bufferizzati e incorporati nel risultato MCP in base64, quindi ogni modalità ha un tetto massimo in byte.

Variabile d’ambiente	Default	Si applica 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`

Un risultato di immagine o TTS troppo grande viene scartato con un errore. Un risultato video o musicale troppo grande resta in coda, quindi puoi chiamare di nuovo il tool di stato con lo stesso ID di coda dopo aver aumentato il limite.

Server HTTP

Rilevante solo nel deploy Streamable HTTP.

Variabile d’ambiente	Default	Note
`PORT`	`3333`	Porta del listener HTTP.
`VENICE_MCP_HOST`	`127.0.0.1`	Indirizzo di bind. Imposta a `0.0.0.0` per l’esposizione in LAN o da container.
`VENICE_MCP_AUTH_TOKEN`	(nessuno)	Bearer token per `/mcp`. Obbligatorio quando il bind avviene al di fuori del loopback, nel qual caso deve essere di almeno 16 caratteri. Una volta impostato, viene applicato anche sul loopback.
`VENICE_MCP_ALLOW_UNAUTHENTICATED_HTTP`	`0`	Via di fuga per esporre HTTP senza autenticazione. Usalo solo dietro un proxy autenticato e affidabile.
`VENICE_MCP_MAX_SESSIONS`	`100`	Numero massimo di sessioni Streamable HTTP attive.
`VENICE_MCP_SESSION_TTL_MS`	`1800000`	Durata di una sessione inattiva prima della pulizia.

Comportamento della generazione di media

I media completati possono essere byte o un URL. I job video e musicali restituiscono risorse MP4/audio incorporate, oppure un JSON con un download_url che viene restituito come link a una risorsa. Scarica prima quel link, poi chiama venice_video_complete o venice_music_complete; la pulizia dei media non viene mai applicata a un risultato download_url perché il link smette di funzionare una volta eliminato il file.
Alcuni modelli restituiscono solo un URL al momento della messa in coda. Per i modelli VPS e Grok Imagine Private, salva il download_url restituito da venice_video_generate e passalo a venice_video_status; un retrieve COMPLETED senza URL inline fornisce comunque un link utilizzabile.
Il miglioramento del prompt viene riportato. Quando viene applicato enhance_prompt, i risultati di generazione, modifica e modifica multipla di immagini includono il prompt decodificato dall’URL restituito da Venice.
La paginazione ASR viene addebitata una sola volta. Le trascrizioni più lunghe di 8.000 caratteri, o con più timestamp di quanti ne stiano in una pagina (200 per array per impostazione predefinita, fino a 500 con timestamp_limit), restituiscono un result_handle insieme alla prima pagina. Richiedi le pagine successive con quell’handle. Gli handle restano in memoria per ogni sessione MCP per 10 minuti, e vengono conservati solo i 16 più recenti.
Il consenso Seedance non è un modo per aggirare le policy. Gli attuali modelli Seedance pubblici possono rifiutare direttamente i media che contengono persone riconoscibili. Quando viene restituita una risposta needs_consent, i tre flag consents.seedance sono attestazioni legali: impostali a true solo dopo che l’utente ha confermato esplicitamente ciascuna dichiarazione.

Modalità wallet x402

Venice supporta l’autenticazione con un token wallet Sign-In-With-X sostenuto da credito USDC prepagato su Base o Solana, oltre al normale flusso con API key. Nessuna email, numero di telefono o KYC richiesti: il tuo wallet è l’unica identità.

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

Il server MCP inoltra VENICE_SIWX_TOKEN nell’header SIGN-IN-WITH-X su ogni chiamata all’API Venice. Il server non vede mai la tua chiave privata. La firma del wallet e le autorizzazioni di ricarica USDC avvengono nel tuo wallet.

Flusso	Cosa succede
Configurazione una tantum	Firma un messaggio Sign-In-With-X nel tuo wallet → produce un token SIWX (JSON base64).
Ricarica	`POST /api/v1/x402/top-up` restituisce 402 + requisiti di pagamento. Firma un pagamento USDC per una delle opzioni Base o Solana restituite, reinvia e Venice accredita il tuo saldo.
Ogni chiamata di inferenza	Il server MCP invia `SIGN-IN-WITH-X: <SIWX>`; Venice scala dal tuo saldo prepagato.

La ricarica minima è di $5 USD. Il saldo minimo per chiamare l’inferenza è $0.10. Una volta ricaricato, le chiamate sono sotto i 100 ms perché la liquidazione avviene off-chain su un account di credito veloce.

I wallet collegati a un account Venice con DIEM in staking consumano dal saldo di staking invece dei crediti USDC, quindi non è necessaria la ricarica.

Venice non accetta header di pagamento sulle route di inferenza, quindi questo server non ne invia mai uno. PAYMENT-SIGNATURE appartiene solo a /x402/top-up, e l’helper di ricarica rileva i requisiti senza inviare alcun pagamento.

Copertura delle modalità di autenticazione

Alcuni endpoint accettano una sola modalità di autenticazione:

Tool	API key	x402
Inferenza, media, web augment, crypto RPC, chat con personaggi	✓	✓
`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`	✓ (qualsiasi chiave)	✗
`venice_x402_balance`, `venice_x402_transactions`	✗	✓
`venice_x402_top_up_info`	✓	✓

Quando sono impostate entrambe le credenziali, l’API key viene usata per ogni chiamata autenticata tranne venice_x402_balance e venice_x402_transactions, che inviano sempre il token wallet.

Self-hosting (Streamable HTTP)

Per deploy di team o workspace, esegui il server MCP su HTTP invece che su 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

Il server è ora disponibile su http://localhost:3333/mcp. I client HTTP devono inviare Authorization: Bearer <VENICE_MCP_AUTH_TOKEN> e dovrebbero creare nuove sessioni senza un header mcp-session-id, per poi riutilizzare l’ID di sessione emesso dal server.

/mcp è un endpoint di esecuzione tool sostenuto da credenziali: i chiamanti possono spendere l’API key Venice configurata o il saldo x402. Quando la modalità HTTP si lega al di fuori del loopback, l’avvio fallisce a meno che non sia impostato VENICE_MCP_AUTH_TOKEN, oppure VENICE_MCP_ALLOW_UNAUTHENTICATED_HTTP=1 dietro un proxy autenticato e affidabile. Per la produzione, fissa esplicitamente la versione del pacchetto npm invece di affidarti a latest.

Risorse

GitHub

Codice sorgente, issue e release

npm

@veniceai/mcp-server

Venice Skills

Skill complementari che insegnano agli agenti come usare questi tool

Specifica MCP

Scopri di più sul Model Context Protocol

GitHub: veniceai/venice-mcp-server

45 tool

Qualsiasi host MCP

Wallet auth (opzionale)

​Avvio rapido

​Cosa ottieni

​Chat ed embeddings

​Image

​Video

​Audio (TTS / ASR)

​Musica

​Web augment

​Catalogo e personaggi

​Attestation TEE

​Crypto

​Fatturazione (chiavi admin)

​API key

​Helper wallet x402

​Configurazione

​Modelli e richieste

​Limiti di dimensione delle risposte

​Server HTTP

​Comportamento della generazione di media

​Modalità wallet x402

​Copertura delle modalità di autenticazione

​Self-hosting (Streamable HTTP)

​Risorse

GitHub

npm

Venice Skills

Specifica MCP

Avvio rapido

Cosa ottieni

Chat ed embeddings

Image

Video

Audio (TTS / ASR)

Musica

Web augment

Catalogo e personaggi

Attestation TEE

Crypto

Fatturazione (chiavi admin)

API key

Helper wallet x402

Configurazione

Modelli e richieste

Limiti di dimensione delle risposte

Server HTTP

Comportamento della generazione di media

Modalità wallet x402

Copertura delle modalità di autenticazione

Self-hosting (Streamable HTTP)

Risorse