Salta al contenuto

Parla con una statua: crea un'app multi-modale con ElevenAgents

Letters on the noisy background

Fotografa una statua. Scopri chi sono i personaggi rappresentati. Poi parla con loro in tempo reale: ogni personaggio risponde con una voce distinta e adatta all’epoca.

È quello che puoi creare con le API Voice Design e Agent di ElevenLabs. In questo articolo ti mostriamo l’architettura di una web app mobile che unisce computer vision e generazione vocale per trasformare i monumenti pubblici in esperienze interattive. Puoi replicare tutto con le API e gli esempi di codice qui sotto.

Salta il tutorial: creala con un solo prompt

Tutta l’app qui sotto è stata creata da un unico prompt, testato con successo inCursore con Claude Opus 4.5 (high) partendo da un progetto NextJS vuoto. Se vuoi andare direttamente al sodo e costruire la tua versione, incolla questo nel tuo editor:

We need to make an app that:
- is optimised for mobile
- allows the user to take a picture (of a statue, picture, monument, etc) that includes one or more people
- uses an OpenAI LLM api call to identify the statue/monument/picture, characters within it, the location, and name
- allows the user to check it's correct, and then do either a deep research or a standard search to get information about the characters and the statue's history, and it's current location
- then create an ElevenLabs agent (allowing multiple voices), that the user can then talk to as though they're talking to the characters in the statue. Each character should use voice designer api to create a matching voice.
The purpose is to be fun and educational.

https://elevenlabs.io/docs/eleven-api/guides/cookbooks/voices/voice-design
https://elevenlabs.io/docs/eleven-agents/quickstart 
https://elevenlabs.io/docs/api-reference/agents/create


Puoi anche usare le Competenze degli agenti ElevenLabs invece di consultare la documentazione. Sono basate sulle docs e possono dare risultati ancora migliori.

Il resto di questo articolo spiega nel dettaglio cosa produce quel prompt.

Come funziona

La pipeline ha cinque fasi:

  1. Scatta una foto
  2. Identifica l’opera e i personaggi (OpenAI)
  3. Ricerca la storia (OpenAI)
  4. Genera voci uniche per ogni personaggio (ElevenAPI)
  5. Avvia una conversazione vocale in tempo reale tramite WebRTC (ElevenAgents)

Identificare la statua con la visione artificiale

Quando un utente fotografa una statua, l’immagine viene inviata a un modello OpenAI con capacità di visione. Un prompt strutturato estrae nome dell’opera, luogo, artista, data e – cosa fondamentale – una descrizione dettagliata della voce per ogni personaggio. Il prompt include il formato JSON di output atteso:

{
  "statueName": "string - name of the statue, monument, or artwork",
  "location": "string - where it is located (city, country)",
  "artist": "string - the creator of the artwork",
  "year": "string - year completed or unveiled",
  "description": "string - brief description of the artwork and its historical significance",
  "characters": [
    {
      "name": "string - character name",
      "description": "string - who this person was and their historical significance",
      "era": "string - time period they lived in",
      "voiceDescription": "string - detailed voice description for Voice Design API (include audio quality marker, age, gender, vocal qualities, accent, pacing, and personality)"
    }
  ]
}
const response = await openai.chat.completions.create({
  model: "gpt-5.2",
  response_format: { type: "json_object" },
  messages: [
    { role: "system", content: SYSTEM_PROMPT },
    {
      role: "user",
      content: [
        {
          type: "text",
          text: "Identify this statue/monument/artwork and all characters depicted.",
        },
        {
          type: "image_url",
          image_url: {
            url: `data:image/jpeg;base64,${base64Data}`,
            detail: "high",
          },
        },
      ],
    },
  ],
  max_completion_tokens: 2500,
});

Per una foto della statua di Boudica sul Westminster Bridge a Londra, la risposta sarà simile a questa:

{
  "statueName": "Boudica and Her Daughters",
  "location": "Westminster Bridge, London, UK",
  "artist": "Thomas Thornycroft",
  "year": "1902",
  "description": "Bronze statue depicting Queen Boudica riding a war chariot with her two daughters, commemorating her uprising against Roman occupation of Britain.",
  "characters": [
    {
      "name": "Boudica",
      "description": "Queen of the Iceni tribe who led an uprising against Roman occupation",
      "era": "Ancient Britain, 60-61 AD",
      "voiceDescription": "Perfect audio quality. A powerful woman in her 30s with a deep, resonant voice and a thick Celtic British accent. Her tone is commanding and fierce, with a booming quality that projects authority. She speaks at a measured, deliberate pace with passionate intensity."
    },
    // Other characters in the statue
  ]
}

Scrivere descrizioni vocali efficaci

La qualità della descrizione vocale determina direttamente la qualità della voce generata. La guida ai prompt di Voice Design lo spiega nel dettaglio, ma gli elementi chiave da includere sono: indicazione della qualità audio ("Qualità audio perfetta."), età e genere, tono/timbro (profondo, risonante, roca), accento preciso ("forte accento celtico britannico" invece di "britannico"), e ritmo. Più la descrizione è dettagliata, più il risultato sarà accurato – "una newyorkese stanca sui 60 anni con senso dell’umorismo asciutto" funziona molto meglio di "voce femminile anziana".

Alcuni consigli dalla guida: usa "forte" invece di "marcato" per descrivere l’accento, evita termini vaghi come "straniero" e, per personaggi storici o di fantasia, puoi suggerire accenti reali come ispirazione (es. "un’antica regina celtica con forte accento britannico, regale e autorevole").

