Enviar una frase a un PNJ

Versión de la API 2026-10-virile-dragon

post https://api.getlingara.com/v1/embed/dialogue/turns

Envía la line del jugador a un personaje y transmite la respuesta del personaje como eventos delta, que terminan con done. El personaje solo habla target_lang, al level del jugador. No se guarda nada: envía la conversación hasta ahora en history. Cada turno se factura a un cliente metered; cualquier otro llamante recibe 403 embed_needs_metered.

Ámbitos embed:play

Parámetros

Lingara-Versionheaderstringopcional: La versión de la API con la que se responde a esta solicitud. Sin ella, un token de acceso recibe la versión a la que está vinculado su cliente, y una solicitud sin token recibe la versión actual. La versión aún en desarrollo solo se alcanza nombrándola aquí. Una versión desconocida responde 400 con el código api_version_unknown. GET /v1/versions enumera las versiones.

Cuerpo de la solicitud `application/json`

npcNpcobligatorio

namestringobligatorio
personastring | nullopcional

scenestring | nullopcional

source_langstringobligatorio

target_langstringobligatorio

levelintegerobligatorio

linestringobligatorio

historyarray of DialogueEntryopcional

La conversación hasta ahora, de la más antigua a la más reciente, con un máximo de 12 líneas. Tú conservas la ventana: Lingara no guarda nada entre turnos. Devuelve cada respuesta del PNJ recortada a sus primeros 500 caracteres.

speakerSpeakerobligatorio
textstringobligatorio

Respuestas

200 La respuesta del personaje, fragmento a fragmento

Eventos del flujo `text/event-stream`

No envía comentarios keepalive.

delta TurnDelta

textstringobligatorio

notice Notice

codestringobligatorio
messagestringobligatorio

done Done Termina el flujo

error StreamError Termina el flujo

Llega dentro de la respuesta 200. La línea de estado ya se ha enviado, así que un fallo después de abrirse el flujo se notifica como este evento.

codestringobligatorio
messagestringobligatorio
plan_idstring | nullopcional

Errores

402application/json: Se rechazó la llamada de un cliente con facturación por uso antes de que gastara nada. spend_cap_reached: el cliente o su cuenta ha alcanzado su límite de gasto mensual; sube el límite en la página Integraciones. metered_billing_inactive: la facturación por uso no está activa para esta cuenta; configúrala o actualiza el método de pago en la página Integraciones.
410application/json: La versión de la API con la que se responde a esta solicitud se ha retirado. Envía una versión admitida en Lingara-Version o vincula el cliente a otra versión.
4XXapplication/json: La solicitud fue rechazada. code indica el motivo y error lo explica con palabras.
503application/json · text/plain: El servicio no está disponible temporalmente; vuelve a intentarlo tras el número de segundos indicado en Retry-After. Durante el mantenimiento, el cuerpo es texto sin formato en lugar del sobre de error.
5XXapplication/json: La solicitud fue rechazada. code indica el motivo y error lo explica con palabras.

codestringobligatorio: Por qué se rechazó la solicitud, como un código estable con el que ramificar: por ejemplo insufficient_scope (403), rate_limited (429) y, para un cliente con facturación por uso, spend_cap_reached (402) y metered_billing_inactive (402).
errorstringobligatorio

Ejemplo

curl -N -X POST "https://api.getlingara.com/v1/embed/dialogue/turns" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"npc":{"name":"Auntie Lin","persona":"a street-food vendor who likes to haggle"},"scene":"A night market in Taipei, just after rain","source_lang":"en","target_lang":"zh","level":3,"line":"How much are the dumplings?","history":[{"speaker":"npc","text":"来来来，刚出锅的饺子！"},{"speaker":"player","text":"你好！"}]}'

¿Prefieres una biblioteca? Consulta la sección Bibliotecas.

Ejemplo de flujo

event: delta
data: {"text":"饺子十块钱一盘，"}

event: delta
data: {"text":"要几盘？"}

event: done
data: {}

Si una traducción y la referencia en inglés difieren, prevalece la referencia en inglés.