API de IA: protocolo, API Key y primera solicitud

Acceso a la API, suscripciones web y cuentas compartidas

Son productos diferentes:

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 BetterToken, las Base URLs son:

OpenAI-compatible Base URL:  https://www.bettertoken.ai/v1
Anthropic-compatible Base URL: https://bettertoken.ai/

El valor compatible con OpenAI ya incluye /v1. El valor compatible con Anthropic no lo incluye; una solicitud Messages directa utiliza la ruta completa /v1/messages.

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://www.bettertoken.ai/v1/chat/completions
Anthropic Messages raw path: https://www.bettertoken.ai/v1/messages

No 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 BETTERTOKEN_API_KEY="your_api_key_here"
export BETTERTOKEN_MODEL_ID="your_current_model_id"

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 https://www.bettertoken.ai/v1/chat/completions \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$BETTERTOKEN_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 https://www.bettertoken.ai/v1/messages \
  -H "x-api-key: $BETTERTOKEN_API_KEY" \
  -H "anthropic-version: CURRENT_SUPPORTED_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$BETTERTOKEN_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. Si tu tarea requiere específicamente acceso compatible con Claude, revisa la configuración y los límites de acceso de Claude API antes de volver a la solicitud mínima.

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 usage esperados.
• BetterToken Workspace muestra un registro de la misma hora con el modelo, el estado, los tokens de entrada, salida y caché aplicables, y el cargo.

Workspace es un registro de uso y facturación. No presupongas que almacena el prompt o el cuerpo de la respuesta completos. Consulta la disponibilidad y los precios en el catálogo actual de modelos en vez de copiar una lista dinámica en las notas de integración.

7. Diagnostica los errores por capa de respuesta

• 401 o 403: comprueba la clave, el grupo de claves, los espacios, la Base URL y la cabecera de autenticación requerida por el protocolo elegido.
• 404: compara la Base URL con la ruta completa. Busca un /v1, /chat/completions o /messages duplicado.
• model not found: copia el Model ID actual y exacto y confirma que está disponible para el grupo de claves y el protocolo seleccionados.
• 429: lee el cuerpo de la respuesta, respeta cualquier demora indicada y comprueba los límites actuales de concurrencia o velocidad antes de enviar una única solicitud más.
• 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.
• No aparece ningún registro en Workspace: asegúrate de que una variable de entorno antigua no haya dirigido la solicitud a otro proveedor.

Después de cambiar la configuración, vuelve a enviar una sola solicitud breve y relaciónala con Workspace. Cuando funcione, añade streaming, herramientas, un contexto más largo o un bucle de agente capa por capa para que cada nuevo error tenga una superficie de diagnóstico pequeña.

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.