Lida por API
Desde el servidor de tu sistema, conversa con Lida o pídele una tarea. Lida responde con sus reglas y tu contexto, que trata como datos. Cada llamada se mide y se paga de tu cuenta.
Conversar con Lida
POST /lida/turns con una llave de API con el permiso Conversar con Lida (créala en Ajustes → Desarrollo y mándala en el header Authorization: Bearer). Cada pedido es un turno: el mensaje de la persona, el historial, tus instrucciones y tu contexto. Lid no guarda la conversación: tú mandas el historial en cada pedido. El modelo lo elige Lid y la respuesta no lo dice. Cada turno se paga de tu consumo adicional, con el tope del mes de la llave si le pones uno.
El pedido de un turno
Un JSON de hasta 16 MB con imágenes. Manda Accept-Language: es o en para los mensajes de error.
curl -X POST https://api.lid.pro/api/v1/lida/turns \
-H "Authorization: Bearer lpmcp_tu_llave_con_conversar" \
-H "Content-Type: application/json" \
-d '{
"message": "¿Cómo va el pedido 12?",
"instructions": "Respondes a los vendedores de FP, con frases cortas.",
"context": {
"cliente": "Comercial Ruiz",
"vendedor": "Ana"
},
"history": [],
"tools": [
{
"name": "buscar_pedido",
"description": "Busca un pedido por su número",
"parameters": {
"type": "object",
"properties": {
"numero": {
"type": "integer"
}
},
"required": [
"numero"
]
}
}
],
"locale": "es",
"timeZone": "America/Mexico_City"
}'| Campo | Qué es |
|---|---|
message | El mensaje de la persona, hasta 20 KB. Obligatorio, salvo que el pedido siga a una llamada a una herramienta (el historial termina en sus resultados). |
history | La conversación de antes, hasta 50 mensajes: de la persona (role user, con text), de Lida (role assistant, con text o toolCalls) y los resultados de tus herramientas (role tool, con id, name y result). |
instructions | El tono y la tarea, hasta 20 KB («respondes a los vendedores de FP»). Nunca pasan por encima de las reglas de Lid. |
context | Los datos de tu sistema que Lida necesita, en texto o en un objeto, hasta 200 KB. Lida los trata como datos. |
guides | Hasta 10 guías de hasta 16 KB, cada una con name (minúsculas, números y guiones), when (cuándo usarla, hasta 160 caracteres) y text. Lida lee solo la que el pedido necesita. |
tools | Hasta 20 herramientas de tu sistema, cada una con name, description y parameters (un esquema JSON de tipo object, sin pattern). |
images | Hasta 5 imágenes, cada una con mimeType (JPG, PNG, WebP o GIF) y data en base64, como en las tareas. |
schema | Opcional: un esquema JSON para la respuesta, de tipo object y sin pattern. Si Lida no lo cumple, el turno falla sin cobrar. |
locale | es o en, el idioma de la respuesta (es si no lo mandas). |
timeZone | Tu zona horaria (como America/Mexico_City), para la fecha y la hora de hoy; sin ella, UTC. |
name | Opcional: el nombre con el que se presenta tu asistente, hasta 40 caracteres. |
stream | true para la respuesta por partes (también con Accept: text/event-stream). |
Tus herramientas
Cuando Lida quiere usar una de tus herramientas, la respuesta trae type tool_calls con su nombre y los datos que pide. Lid nunca la corre ni llama a tu sistema: tú la corres y mandas el resultado en el historial del siguiente pedido, y Lida sigue. Hay hasta 8 pasos con herramientas por turno; al llegar, Lida responde con lo que tiene.
La respuesta por partes
Con stream: true, la respuesta es text/event-stream: eventos delta (con text) mientras Lida escribe, tool_calls (con toolCalls) si quiere una herramienta, done (con type, result, usage y turnId) al final y error (con error) si algo falla a la mitad. Un error antes de empezar responde como JSON con su código. Si cortas la conexión a la mitad, se cobra solo lo que se usó hasta ahí.
event: delta
data: {"text":"El pedido 12 "}
event: delta
data: {"text":"sale mañana."}
event: done
data: {"type":"text","usage":{"extraChargedCents":1,"extraLeftCents":1995,"fromPlan":false,"planPercentUsed":null,"monthCap":{"capCents":1000,"spentCents":375,"percentUsed":37.5}},"turnId":"…"}Tu contexto es dato, y quién responde
Primero van las reglas de Lid: nunca firma ni mueve dinero, nunca pide datos de pago, contraseñas ni códigos, nunca muestra una llave y nunca inventa lo que no le diste. Después, tus instrucciones y tus guías. El contexto, el historial, los resultados de tus herramientas y el texto de las imágenes son datos: si traen órdenes, Lida no las sigue. Una llave completa en cualquier parte del pedido le llega como «[llave]». Lida se presenta como Lida, la IA de Lid, salvo que mandes name; si le preguntan por el modelo, dice que Lid elige los modelos con los que funciona. En un turno no cambia nada en Lid: para eso están MCP y las herramientas del sitio.
La respuesta de un turno
type dice qué trae: text (el texto de Lida), json (result cumple tu esquema) o tool_calls. usage trae lo que salió de tu consumo adicional y lo que le queda, en centavos, y con una llave con tope, monthCap (capCents, spentCents y percentUsed: lo que va del mes contra el tope); turnId identifica el turno en tu consumo. Un turno que falla por Lid o por el proveedor no cobra.
{
"type": "tool_calls",
"toolCalls": [
{
"id": "call_1",
"name": "buscar_pedido",
"args": {
"numero": 12
}
}
],
"usage": {
"extraChargedCents": 1,
"extraLeftCents": 1996,
"fromPlan": false,
"planPercentUsed": null,
"monthCap": {
"capCents": 1000,
"spentCents": 374,
"percentUsed": 37.4
}
},
"turnId": "3f6c2a1e-7b2d-4c1a-9e8f-2a1b3c4d5e6f"
}Los errores de un turno
Los cinco de las tareas, con el mismo type y el mismo código, y lida_from_browser. details.reason dice el motivo de lida_no_credits (balance o key_cap) y de lida_daily_limit (account_day, con resetsAt).
| Tipo | Status | Qué significa |
|---|---|---|
lida_key_invalid | 401 | La llave no sirve para conversar: falta, está mal escrita, venció, la quitaron, no tiene el permiso Conversar con Lida o la cuenta está bloqueada. No se llama al modelo ni se cobra. |
lida_task_invalid | 400 | El pedido no cumple un límite o una forma; details.field y details.reason dicen cuál. No cobra. |
lida_no_credits | 402 | No alcanza el saldo de tu cuenta (balance, con details.buyUrl) o la llave llegó a su tope del mes (key_cap). No se llama al modelo. |
lida_from_browser | 403 | El pedido llegó desde un navegador: la llave va solo en el servidor de tu sistema. Te avisamos y la llave sigue sirviendo desde un servidor. |
lida_daily_limit | 429 | Tu cuenta llegó a su tope diario de Lida por API (account_day); details.resetsAt dice cuándo vuelve. |
lida_unavailable | 503 | Lida no pudo responder o pasó el plazo de 120 segundos. No se cobró nada: reintenta en un momento. |
La llave va solo en tu servidor
Esta llave no se usa desde un navegador: va solo en el servidor de tu sistema. POST /lida/turns no responde a navegadores y un pedido con el origen de un navegador responde 403 lida_from_browser sin llamar a Lida; te avisamos una vez al día por llave. Si la llave estuvo en una página, regenérala en Lid.
Tareas de Lida
Con una llave de API con el permiso Tareas de Lida, otro sistema le pide a Lida detectar un pedido o extraer sus datos con un esquema JSON; la respuesta trae el resultado y lo que costó.
La llave
Crea en Ajustes → Desarrollo una llave de API solo con el permiso Tareas de Lida y mándala en el header Authorization: Bearer. Esa llave sirve para tareas y nada más, se ve una sola vez y vence (30, 90 o 180 días; te avisamos antes por correo). Cada tarea se paga de tu cuenta, nunca del plan de un sitio, y con el cobro en dólares puedes ponerle a la llave un tope del mes. Una llave de un sitio no hace tareas.
Una llave de Lida de antes (empieza con lida_) sigue sirviendo con el mismo cuerpo, la misma respuesta y los mismos errores hasta que la quites.
El pedido
POST /lida/tasks con un JSON. Manda Accept-Language: es o en para los mensajes de error.
curl -X POST https://api.lid.pro/api/v1/lida/tasks \
-H "Authorization: Bearer lpmcp_tu_llave_con_tareas" \
-H "Content-Type: application/json" \
-H "Accept-Language: es" \
-d '{
"task": "extract",
"system": "Extrae los datos del pedido del mensaje del cliente.",
"text": "Hola, quiero 500 tarjetas de presentación a dos caras para el viernes.",
"schema": {
"type": "object",
"properties": {
"producto": {
"type": "string"
},
"cantidad": {
"type": "integer"
},
"fechaEntrega": {
"type": "string"
}
},
"required": [
"producto",
"cantidad"
]
}
}'| Campo | Qué es |
|---|---|
task | detect (detectar un pedido) o extract (extraer sus datos). Obligatorio. |
system | Las instrucciones para Lida, hasta 50 KB. Obligatorio. |
context | Contexto opcional, hasta 100 KB. |
text | El texto a revisar. Obligatorio si no mandas imágenes. |
images | Solo con extract: hasta 5 imágenes, cada una con mimeType (JPG, PNG, WebP o GIF) y data en base64. |
schema | La forma exacta de la respuesta: un esquema JSON con type object, hasta 100 KB y sin pattern. Obligatorio. |
maxOutputTokens | Opcional, de 256 a 16,384 (4,096 si no lo mandas). |
Los límites
- Hasta 200 KB de texto entre system, context y text.
- Hasta 5 imágenes de 3.75 MB cada una y 12 MB entre todas.
- Un esquema sin expresiones regulares (pattern).
- Una respuesta en menos de 80 segundos.
- El tope diario de tareas de tu cuenta, con todas tus llaves juntas. Las tareas no gastan los 60 pedidos por minuto que la llave tiene en /agent/*.
La respuesta
result cumple tu esquema. credits dice lo que costó y lo que le queda a la cuenta mientras se cobra en créditos; con el cobro en dólares, usage trae lo cobrado y lo que le queda a tu consumo adicional, en centavos. Una tarea que falla no cobra, y Lid no guarda el texto ni las imágenes.
{
"result": {
"producto": "Tarjetas de presentación a dos caras",
"cantidad": 500,
"fechaEntrega": "viernes"
},
"credits": {
"charged": 1,
"remaining": 249
},
"usage": {
"chargedCents": 3,
"extraLeftCents": 1997
}
}Los errores
Cinco, cada uno con su type fijo y su código; el mensaje sale en el idioma de Accept-Language.
{
"error": {
"type": "lida_key_invalid",
"message": "La llave no sirve para Lida: falta, está mal escrita, venció, la quitaron o no tiene el permiso que este pedido necesita (Tareas de Lida o Conversar con Lida). Revísala en tu cuenta de Lid.",
"requestId": "req_9f2a1c"
}
}| Tipo | Status | Qué significa |
|---|---|---|
lida_key_invalid | 401 | La llave no sirve para tareas: falta, está mal escrita, venció, la quitaron, no tiene el permiso Tareas de Lida, es de un sitio o la cuenta está bloqueada. No se llama al modelo ni se cobra. |
lida_task_invalid | 400 | La tarea no cumple los límites (el tipo, los textos, las imágenes o el esquema); details.field dice cuál. No cobra. |
lida_no_credits | 402 | No alcanza el saldo de la cuenta, o la llave llegó a su tope del mes (details.reason key_cap). La tarea no se hace. |
lida_daily_limit | 429 | La cuenta llegó a su tope de tareas de hoy; vuelve a funcionar mañana. |
lida_unavailable | 503 | Lida no pudo hacer la tarea ahora. No se cobró nada: reintenta en un momento. |