¿Qué es una API? Explicación con IA y tu primer curl
Aprende qué es una API con ejemplos prácticos de inteligencia artificial: JSON, métodos HTTP, códigos de error y tu primera petición curl explicada paso a paso.
👁 113 lecturas
Una API es un contrato entre dos programas: uno envía una petición en un formato acordado y el otro devuelve una respuesta, también en un formato establecido. Cuando tu script le pide a un modelo de IA que resuma un correo, no hace clic en una ventana de chat; envía por internet un paquete de texto en formato JSON y recibe otro JSON de vuelta. Este artículo es el primer paso de la guía de API de IA desde cero, donde muestro todo con peticiones reales ejecutadas en mi ordenador.
Qué es una API explicado de forma sencilla: la ventanilla con formulario
La forma más simple de imaginar una API es como una ventanilla de atención al público que solo acepta formularios cumplimentados. No ves lo que hay detrás ni sabes quién tramita tu caso ni cómo lo hace. En cambio, sabes tres cosas:
- A qué ventanilla acudir - es la dirección o endpoint, por ejemplo
https://openrouter.ai/api/v1/chat/completions; - Cómo rellenar el formulario - es el formato de la petición detallado en la documentación: qué campos son obligatorios y cuáles opcionales;
- Con qué identificarte - es la clave de API (API key), que adjuntas a cada solicitud.
El encargado te devuelve el trámite resuelto o bien un aviso con un código de error: «falta la firma», «demasiadas solicitudes por hoy», «el sistema no funciona». En una API, estos avisos corresponden a los códigos de estado HTTP que veremos más abajo.
La diferencia entre un chat y una API radica en que el chat (ChatGPT, Claude, Gemini) es una aplicación terminada para personas, mientras que la API es el acceso directo al mismo modelo para un programa. A través de la API, el modelo no recuerda tus conversaciones anteriores, no tiene botones ni historial visible. A cambio, puedes llamarlo mil veces desde una hoja de cálculo, desde un bot o mediante un proceso automatizado por la noche. En ese caso no pagas una suscripción fija, sino únicamente los tokens consumidos (fragmentos de texto), un concepto que explico en el artículo Tokens en IA: qué son y cuánto cuestan.
Petición y respuesta (request y response)
Cada comunicación con una API consta de dos partes. La petición (request) incluye:
- Método - qué acción deseas realizar. Para los modelos de IA se utiliza casi siempre POST, ya que envías contenido.
- Dirección - el endpoint de una función concreta, como generar texto u obtener la lista de modelos.
- Encabezados (headers) - metadatos: la clave de API (
Authorization: Bearer ...) y el tipo de contenido (Content-Type: application/json). - Cuerpo (body) - los datos reales: qué modelo utilizar, qué mensajes enviar y qué parámetros aplicar.
La respuesta (response) contiene un código de estado (por ejemplo 200, que indica éxito) y un cuerpo donde se encuentra el texto generado junto con el contador de tokens consumidos. Así es una respuesta real que recibí el 4 de octubre de 2026 del modelo GPT-6 Luna a través de OpenRouter (resumida en sus campos principales):
{
"id": "gen-1791114764-uKPpeyAgJg4GJmOQhMp4",
"object": "chat.completion",
"model": "openai/gpt-6-luna",
"provider": "OpenAI",
"choices": [
{
"index": 0,
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": "Krak\u00f3w zachwyca zabytkowym Rynkiem G\u0142\u00f3wnym, klimatycznymi uliczkami i bogat\u0105 histori\u0105."
}
}
],
"usage": {
"prompt_tokens": 16,
"completion_tokens": 36,
"total_tokens": 52,
"cost": 0.0000196
}
}La lectura de estos datos es la siguiente: el modelo respondió con una frase sobre Cracovia (traducción del original polaco de la prueba: «Cracovia cautiva con su histórica Plaza del Mercado, sus calles llenas de encanto y su rica historia») dentro del campo content, finalizó con normalidad (finish_reason: stop), consumió 16 tokens de entrada y 36 de salida, y la petición completa costó 0,0000196 USD (aprox. 0,0000175 EUR al cambio de referencia del BCE del 12/10/2026, fuente: https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml), es decir, menos de dos milésimas de centavo.
JSON en 2 minutos
JSON (JavaScript Object Notation) es un formato de texto estructurado para el intercambio de datos que resulta legible tanto para las personas como para cualquier lenguaje de programación. Basta con conocer cinco elementos:
{ }- objeto, es decir, un conjunto de parejas «clave: valor», por ejemplo{"model": "openai/gpt-6-luna"};[ ]- lista o array, por ejemplo la lista de mensajes de una conversación;"texto"- cadenas siempre entre comillas dobles (las comillas simples provocan error de sintaxis);- números sin comillas:
0.7,1024- con punto decimal, nunca con coma; true,false,null- verdadero, falso o ausencia de valor.
Una petición a un modelo de IA es un objeto con el campo model y una lista de messages. Cada mensaje tiene un rol (system para instrucciones directas al modelo, user para ti y assistant para respuestas previas del modelo) y su contenido (aquí traducido del texto original probado en polaco: «Escribe una frase sobre Cracovia»):
{
"model": "openai/gpt-6-luna",
"messages": [
{"role": "user", "content": "Escribe una frase sobre Cracovia."}
]
}El fallo más habitual en principiantes es dejar una coma tras el último elemento de una lista o de un objeto. JSON no lo admite y el servidor responderá con un código 400. Cuando necesites que el modelo devuelva JSON estructurado y no solo texto libre, te resultará útil el modo explicado en el artículo Structured output: cómo obligar a la IA a responder en JSON.
Métodos HTTP: GET, POST y otros
| Método | Significado | Ejemplo en API de IA |
|---|---|---|
| GET | Recuperar datos sin modificarlos | Lista de modelos: GET /api/v1/models |
| POST | Enviar datos para su procesamiento | Generar una respuesta: POST /api/v1/chat/completions |
| PATCH / PUT | Modificar un recurso existente | Cambiar el límite de gasto de una clave mediante la API de gestión |
| DELETE | Eliminar un recurso | Borrar un archivo o una clave de API |
En la práctica, durante las primeras semanas utilizarás principalmente dos: GET para consultar qué recursos están disponibles y POST para generar contenido.
Códigos de estado y errores: 401, 429, 500 y más
El código de estado es un número de tres dígitos situado al inicio de la respuesta. El primer dígito indica el origen del resultado: 2xx representa éxito, 4xx señala un error por parte del cliente y 5xx indica un fallo del servidor.
| Código | Qué significa | Qué hacer |
|---|---|---|
| 200 | OK, la respuesta se incluye en el cuerpo | Nada, procesar el resultado recibido |
| 400 | Petición incorrecta: error en JSON, modelo desconocido o parámetro inválido | Lee el mensaje de error, corrige la llamada y no reintentes en bucle |
| 401 | Falta la clave de API o no es válida | Verifica las variables de entorno y confirma que la clave no esté desactivada |
| 402 | Fondos insuficientes en la cuenta (OpenRouter) | Recarga saldo o incrementa el límite fijado para la clave |
| 403 | Sin permisos: modelo no disponible en la región o contenido bloqueado por moderación | Cambia de modelo o adapta el contenido enviado |
| 404 | La dirección o el modelo no existen | Comprueba que no haya erratas en la URL o identificador |
| 429 | Demasiadas peticiones en poco tiempo (rate limit) o cuota agotada | Espera unos segundos y reintenta aplicando una pausa progresiva |
| 500, 502, 503 | Avería o sobrecarga en los servidores del proveedor | Reintenta pasados unos segundos o cambia temporalmente de proveedor |
| 529 | Sobrecarga de capacidad (código específico de Anthropic) | Mismo procedimiento que con el código 503 |
Hice la prueba directa de qué responde el servicio al omitir la clave de autenticación. Esta es la respuesta a una petición sin encabezado Authorization enviada a OpenRouter:
$ curl -s https://openrouter.ai/api/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"openai/gpt-6-luna","messages":[{"role":"user","content":"hola"}]}'
{"error":{"message":"No cookie auth credentials found","code":401}}Y así se muestran dos errores capturados por mi script en Python: una clave incorrecta y un modelo inexistente. Como detalle técnico: OpenRouter devuelve un código 400 ante un modelo desconocido en lugar de un 404, por lo que en el código conviene no asumir un único número para cada supuesto.
401: comprueba la clave API (Error code: 401 - {'error': {'message': 'User not found.', 'code': 401}})400: corrige la peticion (Error code: 400 - {'error': {'message': 'openai/gpt-7-nie-istnieje is not a valid model ID', 'code': 400}})Si quieres ver cómo gestionar estos códigos dentro de tu programa y aplicar reintentos automáticos ante un error 429, consulta el artículo Primera petición a una API de IA en Python.
Primer curl: cómo hacer peticiones desde la terminal
curl es una herramienta de línea de comandos para enviar peticiones HTTP. Viene preinstalada en Windows 10 y 11 (como curl.exe), en macOS y en Linux, por lo que no necesitas instalar nada. Empezamos con una petición GET que no requiere clave para obtener la lista de modelos disponibles en OpenRouter:
{"data":[{"id":"inclusionai/ling-3.1-flash","canonical_slug":"inclusionai/ling-3.1-flash-20261002","hugging_face_id":null,"name":"inclusionAI: Ling 3.1 Flash","created":1790950024,"description":"Ling 3.1 Flash is a hybrid reasoning mixture-of-experts model from inclusionAI, with 25B active parameters out of 560B total.","contextLa llamada devuelve un objeto con la lista data, que el 4 de octubre incluía 466 modelos. Ahora ejecutamos una petición POST para consultar directamente al modelo. Primero necesitas disponer de tu clave (tienes instrucciones paso a paso para cuatro proveedores en Clave API: cómo conseguirla y cómo protegerla). En Git Bash, Linux y macOS (el prompt original probado estaba en polaco y pedía escribir una frase sobre Cracovia):
#!/usr/bin/env bash
# Primera peticion mediante curl (Git Bash, Linux, macOS). Antes: export OPENROUTER_API_KEY=sk-or-v1-...
curl -s https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-6-luna",
"messages": [{"role": "user", "content": "Napisz jedno zdanie o Krakowie."}]
}'En PowerShell el escape de comillas dobles en JSON suele dar problemas, por lo que resulta más práctico guardar el cuerpo en el archivo zapytanie.json (con la misma estructura mostrada antes) y pasarle el archivo a curl. Ten en cuenta usar curl.exe en vez de curl, ya que en versiones anteriores de PowerShell curl es un alias de otro comando:
# Windows PowerShell: cuerpo de la peticion en el archivo zapytanie.json (evita conflictos de comillas)
# Antes, en la misma ventana: $env:OPENROUTER_API_KEY = "sk-or-v1-..."
curl.exe -s https://openrouter.ai/api/v1/chat/completions `
-H "Authorization: Bearer $env:OPENROUTER_API_KEY" `
-H "Content-Type: application/json" `
-d "@zapytanie.json"Ejecuté ambas variantes en Windows 11 (Git Bash con curl 8.22 y Windows PowerShell). En los dos casos, enviando la petición original en polaco, el modelo respondió con una frase sobre Cracovia y cada consulta tuvo un coste aproximado de 0,00002 USD (aprox. 0,0000179 EUR según la cotización de referencia del BCE del 12/10/2026 de 1 EUR = 1,1181 USD; fuente: https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml). Ambos archivos se encuentran disponibles en el paquete del recurso archivo de inicio de api.
Siguientes pasos
- Crea tu cuenta y genera tu credencial: Clave API en OpenAI, Anthropic, Google AI Studio y OpenRouter.
- Escribe tu primer script: Primera petición a una API de IA en Python.
- Calcula los costes previstos: Tokens en IA y calculadora de costes.
- Cuando domines las llamadas básicas, pasa a la creación de flujos y agentes: Agentes de IA desde cero.
Preguntas frecuentes
¿Qué es una API en palabras sencillas?
Es el método mediante el cual un programa solicita tareas o datos a otro: remite una petición con una estructura fijada y recibe una respuesta en un formato acordado, sin necesidad de conocer cómo funciona el sistema de destino internamente.
¿Qué significan las siglas API?
Corresponden a Application Programming Interface (Interfaz de Programación de Aplicaciones). Se denomina interfaz porque actúa como punto de contacto entre dos sistemas de software, de forma equivalente a cómo una pantalla con botones sirve de interfaz para las personas.
¿Es obligatorio saber programar para utilizar una API?
Para lanzar una primera prueba no es imprescindible: basta con la herramienta curl y copiar el comando correspondiente. No obstante, para integrar resultados en flujos útiles conviene manejar nociones básicas de Python o emplear herramientas de automatización como n8n o Zapier, que gestionan las peticiones por ti.
¿Cuál es la diferencia entre una API y ChatGPT?
ChatGPT es una aplicación con suscripción periódica, historial interactivo e interfaz pensada para usuarios humanos. La API de OpenAI es la vía de acceso a los modelos para programas informáticos, facturada según los tokens consumidos, sin almacenamiento de historial de chat previo ni interfaz visual. La suscripción de ChatGPT no cubre el uso de la API; corresponden a cuentas y facturaciones separadas.
¿Qué es una API REST?
Es el estilo arquitectónico más extendido para construir servicios web: los recursos cuentan con identificadores en forma de URL, las operaciones se eligen mediante métodos HTTP (GET, POST, DELETE) y la información se transmite predominantemente en formato JSON. Las API de los modelos de IA siguen este patrón.
Google · Tus fuentesBrilla más alto en tu Google - con un solo clicAñadir a fuentes preferidas →Fuentes y fecha de verificación
Las pruebas se ejecutaron el 4 de octubre de 2026 en Windows 11 a través de OpenRouter, con un coste total acumulado inferior a 0,0001 USD (aprox. 0,000089 EUR al cambio de referencia del BCE del 12/10/2026, fuente: https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml).
More on this from FULGOR
