cursorapikey.com/Guía
Claves de API de Cursor no funcionan: soluciones con endpoint personalizado
Cuando las claves de API de Cursor no funcionan, la causa casi siempre es una de cuatro cosas: la URL base, el nombre del modelo, la clave en sí o un límite de la cuenta. Un único comando curl te indica cuál es.
Actualizado


Puntos clave
- Prueba la clave fuera de Cursor primero con curl; si curl funciona, el problema está en la configuración de Cursor.
- La URL base debe ser https://api.cursorapikey.com/v1 y el nombre del modelo debe ser exactamente uncensored.
- 401 significa una clave incorrecta, 404 una URL incorrecta, 429 un límite de tasa o concurrencia, y un error de modelo un nombre incorrecto.
- Las etiquetas del menú cambian entre versiones de Cursor, así que ajusta el campo al propósito correspondiente en lugar de la redacción exacta.
Paso 1: prueba la clave fuera de Cursor
Excluye a Cursor de la ecuación. Si una petición simple funciona, tu clave y cuenta están bien y la falla está en la configuración del editor. Si falla, el cuerpo del error indica el problema.
curl -i https://api.cursorapikey.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"uncensored","messages":[{"role":"user","content":"Reply with the word ready."}]}'
La bandera -i imprime la línea de estado y los encabezados. Un estado 200 con un array choices significa éxito. El encabezado X-Balance-USD muestra tu crédito restante, que es lo primero que debes verificar si obtienes un error de autorización o pago.
También puedes listar los modelos, lo que confirma la clave sin gastar nada:
curl https://api.cursorapikey.com/v1/models -H "Authorization: Bearer YOUR_KEY" | grep uncensored
La respuesta debe contener el ID del modelo uncensored.
Paso 2: configura los campos en Cursor
Abre la configuración de Cursor y busca la sección Modelos. Necesitas tres valores, y un error en cualquiera de ellos produce un fallo que parece una clave rota.
- Clave de API de OpenAI: pega tu clave sin espacios ni saltos de línea al principio ni al final.
- Anulación de URL base de OpenAI: activa la anulación e ingresa
https://api.cursorapikey.com/v1. Mantén el/v1y omite/chat/completions. - Modelo personalizado: añade un modelo llamado
uncensoredy actívalo. Desactiva los modelos que no uses para que Cursor no seleccione uno que el endpoint no conozca.
Después de guardar, usa la opción de verificación si tu versión la tiene, luego selecciona uncensored en el menú desplegable del modelo de chat. Una pestaña de chat nueva es una buena prueba, ya que una pestaña antigua puede conservar el modelo con el que se inició. La guía paso a paso en cómo usar la API de Cursor muestra la misma configuración con más contexto.
Relaciona el error con la solución
| Lo que ves | Causa probable | Solución |
|---|---|---|
| 401, "clave no válida", "no autorizado" | Clave mal escrita, truncada o revocada | Cópiala de nuevo desde la página de claves; verifica espacios finales |
| 404, "no encontrado" | URL incorrecta, falta /v1, o una ruta duplicada | Usa exactamente https://api.cursorapikey.com/v1 |
| "modelo no encontrado" o similar | El nombre del modelo difiere de uncensored | Añade el modelo personalizado con ese nombre exacto, en minúsculas |
429 con rate_limited | Superado el límite de solicitudes por minuto | Ralentiza; las claves de prueba permiten 60 por minuto, las completas 300 |
429 con concurrency | Demasiadas peticiones a la vez | Reduce las ejecuciones de agentes en paralelo; prueba 2, clave completa 8 |
429 con Retry-After: 5 | Sobrecarga temporal | Espera cinco segundos y reintenta |
| Funciona en curl, falla en Cursor | Configuración no guardada, modelo de pestaña incorrecto o función que no usa claves personalizadas | Consulta la siguiente sección |
Las peticiones fallidas o rechazadas no se cobran, por lo que reintentar mientras depuras no cuesta nada.
Cuando curl funciona pero Cursor sigue fallando
Este es el caso más confuso y tiene varias explicaciones habituales.
Se ha seleccionado el modelo incorrecto. Cursor mantiene sus propios modelos integrados en la lista. Si uno de ellos está seleccionado, la petición no va a tu endpoint en absoluto. Selecciona explícitamente uncensored en el menú desplegable del chat o compositor que estés usando.
No todas las funciones usan tu clave. Las funciones que dependen de los propios modelos de Cursor, como el autocompletado en línea, pueden seguir usándolos independientemente de la clave que añadas. Las claves personalizadas se aplican donde puedes elegir el modelo, que son los modos de chat y edición. Consulta la documentación actual de Cursor, ya que esto cambia entre versiones.
Concurrencia desde el modo agente. Los agentes y las ejecuciones de múltiples pasos pueden disparar varias solicitudes a la vez. Una clave de prueba permite dos al mismo tiempo. Si los errores aparecen solo en el modo agente, es probable que estés alcanzando el límite de concurrency, y una clave completa lo eleva a ocho. Una solicitud en streaming mantiene su espacio hasta que termina el streaming, por lo que las salidas largas ocupan espacios por más tiempo.
Llamadas a funciones. La API admite llamadas a funciones, con tool_calls en streaming y los resultados pasados de vuelta como role: "tool". La calidad del uso de herramientas depende del modelo, así que si una ejecución de agente se atasca en un paso de herramienta, intenta la misma tarea en chat normal primero.
Verifica el lado de la cuenta
Si curl devuelve un error sobre el saldo, la clave es válida pero el crédito está vacío o la prueba ha finalizado. La prueba es de $0,50, válida por 7 días, se reclama con un clic en la página de la clave de API después del registro. Después necesitas una recarga.
Las recargas son cualquier cantidad entera desde $20 hasta $500, con +5% desde $50, +10% desde $100 y +15% desde $200. Puedes pagar con cripto (USDT en TRC20, USDC en Base). La página de precios muestra la tabla. Si aún no tienes una clave, consigue una aquí.
Mantén una clave por herramienta. Si has pegado una clave en varios editores y scripts, los límites de peticiones se comparten entre ellos, lo que puede parecer fallos aleatorios.
Verificación con script para un caso obstinado
Si aún no puedes encontrar la causa, ejecuta un script corto que replique lo que hace el editor. Usa el SDK de OpenAI, en el que se basan los clientes estilo Cursor, e imprime el objeto de error exacto.
from openai import OpenAI, APIStatusError
client = OpenAI(base_url="https://api.cursorapikey.com/v1", api_key="YOUR_KEY")
try:
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write a one-line Python hello world."}],
stream=True,
)
for chunk in r:
print(chunk.choices[0].delta.content or "", end="")
except APIStatusError as e:
print(e.status_code, e.response.headers.get("X-Request-Id"))
print(e.response.text)
Si el script transmite texto, el endpoint, la clave y el modelo son correctos, y el problema restante es una configuración de Cursor. Si imprime un código de estado, usa la tabla anterior. Mantén el valor X-Request-Id cuando contactes a soporte, ya que identifica la petición exacta. Los detalles completos de los parámetros están en la página de documentación.
Evita que vuelva a fallar
Algunos hábitos previenen la mayoría de los problemas recurrentes. Almacena la clave en una sola entrada del gestor de contraseñas y cópiala desde allí, en lugar de hacerlo desde registros de chat o notas donde los saltos de línea se colan. Escribe los tres valores (URL base, clave, nombre del modelo) para poder ingresarlos nuevamente después de una actualización del editor, ya que las actualizaciones a veces restablecen las anulaciones. Después de cada actualización, envía un mensaje de chat corto antes de comenzar el trabajo real.
Vigila el saldo. El encabezado X-Balance-USD se devuelve en cada respuesta, y también puedes leerlo desde GET /v1/balance. El crédito no caduca, por lo que una recarga modesta que permanezca en la cuenta no se desperdicia. Si usas la clave desde scripts además del editor, dale a los trabajos por lotes largos un bucle de reintento que espere cinco segundos en un 429 y se detenga después de unos intentos, para que un script no prive al editor de sus espacios de concurrencia.
Verificación de costos y qué leer a continuación
Una petición de chat de codificación con 10.000 tokens de contexto de archivo y una respuesta de 700 tokens cuesta 10.000 / 1.000.000 x $0,15 = $0,0015 para entrada y 700 / 1.000.000 x $0,50 = $0,00035 para salida, aproximadamente $0,00185 en total. Las tarifas son $0,15 por 1M de tokens de entrada y $0,50 por 1M de tokens de salida. El artículo sobre precios de la API de Cursor cubre estimaciones mensuales.
Si la petición que falló fue una grande, recuerda la ventana: prompt más completación deben caber en 100.000 tokens, y el cuerpo de la petición está limitado a 8 MB. Adjuntar un repositorio entero a un chat puede exceder ambos. Recorta el contexto a los archivos que importan y vuelve a intentarlo.
Más guías
Preguntas y respuestas
¿Por qué Cursor indica que mi clave de API no es válida?
Usualmente la clave tiene un espacio extra, se copió parcialmente o la URL base aún apunta a otro servicio. Vuelve a copiar la clave y luego confirma que la URL de anulación sea https://api.cursorapikey.com/v1.
¿Qué nombre de modelo debo ingresar?
Escribe uncensored, en minúsculas. Es el único ID de modelo que ofrece la API.
¿El autocompletado usa mi clave?
No necesariamente. Algunas funciones de Cursor utilizan los propios modelos de Cursor, y las claves personalizadas se aplican principalmente a los modos de chat y edición donde eliges el modelo.
¿Se facturan las peticiones fallidas?
No. Las peticiones fallidas o rechazadas no se cobran, por lo que reintentar mientras depuras no tiene costo.
Tu clave está a un formulario de distancia
Crea una cuenta, copia la clave, cambia la URL base. Esa es toda la configuración.