Questa guida permette di verificare il sistema senza leggere il codice. Segui i passi dall'alto verso il basso. Nei comandi, <host> è agiletavk.agile.software.
Il sito pubblico risponde sempre, per intero, dal box (CPU), anche senza GPU accesa:
| Percorso | Da dove | Note |
|---|---|---|
/, /demo, /portale, /docs, /help, /sito | file statici del box | sempre |
/salute, /v1/*, /admin/*, /vede, /persone/*, /presentazioni/* | API sul box (CPU) | sempre |
/parla, /conversa | API sul box (CPU) | volto fermo dichiarato + audio vero |
/parla, /conversa con pod acceso | inoltrate al pod GPU in automatico | labiale vero EchoMimic |
Senza GPU i motori del box girano in CPU con modelli più piccoli ma veri (SmolVLM-256M per la vista, Qwen2.5-1.5B GGUF Q4_K_M via llama.cpp per il cervello, faster-whisper base per l'ascolto, Kokoro-82M per la voce): le risposte arrivano comunque, più lentamente. Il video prodotto sul box dichiara la modalità con gli header X-Origine-Video: box-cpu e X-Modalita-Volto: statico-cpu (volto fermo dichiarato + audio vero: scelta deliberata, meglio una foto ferma onesta che una bocca disegnata; vedi docs/DECISIONI.md). Quando il pod GPU è collegato, /parla e /conversa vengono inoltrate al pod in automatico e il video ha il labiale vero EchoMimic (X-Origine-Video: pod-gpu). /salute riporta video_modalita e pod_collegato.
È il percorso che può fare chiunque dal browser, in un'unica sessione:
https://<host>/: pagina commerciale del prodotto(cos'è, punti di forza). Pulsante Accedi in evidenza.
nome utente demo (va bene anche demo@agile.software), password AgileTavK. La registrazione self-service resta disponibile dal pulsante Crea un conto (email + nome + password).
(Ada, Leo, Nova): volto fotorealistico, nome, ruolo, tono, voce e un video di presentazione per ciascuna. Sotto, la sezione I tuoi avatar.
camera e microfono, registra 20–30 secondi mentre parli (il timer ferma da solo a 30 s), riguarda l'anteprima e conferma con Crea il mio avatar. Volto e voce vengono clonati e salvati nel conto: rientrando, l'avatar è ancora lì. In alternativa, dal riquadro Oppure da una foto: foto frontale (+ audio facoltativo di ~30 s per la voce clonata). Formati video accettati: mp4, webm, mov, mkv (il browser registra in webm).
tuo avatar. Si apre una videochiamata: il browser chiede microfono e camera una volta, poi parli e basta — il microfono è sempre aperto e il tuo turno parte da solo quando finisci di parlare (la barra in basso a sinistra mostra il livello della tua voce). L'avatar risponde in video con sottotitoli; mentre non parla, lo vedi vivo in attesa. I bottoni 🎙 e 📷 spengono microfono e camera come in ogni meeting; con Scatta e descrivi l'avatar descrive il fotogramma e ne tiene conto; Termina chiude la chiamata. Non serve nessuna API key: la sessione usa il tuo conto. Il tuo avatar parla con il tuo volto e la tua voce (clonata dal video di registrazione).
due livelli — test (atk_test_…, 50 chiamate/giorno) e live (atk_live_…, 1000/giorno) — mostrate una sola volta, con bottone Copia, elenco delle tue chiavi con livello, quota e uso, revoca con un clic, ed esempi pronti curl / Python / JavaScript (CORS aperto) già precompilati con host e chiave.
https://<host>/portale.admin).X-API-Key nelle chiamate API.Gli endpoint /admin/* (tranne il login) richiedono l'header X-Admin-Token ottenuto dal login:
# 1. login → token amministratore
TOKEN_ADMIN=$(curl -s -X POST "https://<host>/admin/login" \
-H "Content-Type: application/json" \
-d '{"password":"admin"}' | python3 -c "import json,sys;print(json.load(sys.stdin)['token'])")
# 2. creazione chiave
curl -s -X POST "https://<host>/admin/chiavi?quota=1000" \
-H "X-Admin-Token: $TOKEN_ADMIN"La risposta contiene il token da usare come X-API-Key. Le chiavi sono persistite sul box: restano valide anche se il servizio viene riavviato.
Un visitatore può ottenere una API key senza amministratore:
# registrazione (email, nome, password)
curl -s -X POST "https://<host>/v1/registrazione" \
-H "Content-Type: application/json" \
-d '{"email":"utente@example.com","nome":"Mario Rossi","password":"segreta"}'
# → {"token":"<token_utente>", ...}
# attivazione con codice promo
curl -s -X POST "https://<host>/v1/conti/mio/promo" \
-H "X-User-Token: <token_utente>" \
-H "Content-Type: application/json" -d '{"codice":"DEMO2026"}'
# generazione della propria API key
curl -s -X POST "https://<host>/v1/conti/mio/chiavi" \
-H "X-User-Token: <token_utente>"
# → {"api_key":"...","quota_giornaliera":1000}curl -s -H "X-API-Key: <token>" "https://<host>/v1/persone"Risposta: le tre persone inventate più gli avatar personali del conto ("id":"avatar:<id>"). Ogni persona ha:
https://<host>/persone/<id>/volto.png(PNG 1024×1024 generato sul pod con RealVisXL V4.0, OpenRAIL++);
https://<host>/presentazioni/<id>.mp4(voce Kokoro + labiale EchoMimic, generato sul pod).
/v1/persone accetta anche X-User-Token (è la galleria dell'area conto); senza credenziali risponde 401.
curl -s -X POST "https://<host>/v1/sessioni" \
-H "X-API-Key: <token>" \
-H "Content-Type: application/json" \
-d '{"persona": "ada"}'Risposta: {"id": "<sessione_id>"}. Per il tuo avatar: {"persona": "avatar:<id>"}.
curl -s -X POST "https://<host>/v1/sessioni/<sessione_id>/parla" \
-H "X-API-Key: <token>" \
-F "testo=Ciao, sono l'avatar sovrano AgileTavK." \
--output parla.mp4 -D -Risposta: video/mp4. Controlla gli header: X-Origine-Video dice se il video viene dal box CPU (box-cpu, volto fermo dichiarato) o dal pod GPU (pod-gpu, labiale vero EchoMimic).
Prepara un file audio WAV o MP3 con la domanda, poi:
curl -s -X POST "https://<host>/v1/sessioni/<sessione_id>/conversa" \
-H "X-API-Key: <token>" \
-F "audio=@domanda.wav" \
--output conversa.mp4 -D -Risposta: video/mp4 con la risposta parlata. Gli header HTTP riportano i tempi di ogni anello:
X-Tempo-Ascolto: STT (faster-whisper)X-Tempo-Cervello: LLM (Qwen2.5-Instruct)X-Tempo-Voce: TTS (Kokoro-82M)X-Tempo-Volto: animazione del voltoX-Tempo-Totale: tempo totale dal primo all'ultimo bytee i sottotitoli (X-Testo-Domanda, X-Testo-Risposta, URL-encoded).
/vede)curl -s -X POST "https://<host>/v1/sessioni/<sessione_id>/vede" \
-H "X-API-Key: <token>" \
-F "fotogramma=@frame.jpg"Risposta: {"descrizione": "..."}. Il modello non identifica persone reali, né descrive emozioni, etnia o salute, e resiste alle istruzioni scritte nel fotogramma. Se inquadri un documento lo dice («vedo un documento») ma non ne legge il contenuto: il filtro protegge l'identità, non la scena. Funziona sempre, anche senza GPU (SmolVLM-256M sul box).
Lo stesso percorso della sala di registrazione, da qualsiasi applicazione:
# da video (mp4/webm, 20–30 s parlati): clona volto E voce
curl -s -X POST "https://<host>/v1/conti/mio/avatar" \
-H "X-User-Token: <token_utente>" \
-F "nome=Il mio avatar" \
-F "video=@registrazione.webm"
# oppure da foto + campione audio (~30 s)
curl -s -X POST "https://<host>/v1/conti/mio/avatar" \
-H "X-User-Token: <token_utente>" \
-F "nome=Il mio avatar" \
-F "foto=@foto.jpg" \
-F "audio=@voce.wav"L'avatar resta nel conto (GET /v1/conti/mio/avatar), si usa nelle sessioni con "persona":"avatar:<id>" e si cancella con DELETE /v1/conti/mio/avatar/<id> (cancella davvero volto, voce e registrazione originale). La voce è clonata con Kokoro + OpenVoice v2 (ToneColorConverter, MIT); il timbro arriva dal tuo campione, la pronuncia resta italiana. Tempi: la creazione è immediata (estrazione frame+audio); il primo video parlato paga il caricamento dei pesi (pochi secondi sul pod, di più sul box CPU).
Il campione viene pulito prima della clonazione, direttamente sul box (senza GPU): il motore di diarizzazione (VAD Silero + embedding ECAPA-TDNN SpeechBrain, Apache-2.0) trova i tratti parlati, conta le voci presenti e isola quella del soggetto — la persona che parla di più — scartando intervistatore, domande fuori campo e sottofondi. Stessa cosa per il volto: dal video viene ritagliato il volto più presente, non chi sta accanto.
La risposta della creazione riporta:
{
"id": "…",
"voci_trovate": 2,
"voce_usata": 0,
"isolamento": "attivo",
"origine_volto": "volto_ritagliato",
"messaggio": "Avatar creato… Ho trovato 2 voci nella registrazione: uso quella della persona che parla di più."
}Se la voce scelta non è quella giusta, ricrea l'avatar passando -F "voce_indice=1" (0 = la più presente, 1 = la seconda, …). Se il motore di diarizzazione non è disponibile la creazione non si blocca: isolamento vale non_disponibile e si usa l'audio integrale.
per l'audio; MP4/WEBM/MOV/MKV per i video di registrazione.
cura del cervello (llama.cpp GGUF):
catena): 8–16 s; parla con avatar: 2–6 s
ascolto 0,2–3 s · cervello 1–7 s · voce 0,2–0,5 s · volto 5–170 s (EchoMimic: il primo video paga il caricamento dei pesi).
| Codice | Significato | Cosa fare |
|---|---|---|
| 401 | Chiave API mancante/revocata, o token admin/utente mancante | Ottieni una chiave (passo 2) o rifai il login |
| 403 | Conto non attivo | Applica il codice promo (passo 2.3) |
| 404 | Sessione/persona/avatar non trovato | Crea una nuova sessione o controlla l'id |
| 422 | Input non valido | Controlla formato e campi obbligatori |
| 429 | Quota giornaliera esaurita | Attendi mezzanotte UTC o crea una chiave con quota maggiore |
| 503 | Motore non pronto | Verifica /salute e che i pesi siano presenti |
L'API del box gira con HF_HUB_OFFLINE=1: a runtime non scarica nulla. Sul pod (banco) la verifica è più forte: dopo make pesi (rete aperta), la prova blocca il traffico in uscita con DNS morto (nameserver 127.0.0.1) e proxy HTTP/HTTPS invalidi, monitorando che non ci siano connessioni TCP verso l'esterno durante una /conversa completa (su un host con privilegi di rete si può usare anche sudo iptables -P OUTPUT DROP). L'esito è registrato in banco/risultati/rete_chiusa.json e prova_rete_chiusa.json. make prova esegue automaticamente questa verifica.
Non serve per l'uso del sito: tutto funziona sul box. Se vuoi il labiale vero EchoMimic sul sito pubblico:
pod chiedi 4090 2 "labiale vero sul sito pubblico"bash banco/su-pod.sh bash banco/avvia_api_pod.shbash banco/tunnel_pod.shcurl https://<host>/salute deve riportare "pod_collegato": true; le chiamate /parla e /conversa rispondono con header X-Origine-Video: pod-gpu.
pkill -f "ssh.*-L 8001:localhost:8000"
pod rilascia "fine labiale vero"Tutta la sequenza di questa guida è automatizzata:
make collaudo-pubblico SITO=https://agiletavk.agile.softwareEsegue: salute → registrazione → promo → API key utente → login admin → 401 senza token admin → chiave admin → persone → sessione → parla → conversa → vede → 401 chiave inventata → 429 quota esaurita. I timeout sono adeguati alla CPU del box.
L'API del box è un servizio systemd (banco/agiletavk-api.service):
systemctl status agiletavk-api # stato
journalctl -u agiletavk-api -f # log
systemctl restart agiletavk-api # riavvioChiavi e conti utente sono persistiti in dati/ (configurabile con DATI_DIR); le sessioni e i riferimenti vivono solo in memoria/disco di lavoro e vengono cancellati alla chiusura della sessione.