Envías un mensaje a un personaje y te responde. Si mandas el conversacion que te devolvió, recuerda lo hablado mientras sigas escribiéndole (4 horas desde el último mensaje).
Las rutas que hablan con la IA piden Authorization: Bearer <clave> (o X-Clave). Listar personajes no la pide.
| GET | /api/personajes | Personajes disponibles, con su saludo |
| POST | /api/personajes/{id}/conversar | Enviar un mensaje |
| GET | /api/conversaciones/{id} | Historial de una conversación viva |
| DELETE | /api/conversaciones/{id} | Olvidarla |
| GET | /api/estado | Motor, modelo y memoria |
Personajes: elfa (Nimeriel), ogro (Grumbak), duende (Pizco).
POST /api/personajes/elfa/conversar
Content-Type: application/json
Authorization: Bearer <clave>
{ "mensaje": "¿Puedo sentarme junto al pozo?",
"conversacion": "<opcional: id de la respuesta anterior>",
"viajero": "<opcional: tu nombre>" }
200 OK
{ "conversacion": "6f0c1c9e-…",
"personaje": "elfa",
"respuesta": "*El agua tiembla…* Vaya, un corazón mortal…",
"reiniciada": false,
"expira": "2026-10-22T23:41:00.000Z" }
reiniciada: true: el id que mandaste había caducado y empieza una conversación nueva. Las acciones del personaje van entre *asteriscos*.
Con ?stream=1 o Accept: text/event-stream la respuesta llega por eventos SSE: inicio {conversacion}, varios texto {t}, y fin con lo mismo que la respuesta JSON (o error {codigo, mensaje}).
curl -N "https://taberna.unlimited-systems.net/api/personajes/ogro/conversar?stream=1" \
-H "Authorization: Bearer $CLAVE" -H "Content-Type: application/json" \
-d '{"mensaje": "¡Déjame cruzar el puente, bestia!"}'
Siempre {"error": {"codigo", "mensaje"}}: 400 petición mal formada · 401 clave · 404 no existe · 409 aún respondiendo al anterior · 413 mensaje de más de 2000 caracteres · 422 el modelo declinó · 429 límite (40 mensajes cada 10 min por IP, y uno diario) · 502/503/504 problema con la IA.