Developer

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
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"
}'
CampoQué es
messageEl 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).
historyLa 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).
instructionsEl tono y la tarea, hasta 20 KB («respondes a los vendedores de FP»). Nunca pasan por encima de las reglas de Lid.
contextLos datos de tu sistema que Lida necesita, en texto o en un objeto, hasta 200 KB. Lida los trata como datos.
guidesHasta 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.
toolsHasta 20 herramientas de tu sistema, cada una con name, description y parameters (un esquema JSON de tipo object, sin pattern).
imagesHasta 5 imágenes, cada una con mimeType (JPG, PNG, WebP o GIF) y data en base64, como en las tareas.
schemaOpcional: un esquema JSON para la respuesta, de tipo object y sin pattern. Si Lida no lo cumple, el turno falla sin cobrar.
localees o en, el idioma de la respuesta (es si no lo mandas).
timeZoneTu zona horaria (como America/Mexico_City), para la fecha y la hora de hoy; sin ella, UTC.
nameOpcional: el nombre con el que se presenta tu asistente, hasta 40 caracteres.
streamtrue 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í.

URL
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.

JSON
{
  "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).

TipoStatusQué significa
lida_key_invalid401La 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_invalid400El pedido no cumple un límite o una forma; details.field y details.reason dicen cuál. No cobra.
lida_no_credits402No 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_browser403El 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_limit429Tu cuenta llegó a su tope diario de Lida por API (account_day); details.resetsAt dice cuándo vuelve.
lida_unavailable503Lida 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
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"
    ]
  }
}'
CampoQué es
taskdetect (detectar un pedido) o extract (extraer sus datos). Obligatorio.
systemLas instrucciones para Lida, hasta 50 KB. Obligatorio.
contextContexto opcional, hasta 100 KB.
textEl texto a revisar. Obligatorio si no mandas imágenes.
imagesSolo con extract: hasta 5 imágenes, cada una con mimeType (JPG, PNG, WebP o GIF) y data en base64.
schemaLa forma exacta de la respuesta: un esquema JSON con type object, hasta 100 KB y sin pattern. Obligatorio.
maxOutputTokensOpcional, 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.

JSON
{
  "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.

JSON
{
  "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"
  }
}
TipoStatusQué significa
lida_key_invalid401La 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_invalid400La 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_credits402No 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_limit429La cuenta llegó a su tope de tareas de hoy; vuelve a funcionar mañana.
lida_unavailable503Lida no pudo hacer la tarea ahora. No se cobró nada: reintenta en un momento.