Una API de inteligencia artificial es una interfaz mediante la que una aplicación envía una solicitud a un servicio de modelo y recibe una respuesta. La API define formato, autenticación, límites y errores; no elimina el trabajo de diseñar contexto, permisos y validación en la aplicación.
Qué contiene una solicitud
Puede incluir instrucciones, mensajes, parámetros, archivos o referencias. El backend debe construirla desde datos permitidos y limitar tamaño y coste. No expongas la clave al navegador ni permitas que el usuario cambie libremente opciones sensibles.
Respuesta, errores y versiones
La respuesta puede ser texto, una estructura o un error de límite. Gestiona códigos, timeout, reintentos y cambios de modelo. Registra la versión utilizada cuando esté disponible; una respuesta puede variar después de una actualización del proveedor.
Rate limits y control de coste
Limita solicitudes por usuario, sesión o aplicación y define un presupuesto. El número de tokens de entrada y salida afecta al consumo. Una entrada maliciosa o una conversación sin límite puede producir gasto y latencia innecesarios.
Datos y seguridad
Antes de enviar información, clasifica datos y revisa retención y condiciones. En el backend valida la identidad, separa tenants y evita guardar secretos en logs. La API no convierte automáticamente la salida en confiable ni la conexión en una autorización para actuar.
Fallback y experiencia
Una web debe seguir ofreciendo una respuesta razonable si el servicio tarda o no está disponible. Puede mostrar una opción manual, usar una respuesta determinista o poner la solicitud en cola. Informa sin revelar detalles internos ni prometer una respuesta que no se ha verificado.
Medir la integración
Registra latencia por etapa, tokens, errores, reintentos, coste y revisión humana. Prueba entradas vacías, contexto largo, formato incorrecto y servicio caído. Una API es una dependencia de software y necesita el mismo mantenimiento que cualquier otra integración.
Diseñar el contrato
Un contrato de API debe describir entrada, salida, errores, límites y versiones. Si la respuesta es texto libre, la aplicación necesita validaciones adicionales. Si es estructurada, define esquema y comportamiento para campos ausentes o desconocidos.
Reintentos sin duplicar acciones
Un timeout no demuestra que el proveedor no haya procesado la solicitud. Para una operación con efectos, utiliza identificadores idempotentes o no ejecutes la acción directamente desde una respuesta del modelo. Reintentar una consulta informativa no tiene el mismo riesgo que repetir un pago o un cambio de cuenta.
Observabilidad
Relaciona solicitud, latencia, tokens, código de error y versión sin guardar secretos. Las métricas de coste deben poder atribuirse a usuario o función con el nivel de privacidad permitido. Monitoriza también rechazos y respuestas de fallback.
Dependencia de proveedor
Una API puede cambiar modelos, límites, precios o formatos. Mantén una capa de adaptación para no repartir detalles del proveedor por toda la aplicación y prueba una alternativa cuando el riesgo de interrupción lo justifique.
Contrato de entrada y salida
Define tipos, límites, errores, versiones y comportamiento cuando falte un campo. Un esquema JSON puede facilitar validación, pero una estructura correcta puede contener una afirmación falsa. Comprueba valores contra el sistema autorizado.
Reintentos y operaciones
Un timeout no demuestra que la solicitud no se procesara. Para acciones con efectos utiliza idempotencia o una confirmación independiente. Una consulta informativa puede reintentarse de forma distinta a una modificación de cuenta.
Coste y cuota
Limita tokens de entrada y salida, tamaño de archivos, frecuencia y presupuesto. Registra el consumo por función y usa una respuesta alternativa cuando se alcance el límite. Una conversación sin control puede crecer sin que el usuario perciba el coste.
Fallback y continuidad
Define una respuesta fija, una cola o una revisión cuando el proveedor no esté disponible. Una integración que bloquea la web durante una caída externa no tiene un comportamiento operativo completo.
Probar la API
Incluye timeout, límite, respuesta inválida, error de autenticación, cambio de versión y entrada larga. Conserva métricas y una ruta para revertir la configuración.
Una API necesita mantenimiento
Prueba respuestas largas, límites, errores, cambios de versión y fallos de red. Registra coste, latencia y reintentos sin conservar secretos. La aplicación debe continuar de forma controlada cuando el proveedor no responde.
El contrato debe ser conocido por quien mantiene el backend.
Validar la respuesta en el servidor
Un esquema válido puede contener un identificador o importe erróneo. Contrasta valores y permisos con el sistema que tiene autoridad antes de guardar o ejecutar. Para acciones con efectos, utiliza confirmación o idempotencia.
Medir el contrato
Prueba timeout, límite, autenticación, formato inválido, entrada larga, versión nueva y fallo de red. Documenta qué respuesta recibe el usuario y cómo se evita bloquear la web.
El proveedor es una dependencia
Puede cambiar versión, precio, límite o formato. Mantén una capa de adaptación, una respuesta alternativa y pruebas de regresión. La aplicación debe continuar de forma controlada durante una caída.
Seguridad de la integración
Rota claves, limita cuota y no expongas secretos al navegador. Un error de autenticación no debe mostrar la configuración interna.
Una prueba de API debe incluir límite, timeout, respuesta inválida y fallo de red. Documenta siempre el fallback.
El contrato se revisa después de cambiar versión.
La respuesta debe poder asociarse a una versión, una solicitud y un coste. Esa trazabilidad facilita corregir una integración sin guardar secretos.