Crea una app de chat con personajes de IA usando la API de eroq

Este es el tutorial que nos habría gustado tener cuando lanzamos nuestro primer producto de personajes. Una tarde de trabajo, un patrón que funciona: entra el personaje, salen las respuestas en streaming y los costos se pueden predecir.

La arquitectura en un párrafo

Tu backend guarda la clave de API, las fichas de personaje y el almacén de conversaciones. El cliente solo habla con tu backend. En cada turno, montas [system] + [windowed history] + [new user message], lo envías a /v1/chat/completions y devuelves la respuesta en streaming. La API no guarda estado, lo que significa que la memoria es cosa de tu producto, y eso es una ventaja.

1. El prompt del personaje

Separa la conducta de la identidad. La identidad es breve; la conducta, estricta:

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(' ')
}

Resiste la tentación de volcar todo el lore. Una historia de fondo de 2,000 palabras en el prompt del sistema te cuesta deriva, no profundidad: inyecta datos concretos solo cuando la escena los toque.

2. El turno, en streaming

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 crédito; 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
}

Conecta onDelta a tu interfaz mediante tu propio SSE o WebSocket. Que los primeros tokens aparezcan en pantalla en menos de un segundo es lo que hace que un personaje se sienta presente.

3. La ventana de historial

Envía los últimos 20 a 40 turnos, nunca todo. El contexto antiguo añade deriva más rápido de lo que añade memoria. Para relaciones largas, haz una pasada de resumen barata cada N mensajes y antepón el resumen como una nota pegada al prompt del sistema: una llamada a eroq-rp-mini (1 crédito) te compra una línea de memoria duradera.

Filtra la ventana antes de enviarla: cualquier turno en el que el modelo se salió del personaje no debería estar en el contexto que vuelves a enviar, o tendrás más de lo mismo.

4. Calcular el costo

Todo el sentido de un precio fijo es que esta tabla exista antes de lanzar:

Comportamiento del usuario	Llamadas/día	Modelo	Créditos/día
Ocasional (20 mensajes)	20	rp-mini	20
Activo (80 mensajes)	80	rp-mini	80
Intensivo + escenas de calidad	150	mixto	~250

A precio de paquete (~$0.01/crédito o menos), un usuario activo cuesta unos $0.80/día en gasto de modelo. Fija el precio de tu suscripción en consecuencia, y añade imágenes (10 créditos) y frases de voz como momentos premium y no como algo por defecto.

5. Los dos errores que hay que gestionar bien

• 402 insufficient_credits: es tu saldo, no un bug tuyo. Ponte una alerta, recarga y degrada con elegancia (pon el mensaje en cola y dile al usuario que el personaje «se ausentó un momento»).
• 502 / eventos de error del stream: se reembolsan automáticamente. Reintenta una vez con backoff; el usuario ve un indicador de escritura, no una disculpa.

Todo lo demás de la guía de errores es estándar.

Preguntas frecuentes

¿Cómo hago que un personaje no se salga de su papel en una conversación larga?

Tres hábitos hacen casi todo el trabajo: un prompt del sistema que especifica la conducta en lugar de la biografía, una ventana con los últimos 20 a 40 turnos en vez de la transcripción completa, y un resumen continuo que se renueva cada ~30 turnos (una llamada a eroq-rp-mini, 1 crédito). Antes de volver a enviar el historial, quita cualquier turno en el que el modelo se haya salido del personaje. Si la deriva sigue apareciendo, pasa esa conversación a RP+, que está ajustado para sostener un personaje en profundidad.

¿Cuánto cuesta por usuario una app de chat con personajes?

Una respuesta cuesta 1 crédito en RP mini y 3 en RP+, sea cual sea su longitud. Un usuario activo con 80 mensajes al día gasta unos 80 créditos diarios: aproximadamente $0.80 a precio de paquete, ya que con $10 compras 1,000 créditos. Las imágenes suman 10 créditos cada una y las fotos adjuntas suman 2, así que lo que hay que vigilar son los momentos premium, no el chat en sí.

¿La API de chat de eroq recuerda los mensajes anteriores?

No, y es deliberado. /v1/chat/completions no guarda estado: en cada llamada envías el historial que quieres que vea el modelo, lo que significa que la memoria es tuya y puedes inspeccionarla, seleccionarla y depurarla. Las fichas de personaje y el estado del mundo pueden viajar en el campo context de nivel superior en lugar de abarrotar tu array messages.

¿Los usuarios pueden enviarle fotos a un personaje?

Sí. El content de un turno del usuario puede ser un array que mezcle partes de texto e image_url (una URL https o un data URI, hasta 2 imágenes por solicitud) a +2 créditos por imagen, además de la respuesta. La guía de visión cubre los patrones de UX y las obligaciones de moderación que siguen siendo tuyas.

Lánzalo

De verdad, ese es todo el patrón: un prompt de conducta, una ventana, un stream, un presupuesto. Consigue una clave, pega la sección 2 y tu primer personaje estará hablando dentro de los cinco minutos del inicio rápido: los 50 créditos gratis cubren toda la tarde de pruebas.