Come collegare HeyGen a Gemini via MCP

💡 Niente installazione? Vai direttamente su cloud.anythingmcp.com. Accedi, clicca Connectors → HeyGen, inserisci le credenziali, genera una MCP API key e hai finito. Niente Docker, niente git clone, niente server locale.

HeyGen + Gemini

Fai creare alla tua AI video con avatar HeyGen usando la tua chiave: scegli avatar e voci, trasforma uno script o un prompt in un video parlato, compila i tuoi template, traduci video in altre lingue con il lip-sync, crea photo avatar e controlla i render e il tuo saldo.

Prerequisiti

Le istruzioni di setup complete sono incluse nel connettore stesso (visibili nello store quando lo selezioni). Le variabili d'ambiente richieste sono:

HEYGEN_API_KEY

Step 1 — Ottieni le credenziali

1. Accedi a https://app.heygen.com e apri la dashboard API (https://app.heygen.com/developers/api).
2. Genera una API key e copiala. L'uso delle API viene fatturato separatamente da un abbonamento web a HeyGen: se l'account non ne ha, aggiungi lì del saldo o un metodo di pagamento.
3. Incolla la chiave in HEYGEN_API_KEY e installa il connettore. La chiave viene inviata solo a HeyGen. Una chiave limitata ad alcuni scope ha bisogno dell'accesso in lettura ad avatar, voci, video, template, traduzioni e utente, e dell'accesso in scrittura per i tool che creano contenuti.
4. Inizia con heygen_get_account: mostra il tuo tipo di fatturazione e quanto ti resta da spendere.

Addebitato sul tuo saldo API HeyGen: video, traduzioni e avatar vengono pagati con il tuo saldo API (un wallet a consumo o i crediti del tuo piano). HeyGen fattura i video in base a durata e motore; i prezzi attuali sono nella dashboard API, e una chiamata rifiutata (402) indica quanto sarebbe servito. Elencare e controllare è gratuito.

Prima conferma: prima di heygen_create_video, heygen_generate_from_template, heygen_create_agent_video o heygen_translate_video, l'AI ti dice cosa verrà creato (avatar, voce, lunghezza dello script, formato, lingue, motore) e aspetta il tuo sì. heygen_create_photo_avatar accetta solo la foto di una persona che ha dato il proprio consenso, per esempio tu stesso, e l'AI ti chiede di confermare che ne hai il diritto. heygen_delete_video è disattivato all'installazione.

Come nasce un video:

1. L'AI sceglie un personaggio con heygen_list_avatar_groups e uno dei suoi look con heygen_list_avatar_looks; il look è il presentatore. Una voce da heygen_list_voices è facoltativa, altrimenti parla la voce propria dell'avatar.
2. heygen_create_video riceve lo script (fino a 5.000 caratteri), il formato (per esempio 9:16 per gli short) e il motore, e restituisce subito un id video.
3. Il video viene renderizzato in background. L'AI controlla heygen_get_video circa ogni 30 secondi; un render richiede da un minuto a diversi minuti, di più per gli script lunghi.
4. Il video finito arriva con un link MP4, una versione con sottotitoli, i sottotitoli SRT e un link al video in HeyGen. I link di download scadono; chiedine di nuovi.

Altri modi per creare un video:

• Template: heygen_list_templates e heygen_get_template mostrano i tuoi template pronti per le API e le loro variabili; heygen_generate_from_template compila ogni variabile di testo e renderizza il video.
• Video Agent: heygen_create_agent_video trasforma un prompt in un video completo (script, scene, avatar); heygen_get_agent_session lo segue finché il video non è renderizzato.
• Traduzione: heygen_translate_video traduce un video da un link pubblico in una o più lingue, con la voce clonata di chi parla e il lip-sync oppure solo come audio; heygen_list_translation_languages elenca le lingue di destinazione.
• Photo avatar: heygen_create_photo_avatar crea un presentatore da un solo ritratto; heygen_get_avatar_look mostra quando è pronto all'uso.

Motori: avatar_iv è quello predefinito. avatar_v offre i movimenti più naturali, ma solo per i look che lo supportano. avatar_iii supporta il 4K per digital twin e studio avatar.

Limiti: con il piano a consumo, 10 tra video, traduzioni o sessioni agente in render contemporaneamente (di più su Enterprise), 300 chiamate di elenco e 500 controlli di stato al minuto. I file sorgente devono essere link pubblici: video fino a 100 MB, audio fino a 50 MB e 10 minuti.

Errori comuni: 401: la chiave è sbagliata o revocata. 402 insufficient_credit: il saldo non copre questo video, e il messaggio indica quanto serve. usage_limit_reached o trial_limit_exceeded: un limite del workspace o della prova che un amministratore o un piano a pagamento può rimuovere. 403 insufficient_api_key_scope: la chiave è limitata; assegnale gli scope indicati sopra. 400 invalid_parameter: il messaggio indica il campo, per esempio un motore che il look non supporta. 404: un id che non esiste; l'AI lo verifica con i tool di elenco. 429: troppe richieste; aspetta e riprova una volta più tardi.

Il connettore usa l'API v3 di HeyGen (HeyGen dismette i vecchi endpoint v1 e v2 il 31 ottobre 2026). Non copre video studio multi-scena, image-to-video, lip-sync di video esistenti, clonazione e design delle voci, text to speech a sé stante, avatar interattivi in streaming, upload di file (le sorgenti devono essere link pubblici), revisione delle traduzioni, webhook, brand kit, cartelle né batch.

Step 2 — Installa l'adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Step 3 — Aggiungi il connettore in Gemini

L'URL del tuo server: in AnythingMCP apri MCP Servers → il server su cui si trova questo connettore e copia il suo URL (https://cloud.anythingmcp.com/mcp/…). Usalo ovunque questa guida mostra YOUR_SERVER_ID.

Gemini CLI legge i server MCP da ~/.gemini/settings.json (su Windows %USERPROFILE%\.gemini\settings.json). Aggiungi:

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Crea una chiave API MCP in AnythingMCP da MCP Servers → il tuo server → API keys e incollala al posto di YOUR_MCP_API_KEY.
2. Salva il file e riavvia gemini.
3. Esegui /mcp in Gemini CLI (oppure gemini mcp list dal terminale): anythingmcp dovrebbe risultare connesso.
4. Inizia a scrivere prompt: Gemini CLI ora può chiamare i tool di HeyGen.

Tool disponibili

Esempi di prompt

• "Quanto resta sul mio saldo API HeyGen?"
• "Mostrami i miei avatar e quali dei loro look funzionano meglio in 9:16."
• "Crea un video 9:16 di 45 secondi con il mio digital twin che legge questo script. Prima conferma con me avatar, voce e durata, poi mandami il link MP4 quando è pronto."
• "Compila il nostro template di aggiornamento settimanale con queste tre notizie e fai il render."
• "Traduci questo video demo del prodotto in spagnolo (Spagna) e giapponese con il lip-sync e dimmi quando entrambe le versioni sono pronte."

FAQ

Dove cerca i server MCP Gemini CLI? In ~/.gemini/settings.json per il tuo utente, oppure in .gemini/settings.json dentro un progetto. gemini mcp list mostra ogni server e se si connette.

Prossimi passi

• Landing del connettore
• Collegare a Claude
• Collegare a ChatGPT