Creare voci dei personaggi con Voice Design

L’ API Voice Design genera nuove voci sintetiche da descrizioni testuali – non servono campioni vocali né clonazione. È perfetta per personaggi storici di cui non esistono registrazioni.

Il processo si divide in due passaggi.

Genera le anteprime

const { previews } = await elevenlabs.textToVoice.design({
  modelId: "eleven_multilingual_ttv_v2",
  voiceDescription: character.voiceDescription,
  text: sampleText,
});

Il parametro text è importante. Un testo di esempio più lungo e adatto al personaggio (oltre 50 parole) dà risultati più stabili – scegli un dialogo coerente con il personaggio invece di un saluto generico. La guida ai prompt di Voice Design approfondisce questo aspetto.

Salva la voce

Dopo aver generato le anteprime, selezionane una e crea la voce definitiva:

const voice = await elevenlabs.textToVoice.create({
  voiceName: `StatueScanner - ${character.name}`,
  voiceDescription: character.voiceDescription,
  generatedVoiceId: previews[0].generatedVoiceId,
});

Per statue con più personaggi, la creazione delle voci avviene in parallelo. Le voci di cinque personaggi vengono generate in circa lo stesso tempo di una sola:

const results = await Promise.all(
  characters.map((character) => createVoiceForCharacter(character))
);

Creare un agente ElevenLabs multi-voce

Una volta create le voci, il passo successivo è configurare unAgente ElevenLabs che possa cambiare voce in tempo reale a seconda del personaggio.

const agent = await elevenlabs.conversationalAi.agents.create({
  name: `Statue Scanner - ${statueName}`,
  tags: ["statue-scanner"],
  conversationConfig: {
    agent: {
      firstMessage,
      language: "en",
      prompt: {
        prompt: systemPrompt,
        temperature: 0.7,
      },
    },
    tts: {
      voiceId: primaryCharacter.voiceId,
      modelId: "eleven_v3",
      supportedVoices: otherCharacters.map((c) => ({
        voiceId: c.voiceId,
        label: c.name,
        description: c.voiceDescription,
      })),
    },
    turn: {
      turnTimeout: 10,
    },
    conversation: {
      maxDurationSeconds: 600,
    },
  },
});

Cambio voce multi-personaggio

L’array supportedVoices indica all’agente quali voci sono disponibili. La piattaforma Agents gestisce il cambio voce in automatico: quando la risposta dell’LLM indica che sta parlando un altro personaggio, il motore TTS assegna quella parte alla voce corretta.

Prompt engineering per conversazioni di gruppo

Per far sembrare che più personaggi interagiscano davvero – e non solo rispondano in sequenza – serve progettare il prompt con attenzione:

const multiCharacterRules = `
MULTI-CHARACTER DYNAMICS:
You are playing ALL ${characters.length} characters simultaneously.
Make this feel like a group conversation, not an interview.

- Characters should interrupt each other:
  "Actually, if I may -" / "Wait, I must say -"

- React to what others say:
  "Well said." / "I disagree with that..." / "Always so modest..."

- Have side conversations:
  "Do you remember when -" / "Tell them about the time you -"

The goal is for users to feel like they are witnessing a real exchange
between people who happen to include them.
`;

Voce in tempo reale via WebRTC

L’ultimo passaggio è la connessione del client. Gli ElevenLabs Agents supportano WebRTC per conversazioni vocali a bassa latenza – molto più rapido rispetto alle connessioni via WebSocket, il che rende più naturale il cambio di turno nella conversazione.

Lato server: ottieni un token di conversazione

const { token } = await client.conversationalAi.conversations.getWebrtcToken({
    agentId,
});

Lato client: avvia la sessione

import { useConversation } from "@elevenlabs/react";

const conversation = useConversation({
  onConnect: () => setIsSessionActive(true),
  onDisconnect: () => setIsSessionActive(false),
  onMessage: (message) => {
    if (message.source === "ai") {
      setMessages((prev) => [...prev, { role: "agent", text: message.message }]);
    }
  },
});

await conversation.startSession({
  agentId,
  conversationToken: token,
  connectionType: "webrtc",
});

L’hook useConversation gestisce acquisizione audio, streaming, rilevamento dell’attività vocale e riproduzione.

Aggiungere profondità alla ricerca con la ricerca web

Per chi vuole più contesto storico prima di iniziare la conversazione, puoi aggiungere una modalità di ricerca avanzata usando lo strumento di ricerca web di OpenAI:

const response = await openai.responses.create({
  model: "gpt-5.2",
  instructions: RESEARCH_SYSTEM_PROMPT,
  tools: [{ type: "web_search_preview" }],
  input: `Research ${identification.statueName}. Search for current information
including location, visiting hours, and recent news about the artwork.`,
});

Cosa abbiamo imparato

Questo progetto dimostra che, combinando diverse modalità di IA – testo, ricerca, visione e audio – puoi creare esperienze che collegano mondo digitale e reale. C’è ancora molto potenziale nei multi-modal agent che ci piacerebbe vedere esplorato di più per l’educazione, il lavoro e il tempo libero.

Inizia a creare

Le API usate in questo progetto –Progettazione vocale,ElevenAgents e OpenAI – sono tutte disponibili già da oggi.

Scopri gli articoli del team ElevenLabs

Crea con l'audio IA della massima qualità