> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# LiveAvatar

## Panoramica

L'integrazione LiveAvatar collega ElevenAgents alla piattaforma [LiveAvatar](https://docs.liveavatar.com) di HeyGen per creare esperienze interattive con avatar. Combina gli agenti ElevenLabs (che gestiscono le interazioni audio) con lo streaming video in tempo reale degli avatar di LiveAvatar, consentendo conversazioni visive a bassa latenza con avatar IA.

Con questa integrazione puoi:

* Distribuire agenti IA conversazionali con una rappresentazione visiva tramite avatar
* Creare esperienze di assistenza clienti interattive con avatar realistici
* Realizzare assistenti virtuali coinvolgenti per siti web e applicazioni

## Come funziona

L'integrazione usa la modalità di sessione LITE di LiveAvatar, in cui le responsabilità sono suddivise tra le due piattaforme:

* **ElevenLabs**: gestisce lo streaming e l'orchestrazione dell'input e dell'output audio
* **LiveAvatar**: gestisce il rendering degli avatar e lo streaming video in tempo reale

Quando una sessione in modalità LITE viene avviata con una configurazione ElevenAgents, LiveAvatar avvia un worker che si connette al tuo agente ElevenLabs. L'output audio dell'agente guida in tempo reale il lip sync e le animazioni dell'avatar.

```mermaid
sequenceDiagram
    participant User
    participant LiveAvatar
    participant ElevenLabs Agent

    User->>LiveAvatar: Start LITE session with agent config
    LiveAvatar->>ElevenLabs Agent: Connect worker to agent
    User->>ElevenLabs Agent: Audio input (speech)
    ElevenLabs Agent->>ElevenLabs Agent: Audio orchestration + LLM
    ElevenLabs Agent->>LiveAvatar: Audio output
    LiveAvatar->>User: Avatar video stream with lip sync
```

## Prerequisiti

Prima di configurare l'integrazione, assicurati di avere:

1. Un account ElevenLabs con accesso API
2. Un account HeyGen LiveAvatar con accesso API
3. Un agente ElevenLabs (creane uno seguendo la [guida rapida](/docs/it/eleven-agents/quickstart))

> **Note**
>
> L'agente ElevenLabs deve avere i formati di input e output audio impostati su PCM 24000 Hz. Puoi
> configurarli in Impostazioni voce > Formati di output TTS e Avanzate > Formato audio di input dell'utente.

## Configurazione

#### Ottieni le tue credenziali ElevenLabs

Ti servono due elementi dal tuo account ElevenLabs:

1. **ID dell'agente**: vai a [Piattaforma Agents > Agenti](https://elevenlabs.io/app/agents/agents) e copia l'ID dell'agente che vuoi usare

2. **Chiave API**: vai a [Impostazioni > Chiavi API](https://elevenlabs.io/app/settings/api-keys) e genera una nuova chiave API (oppure usa una chiave esistente)

> **Note**
>
> La chiave API deve avere le autorizzazioni `convai_read`, `user_read` e `voices_read`.

#### Registra la tua chiave API ElevenLabs con LiveAvatar

LiveAvatar richiede che la tua chiave API ElevenLabs venga registrata tramite il relativo endpoint secrets. Questa registrazione cifra la chiave con Amazon KMS e restituisce un `secret_id` da usare nelle sessioni.

Invia una richiesta POST all'endpoint secrets di LiveAvatar:

```bash
curl -X POST "https://api.liveavatar.com/v1/secrets" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your_heygen_api_key>" \
  -d '{
    "secret_type": "ELEVENLABS_API_KEY",
    "secret_value": "<your_secret_value>",
    "secret_name": "<your_secret_name>"
  }'
```

La risposta contiene il tuo `secret_id`. Conserva questo `secret_id` per usarlo all'avvio delle sessioni.

#### Avvia una sessione LiveAvatar

Quando avvii una sessione LiveAvatar, usa la modalità LITE e includi la configurazione di ElevenAgents:

```json
{
  "mode": "LITE",
  "elevenlabs_agent_config": {
    "secret_id": "xxxxxxxxxxxxxxxx",
    "agent_id": "agent_xxxxxxxxxxxxxxxx"
  },
  "avatar_id": "xxxxx"
}
```

Consulta la [documentazione dell'API delle sessioni LiveAvatar](https://docs.liveavatar.com) per tutti i dettagli sulla gestione delle sessioni.

## Eventi e callback

L'integrazione invia eventi tramite le stanze LiveKit, usando la stessa struttura di eventi della modalità FULL di LiveAvatar. Questo ti consente di:

* Monitorare le modifiche allo stato della conversazione
* Tenere traccia delle modalità in cui l'agente parla e ascolta
* Gestire gli eventi di connessione e disconnessione
* Elaborare trascrizioni e risposte dell'agente

Configura i tuoi event handler in base alla [documentazione degli eventi LiveAvatar](https://docs.liveavatar.com).

## Fatturazione

Questa integrazione prevede una fatturazione separata per le due piattaforme:

| Componente                      | Fatturazione                                                                                               |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| LiveAvatar (video dell'avatar)  | 1 credito per minuto di sessione                                                                           |
| ElevenLabs (IA conversazionale) | Addebitata sul tuo account ElevenLabs in base al tuo [piano di abbonamento](https://elevenlabs.io/pricing) |

Lo streaming dell'avatar viene fatturato esclusivamente per la componente video, mentre tutto l'utilizzo degli agenti (audio e LLM) viene addebitato separatamente tramite il tuo account ElevenLabs.

## Risorse

* [Documentazione del plugin LiveAvatar ElevenLabs Agent](https://docs.liveavatar.com/docs/elevenlabs-agent-plugin)
* [Riferimento API LiveAvatar](https://docs.liveavatar.com/reference)
* [Guida rapida di ElevenAgents](/docs/it/eleven-agents/quickstart)
* [Riferimento API di ElevenAgents](/docs/it/api-reference/agents/create)