So fügen Sie Ihrer Website eine sprechende KI-Figur hinzu
Fügen Sie jeder Website eine sprechende KI-Figur hinzu: Installieren Sie das Neocortex Web SDK, halten Sie den API-Schlüssel auf Ihrem Server, setzen Sie ein Sprachchat-Element ein und verarbeiten Sie Aktionen.
Sercan AltundasFounder of Neocortex
· 7 Min. Lesezeit

Eine Figur auf der Website ist ein Guide, ein Gastgeber oder ein Verkaufsassistent, mit dem Besucher mit eigenen Worten sprechen können, mit Persönlichkeit und Stimme statt einer austauschbaren Chatblase. Dieser Leitfaden zeigt, wie Sie mit dem Neocortex Web SDK eine solche Figur auf jeder Website einbaust: ein paar Zeilen auf dem Server, ein Element auf der Seite und optionale Aktionen, mit denen die Figur etwas tun kann.
Was Sie bauen
Eine Figur auf Ihrer Seite, die:
- getippte oder gesprochene Fragen mit eigener Stimme beantwortet
- Ihre Inhalte kennt, aus einem Wissensspeicher, den Sie hochladen
- Aktionen auf der Seite ausführen kann, etwa ein Produkt öffnen oder eine Tour starten
- Ihren API-Schlüssel niemals dem Browser preisgibt
Was Sie brauchen
- Ein Neocortex-Konto, einen API-Schlüssel und eine Figur aus dem Dashboard
- Einen Server mit Node 20 oder neuer, oder Cloudflare Workers, Bun oder Deno
- Eine Seite, die über HTTPS ausgeliefert wird, weil Browser das Mikrofon nur auf sicheren Seiten erlauben
Schritt 1: Entwirf die Figur
Geben Sie der Figur im Neocortex-Editor eine Persönlichkeit, eine Stimme und einen Wissensspeicher mit Ihren Produktseiten, FAQs oder Tour-Notizen. Testen Sie sie im Browser, bis sie richtig klingt: Das Testen im Editor ist in jedem Tarif enthalten. Kopieren Sie die ID der Figur aus dem Dashboard.
Schritt 2: Installiere das SDK
Führen Sie npm install @neocortex-link/web im Projekt Ihrer Website aus.
Schritt 3: Fügen Sie den Proxy auf Ihrem Server hinzu
Neocortex-API-Schlüssel sind geheim. Wer einen Schlüssel aus dem JavaScript Ihrer Seite liest, kann die Nutzung auf Ihrem Konto in die Höhe treiben. Deshalb liefert das SDK einen kleinen Server-Handler mit, der den Schlüssel hält. Er prüft außerdem, wer spricht, und lässt nur die Figuren zu, die Sie auflisten.
In einer Next.js-App legen Sie app/api/neocortex/[...path]/route.ts an:
import { createNeocortexHandler } from "@neocortex-link/web/server";
import { auth } from "@/auth";
const handler = createNeocortexHandler({
apiKey: process.env.NEOCORTEX_API_KEY!,
characters: ["your-character-id"],
authorize: async () => {
const session = await auth();
return session?.user ? { id: session.user.id } : null;
},
});
export { handler as GET, handler as POST, handler as OPTIONS };authorize gibt den Besucher als { id } zurück oder null, um abzulehnen. Diese ID wird zur playerId der Figur, sodass jeder Besucher seine eigene Unterhaltung hat. Für Express umhüllen Sie denselben Handler mit toNodeHandler und hängen Sie ihn unter /api/neocortex ein. Seiten ohne Anmeldung können jedem Besucher eine feste ID in einem signierten Cookie geben.
Schritt 4: Setze die Figur auf die Seite
Laden Sie die Oberfläche einmal mit import "@neocortex-link/web/ui/auto" (oder über ein CDN-Script-Tag, wenn Ihre Seite keinen Bundler hat) und setzen Sie dann das Element dorthin, wo die Figur erscheinen soll:
<neocortex-chat endpoint="/api/neocortex" character-id="your-character-id" voice></neocortex-chat>Der Chat hat ein Textfeld und Mikrofoneingabe. Das Attribut voice fügt gesprochene Antworten hinzu: Jede Zeile wird als Sprache gestreamt, und die nächste Zeile wird geladen, während die aktuelle läuft. Ergänzen Sie push-to-talk, wenn Besucher den Knopf beim Sprechen gedrückt halten sollen, oder mic="false" für reinen Text.
Die Elemente sind Standard-Web-Components, sie funktionieren also in React, Vue, Svelte, Angular oder reinem HTML, und Sie können sie mit CSS-Custom-Properties im hellen oder dunklen Modus umgestalten. Es gibt außerdem Elemente für einen Gruppenchat mit mehreren Figuren (Pro- und Team-Tarife) und einen Quizmoderator (Team-Tarif).
Schritt 5: Lass die Figur handeln
Definieren Sie Aktionen im Editor, etwa OPEN_PRODUCT oder START_TOUR, und verarbeiten Sie sie dann auf der Seite:
const chat = document.querySelector("neocortex-chat");
chat.agent.registerAction("OPEN_PRODUCT", (action) => openProduct(action.targetId));openProduct ist Ihre eigene Funktion. Die Figur entscheidet, wann eine Aktion zum Gespräch passt, und Ihr Code entscheidet, was sie tut.
Ideen für Website-Figuren
- Ein Produktguide in einem 3D-Konfigurator, der Optionen erklärt und auf Wunsch die Farben wechselt.
- Ein Event-Gastgeber, der Fragen zum Programm beantwortet und Besucher zur richtigen Bühne schickt.
- Eine Museums- oder Markenfigur, die Geschichten aus Ihrem Archiv mit eigener Stimme erzählt.
- Die Landingpage eines Spiels, auf der Besucher vor dem Kauf mit den Figuren des Spiels sprechen können.
Unsere Anwendungsfall-Leitfäden behandeln KI-Einkaufsführer für 3D-Webshops und KI-Gastgeber für virtuelle Events ausführlicher.
Häufige Probleme
- Das Mikrofon startet nicht. Browser verlangen HTTPS und einen Klick oder Tipp, bevor aufgenommen wird. Testen Sie auf Ihrer echten Domain, nicht in einer Vorschau über reines HTTP.
- 401 oder 403 vom Endpunkt.
authorizehatnullzurückgegeben, oder die ID der Figur steht nicht in der Listecharacters. - Der Schlüssel ist im Browser gelandet. Geben Sie ihn niemals an Client-Code weiter. Nur der Server-Handler darf
NEOCORTEX_API_KEYlesen.
Nächste Schritte
Für Game-Engines statt Websites beginnen Sie mit wie Sie Ihrem Unity-Spiel eine KI-Figur hinzufügen. Um die Sprachseite zu verstehen, lesen Sie wie die Sprachpipeline für KI-NPCs funktioniert. Jedes Tutorial der Reihe finden Sie im Leitfaden zum Bau von KI-NPCs, und die vollständige Einrichtung steht in der Doku zum Web SDK.
Häufig gestellte Fragen
Wie füge ich meiner Website eine KI-Figur mit Stimme hinzu?
Installieren Sie das Neocortex Web SDK, fügen Sie seinen kleinen Proxy auf Ihrem Server hinzu, damit der API-Schlüssel geheim bleibt, und setzen Sie dann ein neocortex-chat-Element mit dem Attribut voice auf die Seite. Besucher können tippen oder sprechen, und die Figur antwortet laut.
Kann ich einen KI-Chatbot auf meiner Website nutzen, ohne meinen API-Schlüssel offenzulegen?
Ja. Das Neocortex Web SDK enthält einen Server-Handler, der den Schlüssel hält, prüft, wer spricht, und nur die Figuren zulässt, die Sie auflisten. Der Browser spricht immer nur mit Ihrem eigenen Endpunkt.
Funktioniert es mit React, Vue oder WordPress?
Die Chat-Oberfläche besteht aus Standard-Web-Components, sie funktioniert also in React, Vue, Svelte, Angular und reinem HTML. Jede Seite, die einen kleinen Server-Endpunkt betreiben kann, etwa mit Next.js, Express oder Cloudflare Workers, kann den Proxy hosten.
Ist das Neocortex Web SDK kostenlos?
Das SDK ist Open Source unter Apache-2.0. Gespräche zählen auf Ihren Neocortex-Tarif.
Kann die Figur auf der Seite etwas tun?
Ja. Definieren Sie Aktionen für die Figur im Neocortex-Editor und registrieren Sie dann auf der Seite für jede einen Handler, etwa um ein Produkt zu öffnen, eine Tour zu starten oder zu einem Abschnitt zu scrollen.






