API de IA: protocolo, API Key y primera solicitud
Elige el protocolo de API de IA correcto, protege la clave, envía una solicitud mínima y comprueba la respuesta y el registro de uso.
Índice
Antes de conectar una API de IA, identifica el contrato que espera tu cliente: compatible con OpenAI o con Anthropic. Después, utiliza la Base URL documentada por el proveedor, mantén la API Key fuera del código fuente, envía una solicitud breve y verifica tanto la respuesta como su registro de uso. Que una pantalla de configuración se guarde correctamente no demuestra que la solicitud haya llegado al endpoint previsto.
Si necesitas una pasarela de API en lugar de una suscripción web específica de un proveedor, empieza por la descripción general de las API de IA de BetterToken. BetterToken ofrece interfaces separadas compatibles con OpenAI y Anthropic. Seguirás utilizando tu propia cuenta de BetterToken y tu propia API Key; la clave no es una clave de OpenAI Console ni de Anthropic Console.
Acceso a la API, suscripciones web y cuentas compartidas
Son productos diferentes:
| Vía de acceso | Qué recibes | Qué no implica |
|---|---|---|
| Acceso a la API | Solicitudes HTTP autenticadas con tu propia clave | Acceso a la suscripción de chat para consumidores de un proveedor |
| Suscripción web | Una interfaz de producto concreta y sus límites incluidos | Un saldo de API transferible o una API Key de terceros |
| Cuenta compartida | La sesión iniciada por otra persona | Una integración de producción segura o adecuada |
Para el desarrollo habitual, utiliza una cuenta y una clave que controles. No construyas una integración alrededor de un acceso comprado o compartido.
1. Elige el protocolo a partir del cliente
Lee la documentación del cliente o del SDK antes de elegir un modelo. Utiliza la interfaz compatible con OpenAI cuando la herramienta espere un SDK de OpenAI, Chat Completions, Responses API o un campo como OPENAI_BASE_URL. Utiliza la interfaz compatible con Anthropic cuando cree solicitudes Messages y espere ANTHROPIC_BASE_URL o x-api-key.
El nombre del modelo no determina el protocolo. El cliente debe crear el mismo contrato de solicitud que acepta el endpoint.
Para un proveedor compatible con OpenAI, la Base URL y la ruta de Chat Completions pueden tener esta forma:
Base URL: https://api.example.com/v1
Ruta completa: https://api.example.com/v1/chat/completionsPara un proveedor compatible con Anthropic, la forma puede ser: Base URL https://api.example.com y ruta completa de Messages https://api.example.com/v1/messages. Son formas, no valores listos para pegar: copia los valores reales de la documentación del proveedor elegido.
¿Necesitas comprobar el protocolo y los campos de la primera solicitud? Abrir la referencia de configuración de la API
2. Distingue la Base URL de la ruta de solicitud
Un SDK o una herramienta suele pedir una Base URL y añade su propia ruta del recurso. Una llamada HTTP directa necesita la ruta completa.
OpenAI-compatible raw path: https://api.example.com/v1/chat/completions
Anthropic Messages raw path: https://api.example.com/v1/messagesNo pegues una ruta de solicitud completa en un campo que solo espera una Base URL. De lo contrario, el cliente puede añadir el recurso dos veces y devolver un error 404.
3. Mantén la API Key fuera del código
Utiliza variables de entorno locales para la primera prueba y traslada después las credenciales de producción al gestor de secretos que proporcione tu plataforma.
export API_KEY="your_api_key_here"
export MODEL_ID="your_current_model_id"
export OPENAI_BASE_URL="https://api.example.com/v1"
export ANTHROPIC_BASE_URL="https://api.example.com"No incluyas nunca una clave real en el código fuente, .env.example, un prompt, una incidencia, una captura de pantalla o un mensaje de soporte. Copia el Model ID actual y exacto de la documentación o del catálogo del proveedor en lugar de deducirlo de un nombre comercial.
4. Envía una solicitud mínima compatible con OpenAI
Empieza con una solicitud breve de solo texto antes de habilitar streaming o herramientas:
curl "$OPENAI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$MODEL_ID"'",
"messages": [{"role": "user", "content": "Reply with API_OK"}],
"max_tokens": 16
}'Evita curl -v en registros que compartas con otras personas, porque la salida detallada puede revelar cabeceras sensibles.
5. Envía una solicitud mínima compatible con Anthropic
La solicitud Messages utiliza una cabecera de autenticación y una estructura de cuerpo diferentes:
curl "$ANTHROPIC_BASE_URL/v1/messages" \
-H "x-api-key: $API_KEY" \
-H "anthropic-version: CURRENT_SUPPORTED_VERSION" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$MODEL_ID"'",
"max_tokens": 16,
"messages": [{"role": "user", "content": "Reply with API_OK"}]
}'CURRENT_SUPPORTED_VERSION es un marcador de posición. Confirma la cabecera admitida actualmente en la referencia de la API antes de realizar la prueba.
6. Verifica la respuesta y el registro de uso
La primera prueba solo termina cuando coinciden estas señales:
- El estado HTTP indica que la solicitud se completó correctamente.
- La respuesta contiene el Model ID esperado o su valor de presentación documentado.
- El contrato elegido devuelve el contenido y los campos
usageesperados. - El registro de uso o facturación del proveedor muestra la solicitud con el estado y el cargo esperados.
La disponibilidad de modelos, sus ID y los precios cambian. Consulta el catálogo y la página de precios actuales del proveedor elegido antes de calcular un presupuesto.
7. Diagnostica los errores por capa de respuesta
- 401: comprueba la clave, los espacios y el método de autenticación. Bearer y
x-api-keyno son intercambiables. - 404: compara la Base URL con la ruta completa. Busca un
/v1,/chat/completionso/messagesduplicado. - model not found: copia el Model ID actual y exacto y confirma que está disponible para el grupo de claves y el protocolo seleccionados.
- Timeout o error TLS: separa las condiciones locales de proxy, firewall, DNS y certificados de una respuesta de la API. No desactives permanentemente la verificación TLS.
El orden práctico es: identificar el contrato del cliente, guardar la clave como secret, configurar la Base URL correcta, enviar una solicitud breve y comprobar la respuesta junto con el registro de uso. Añade streaming, herramientas, contexto largo o un flujo de agentes solo después.
Siguiente paso: API compatible con OpenAI
Para una ruta práctica de configuración con tu propia clave y una ruta compatible con OpenAI, consulta la página de API de OpenAI. Describe una API compatible de BetterToken, no una clave oficial de OpenAI.
Las formas https://api.example.com, https://api.example.com/v1, https://api.example.com/v1/messages y https://api.example.com/v1/chat/completions son solo ejemplos: usa los valores documentados por el proveedor elegido.
