Cómo probar una clave de API de IA con curl y Python

Así es cómo probar el acceso a la clave de API sin construir nada: tres llamadas, unos dos minutos y sabrás si la clave es válida, tiene fondos y está autorizada para generar texto.
Puntos clave
- Llama a GET /v1/models primero: demuestra que la clave es aceptada sin gastar crédito.
- Envía una petición de chat corta al modelo uncensored para confirmar que la generación funciona.
- Lee el encabezado X-Balance-USD o GET /v1/balance para ver lo que queda.
- 401 apunta a la clave, 402 al saldo, 429 a tu tasa de peticiones.
La prueba de tres llamadas
Para probar correctamente una clave de API de IA necesitas demostrar tres cosas distintas: que el servidor acepta la clave, que la clave tiene crédito detrás y que llega una respuesta real. Una llamada por pregunta mantiene el diagnóstico simple. Si algo falla, sabes qué capa es la responsable.
- Lista de modelos. Autentica la clave y no cuesta nada.
- Finalización de chat. Confirma que el modelo responde y que tu formato de petición es correcto.
- Saldo. Confirma lo que queda después de la prueba.
Todo lo de abajo usa la URL base https://api.aiapisource.com/v1 y el ID de modelo uncensored. Pon tu clave en una variable de entorno para que nunca termine en el historial de tu shell o en un repositorio.
export AIAPI_KEY="paste-your-key-here"
Si aún no tienes una clave, la página de la clave de API muestra cómo crear una. Las cuentas nuevas pueden reclamar un crédito de prueba de $0,50 allí con un clic, lo cual es más que suficiente para cada prueba en este artículo.
Paso 1: listar modelos con curl
La verificación más barata es una petición de solo lectura. GET /v1/models devuelve la lista de modelos y requiere una clave válida, por lo que una respuesta exitosa demuestra la autenticación.
curl -s https://api.aiapisource.com/v1/models \
-H "Authorization: Bearer $AIAPI_KEY"
Una respuesta saludable es JSON con un array data que incluye uncensored. Si ves una página HTML, un error de conexión o una respuesta vacía, el problema es la URL, no la clave. Verifica que mantuviste el sufijo /v1 y que no hay un espacio al final después de la clave en tu variable.
Añade -i al comando curl para ver los encabezados de respuesta. La API envía X-Request-Id en cada llamada. Guarda ese valor si alguna vez contactas a soporte, porque identifica la petición exacta.
Paso 2: enviar una petición de chat
Ahora verifica la generación. Mantén el prompt diminuto y limita la salida para que la prueba cueste una fracción de centavo.
curl -s https://api.aiapisource.com/v1/chat/completions \
-H "Authorization: Bearer $AIAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "Reply with the single word: ready"}],
"max_tokens": 10
}'
Busca choices[0].message.content y un objeto usage con prompt_tokens y completion_tokens. Una petición de aproximadamente 20 tokens de entrada y 5 de salida cuesta 20 / 1.000.000 x $0,15 más 5 / 1.000.000 x $0,50, que es aproximadamente $0.0000055. Podrías ejecutar cien de estas por menos de un centavo.
El mismo endpoint también funciona para streaming: añade "stream": true y los tokens llegan como eventos enviados por el servidor. Prueba eso por separado una vez que la llamada básica funcione.
Paso 3: la misma prueba en Python
Si tu código real usa un SDK de OpenAI, pruébalo también a través del SDK. Detecta problemas que curl no verá, como una URL base pasada al argumento incorrecto.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["AIAPI_KEY"],
base_url="https://api.aiapisource.com/v1",
)
print([m.id for m in client.models.list().data])
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Reply with the single word: ready"}],
max_tokens=10,
)
print(r.choices[0].message.content)
print(r.usage)
La primera impresión debe mostrar una lista que contiene uncensored. La segunda muestra la respuesta del modelo. Para una guía más detallada de la configuración del SDK, consulta la guía de Python de la API OpenAI en este sitio.
Ejecuta la versión de Python desde la misma shell donde exportaste la clave. Si genera un KeyError en AIAPI_KEY, la variable no está configurada en esa sesión, que es la razón más común por la que una prueba falla antes de llegar a la red.
Node funciona de la misma manera: pasa baseURL: "https://api.aiapisource.com/v1" y la clave al constructor del cliente de OpenAI.
Verificar el saldo
Una clave puede ser válida y aún no tener nada para gastar. Dos formas de leer el saldo:
curl -s https://api.aiapisource.com/v1/balance \
-H "Authorization: Bearer $AIAPI_KEY"
# OpenAI-style alternative
curl -s https://api.aiapisource.com/v1/dashboard/billing/credit_grants \
-H "Authorization: Bearer $AIAPI_KEY"
Cada respuesta también incluye un X-Balance-USD cabecera, por lo que la petición de chat del paso 2 ya te indicó el crédito restante si la ejecutaste con -i. En Python, el SDK de OpenAI expone esto a través de client.chat.completions.with_raw_response.create(...), donde lees response.headers["X-Balance-USD"].
Las peticiones fallidas o rechazadas no se cobran, por lo que una prueba que genera un error no consume crédito. El crédito prepago no caduca, lo que significa que un saldo sin usar seguirá ahí la próxima semana.
Leyendo los códigos de error
Cuando una prueba falla, el estado HTTP acota la causa rápidamente.
| Código | Significado habitual | Qué hacer |
|---|---|---|
| 401 | La clave falta, está mal escrita o fue revocada | Verifica el encabezado Authorization: Bearer, copia la clave de nuevo, busca espacios ocultos o comillas |
| 402 | No queda crédito para pagar la petición | Lee el saldo, luego recarga en la página de precios |
| 404 | Ruta incorrecta o ID de modelo incorrecto | Usa /v1/chat/completions y el modelo uncensored |
| 429 | Límite de tasa o concurrencia, o sobrecarga breve | Espera y reintenta; ver abajo |
Un 429 lleva un código de error. rate_limited significa demasiadas peticiones por minuto y concurrency significa demasiadas a la vez. Una clave completa permite 300 peticiones por minuto y 8 peticiones simultáneas; una clave de prueba permite 60 por minuto y 2 a la vez. En sobrecarga temporal, la API responde 429 con Retry-After: 5, así que espera cinco segundos y envía la petición de nuevo. Una petición en streaming mantiene su espacio de concurrencia hasta que termina el streaming, que es una razón común por la que una clave de prueba alcanza el límite durante pruebas paralelas.
Los códigos de estado 401, 402 y 404 siguen las convenciones normales de API, así que trata la tabla como una primera suposición y lee el cuerpo de error JSON para el mensaje exacto.
Un script de prueba de humo reutilizable
Una vez que la prueba manual pasa, mantén un script que puedas ejecutar después de rotar claves o cambiar entornos.
import os, sys
import requests
BASE = "https://api.aiapisource.com/v1"
H = {"Authorization": "Bearer " + os.environ["AIAPI_KEY"]}
m = requests.get(BASE + "/models", headers=H, timeout=15)
print("models", m.status_code)
c = requests.post(
BASE + "/chat/completions",
headers=H,
json={"model": "uncensored",
"messages": [{"role": "user", "content": "ping"}],
"max_tokens": 5},
timeout=60,
)
print("chat", c.status_code, "balance", c.headers.get("X-Balance-USD"))
sys.exit(0 if m.ok and c.ok else 1)
El código de salida facilita integrarlo en una verificación de despliegue. Para parámetros más allá de este mínimo, la documentación de la API lista todo lo que el endpoint acepta.
Más guías
Preguntas y respuestas
¿Probar una clave de API cuesta dinero?
La lista de modelos es gratuita de consultar. Una solicitud de chat breve con un max_tokens bajo cuesta unos pocos millonésimos de dólar a $0,15 por 1M de tokens de entrada y $0,50 por 1M de tokens de salida. Las peticiones fallidas no se cobran.
¿Cómo pruebo una clave sin tarjeta?
Reclama el crédito de prueba de $0,50 en la página de la clave de API tras registrarte. No necesita tarjeta y es válida por 7 días, una por persona.
¿Por qué una clave válida devuelve 429 de inmediato?
Probablemente hayas alcanzado un límite de concurrencia o por minuto. Las claves de prueba permiten 2 solicitudes concurrentes y 60 por minuto; las claves completas permiten 8 y 300. Comprueba el código de error, luego reduce la velocidad o reintenta después de unos segundos.
¿Puedo probar la clave en Postman o en una app en lugar de curl?
Sí. Cualquier cliente compatible con OpenAI funciona: establece la base URL en https://api.aiapisource.com/v1, pega la clave como un token Bearer y usa el modelo uncensored.
Tu clave está a un formulario de distancia
Crea una cuenta, copia la clave, cambia la URL base. Esa es toda la configuración.