Eine KI-Charakter-Chat-App mit der eroq-API bauen

Das ist das Tutorial, das wir uns gewünscht hätten, als wir unser erstes Charakter-Produkt ausgeliefert haben. Ein Abend Arbeit, ein funktionierendes Muster: Persona rein, gestreamte Antworten raus, Kosten, die du vorhersagen kannst.

Die Architektur in einem Absatz

Dein Backend verwaltet den API-Schlüssel, die Charakterbögen und den Gesprächsspeicher. Der Client spricht nur mit deinem Backend. In jedem Zug setzt du [system] + [windowed history] + [new user message] zusammen, schickst es an /v1/chat/completions und streamst die Antwort zurück. Die API ist zustandslos – dein Produkt verwaltet also das Gedächtnis, und das ist ein Feature.

1. Der Persona-Prompt

Halte Verhalten und Identität getrennt. Die Identität ist kurz, das Verhalten streng:

function personaPrompt(character) {
  return [
    `You are ${character.name}. ${character.oneLineIdentity}`,
    character.voiceNotes,                    // "dry humor, short sentences, hates small talk"
    'Stay fully in character. Never mention being an AI or add out-of-character notes.',
    'Actions in *asterisks*. Advance the scene, then hand it back.',
  ].join(' ')
}

Widersteh dem Lore-Dump. Eine Hintergrundgeschichte mit 2.000 Wörtern im System-Prompt bringt dir Drift, keine Tiefe – füge konkrete Fakten erst ein, wenn die Szene sie berührt.

2. Der Zug, gestreamt

export async function characterReply(character, history, userMessage, onDelta) {
  const res = await fetch('https://eroq.ai/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.EROQ_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'eroq-rp-mini',                 // 1 Credit; rp-plus where it matters
      stream: true,
      messages: [
        { role: 'system', content: personaPrompt(character) },
        ...history.slice(-30),               // the window — see below
        { role: 'user', content: userMessage },
      ],
    }),
  })

  const reader = res.body.getReader()
  const decoder = new TextDecoder()
  let buffer = ''
  let full = ''
  while (true) {
    const { done, value } = await reader.read()
    if (done) break
    buffer += decoder.decode(value, { stream: true })
    const events = buffer.split('\n\n')
    buffer = events.pop() ?? ''
    for (const event of events) {
      const data = event.replace(/^data: /, '')
      if (data === '[DONE]') continue
      const chunk = JSON.parse(data)
      const delta = chunk.choices?.[0]?.delta?.content
      if (delta) { full += delta; onDelta(delta) }
    }
  }
  return full
}

Leite onDelta über dein eigenes SSE oder WebSocket an deine UI weiter. Erste Tokens in unter einer Sekunde auf dem Bildschirm – das lässt einen Charakter präsent wirken.

3. Das Verlaufsfenster

Schick die letzten 20–40 Züge, nie alles. Älterer Kontext bringt schneller Drift als Gedächtnis. Bei langen Beziehungen lässt du alle N Nachrichten einen günstigen Zusammenfassungsdurchlauf laufen und stellst die Zusammenfassung als systemnahe Notiz voran – ein einziger eroq-rp-mini-Aufruf (1 Credit) kauft dir eine dauerhafte Erinnerungszeile.

Filter das Fenster vor dem Senden: Jeder Zug, in dem das Modell aus der Rolle gefallen ist, gehört nicht in den Kontext, den du zurückschickst – sonst bekommst du mehr davon.

4. Die Kosten

Der ganze Sinn fester Preise ist, dass diese Tabelle existiert, bevor du startest:

Nutzerverhalten	Aufrufe/Tag	Modell	Credits/Tag
Gelegentlich (20 Nachr.)	20	rp-mini	20
Engagiert (80 Nachr.)	80	rp-mini	80
Power-User + Qualitätsszenen	150	Mix	~250

Zu Paketpreisen (~$0.01/Credit oder weniger) kostet ein engagierter Nutzer etwa $0.80/Tag an Modellkosten. Kalkulier dein Abo entsprechend und biete Bilder (10 Credits) und Sprachzeilen als Premium-Momente an statt als Standard.

5. Die zwei Fehler, die du gut behandeln solltest

• 402 insufficient_credits – dein Guthaben, nicht dein Bug. Alarmier dich selbst, lad auf und reagier elegant (stell die Nachricht in die Warteschlange, sag dem Nutzer, der Charakter sei „kurz weg“).
• 502 / Stream-Fehler-Events – werden automatisch erstattet. Einmal mit Backoff wiederholen; der Nutzer sieht eine Tipp-Anzeige, keine Entschuldigung.

Alles andere im Fehler-Leitfaden ist Standard.

Häufige Fragen

Wie bleibt ein Charakter über ein langes Gespräch hinweg in seiner Rolle?

Drei Gewohnheiten erledigen den Großteil: ein System-Prompt, der Verhalten statt Biografie festlegt, ein Fenster der letzten 20–40 Züge statt des ganzen Verlaufs und eine fortlaufende Zusammenfassung, die etwa alle ~30 Züge aufgefrischt wird (ein eroq-rp-mini-Aufruf, 1 Credit). Wirf jeden Zug raus, in dem das Modell aus der Rolle gefallen ist, bevor du den Verlauf zurückschickst. Zeigt sich trotzdem Drift, verlege das Gespräch auf RP+, das darauf abgestimmt ist, eine Persona auch in der Tiefe zu halten.

Was kostet eine Charakter-Chat-App pro Nutzer?

Eine Completion kostet 1 Credit mit RP mini und 3 mit RP+, egal wie lang die Antwort ist. Ein engagierter Nutzer mit 80 Nachrichten am Tag verbraucht etwa 80 Credits täglich – ungefähr $0.80 zu Paketpreisen, da $10 1.000 Credits kauft. Bilder kosten je 10 Credits und angehängte Bilder 2 zusätzlich – die Premium-Momente sind also die Zeile, die du im Blick behalten musst, nicht der Chat selbst.

Merkt sich die Chat-API von eroq frühere Nachrichten?

Nein, und das ist Absicht. /v1/chat/completions ist zustandslos: Du schickst bei jedem Aufruf den Verlauf mit, den das Modell sehen soll – du verwaltest also das Gedächtnis und kannst es einsehen, kuratieren und debuggen. Charakterbögen und Weltzustand können im Top-Level-Feld context mitreisen, statt dein messages-Array zu überladen.

Können Nutzer einem Charakter Bilder schicken?

Ja. Der content eines Nutzerzugs kann ein Array aus Text- und image_url-Teilen sein – eine https-URL oder eine Data-URI, bis zu 2 Bilder pro Anfrage –, zu +2 Credits pro Bild zusätzlich zur Completion. Die Vision-Anleitung behandelt die UX-Muster und die Moderationspflichten, die bei dir bleiben.

Ab damit in Produktion

Das ist wirklich das ganze Muster: ein Verhaltens-Prompt, ein Fenster, ein Stream, ein Budget. Hol dir einen Schlüssel, füge Abschnitt 2 ein, und dein erster Charakter spricht innerhalb der fünf Minuten des Quickstarts – die 50 Gratis-Credits reichen für einen ganzen Testabend.