Una clave API de Perplexity es la credencial que envías con cada solicitud a api.perplexity.ai. Identifica tu proyecto, reduce tu saldo de crédito prepago y establece tu nivel de límite de velocidad. Si nunca has manejado una antes, nuestra guía introductoria sobre qué es una clave API cubre lo básico. Esta guía cubre la parte específica de Perplexity: crear la cuenta, añadir créditos, generar la clave y enviar tu primera solicitud Sonar basada en datos desde curl, Python y Apidog.
Una nota sobre los tiempos antes de empezar. Perplexity movió Sonar a su API de Agente, y el inicio rápido oficial ahora apunta allí. El antiguo endpoint de Sonar para completaciones de chat seguirá funcionando hasta el 27 de septiembre de 2026, luego se retirará. Cada ejemplo a continuación utiliza el endpoint actual, con una breve nota sobre el formato heredado en caso de que estés manteniendo código antiguo.
Lo que necesitas antes de empezar
- Una cuenta de Perplexity. Google, Apple, SSO o un inicio de sesión por correo electrónico sin contraseña funcionan, y se resuelven a la misma cuenta por dirección de correo electrónico.
- Una tarjeta de pago. La API es de pago por uso sin suscripción, pero las solicitudes fallan una vez que tu saldo de crédito llega a cero.
- curl o Python 3.9+ para la primera solicitud.
- Apidog si deseas que la clave se almacene como un secreto local y la solicitud se guarde como una prueba repetible.
Paso 1: inicia sesión en la consola de la API y crea un proyecto
Ve a console.perplexity.ai y elige un método de inicio de sesión. Iniciar sesión crea una cuenta de Perplexity, pero no un proyecto de API. En tu primera visita, el asistente de configuración te pedirá que crees o te unas a un proyecto antes de que puedas generar una clave, porque las claves están limitadas a proyectos.
Abre Configuración en la barra lateral izquierda y completa el nombre, la dirección y los detalles fiscales de tu organización; aparecerán en tus facturas. Si tu empresa ya tiene un proyecto, pídele a un administrador que te agregue a él en lugar de crear uno segundo. Los proyectos separados tienen saldos de crédito y claves separadas, lo cual es útil para aislar una aplicación de producción de un experimento.
Paso 2: añade un método de pago y créditos
Abre la página de Facturación y añade una tarjeta. Según la documentación, añadir un método de pago no carga la tarjeta; almacena los detalles para uso futuro. Luego compra créditos. El saldo, los desgloses de uso por modelo y el historial de facturas se encuentran en esta página.
Dos detalles importan aquí. La API factura a partir de créditos prepagos, y si el saldo se agota, tus claves se bloquean hasta que recargues. La documentación describe ese fallo como un 401, no un 402, por lo que una aplicación sin créditos parece un error de autenticación a primera vista. Y junto a Recarga automática, haz clic en Cambiar preferencias para que la consola añada créditos automáticamente cuando el saldo caiga por debajo de un umbral que establezcas. Activa esto antes de que algo pase a producción.
La documentación no publica una cantidad mínima de compra, así que guíate por lo que te muestra la página de facturación. Tu nivel de uso, que establece tus límites de velocidad, se basa en los créditos acumulados comprados a lo largo de la vida de la cuenta, no en el saldo actual.
Paso 3: genera la clave API
Abre la página de Claves API en la consola y crea una clave. Dale un nombre descriptivo como dev-laptop o prod-search-worker. Después de la creación, el nombre es la única forma de distinguir las claves, porque el valor completo se muestra una vez y no se puede recuperar de nuevo. Cópialo de inmediato.
Coloca la clave en una variable de entorno, nunca en el código:
export PERPLEXITY_API_KEY="pplx-your-key-here"
En Windows, usa setx PERPLEXITY_API_KEY "pplx-your-key-here" y abre una nueva terminal.
Puedes crear varias claves dentro de un proyecto, así que crea una por entorno y por servicio. Revocar una clave es permanente, que es lo que quieres cuando una clave se filtra. Si no estás seguro de si una clave ya se ha filtrado en un repositorio, ejecuta un escáner de secretos sobre tu historial de git antes de rotarla.
Paso 4: haz tu primera solicitud Sonar
El endpoint actual es POST https://api.perplexity.ai/v1/agent. La autenticación es una cabecera de portador estándar, Authorization: Bearer $PERPLEXITY_API_KEY. El cuerpo toma un model y una cadena input. El ID de modelo de Sonar en este endpoint es perplexity/sonar, y añadir la herramienta web_search le indica que busque en la web en vivo y adjunte las fuentes.
Pregúntale algo con una respuesta real que cambie con el tiempo:
curl https://api.perplexity.ai/v1/agent \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "perplexity/sonar",
"input": "Which Node.js release line is currently Active LTS, and when does it reach end of life?",
"tools": [{ "type": "web_search" }]
}' | jq
La respuesta contiene output_text, la respuesta como texto plano, y un array output con un elemento por cada paso que tomó el modelo. El elemento message contiene la respuesta; el elemento search_results lista las páginas que leyó, cada una con una url, title, snippet y date. El objeto usage informa los recuentos de tokens y el costo. Un status de completed significa que la ejecución finalizó.
La misma solicitud en Python con el SDK oficial:
pip install perplexityai
from perplexity import Perplexity
client = Perplexity() # reads PERPLEXITY_API_KEY from the environment
response = client.responses.create(
model="perplexity/sonar",
input="Which Node.js release line is currently Active LTS, and when does it reach end of life?",
tools=[{"type": "web_search"}],
)
print(response.output_text)
Si prefieres el SDK de OpenAI, configura base_url="https://api.perplexity.ai/v1" y llama a client.responses.create() con los mismos argumentos. El SDK lo enruta a /v1/responses, que Perplexity acepta como un alias. Los preajustes (fast, low, medium, high, xhigh) agrupan un modelo, presupuestos de tokens y herramientas para ti; en el SDK de OpenAI los pasas a través de extra_body.
Si estás en el formato heredado de completaciones de chat
El código antiguo envía messages a https://api.perplexity.ai/v1/sonar con los IDs de modelo sonar, sonar-pro, sonar-reasoning-pro o sonar-deep-research, y lee choices[0].message.content. Ese formato funciona hasta el 27 de septiembre de 2026. La guía de migración mapea sonar a perplexity/sonar, sonar-pro a perplexity/sonar con el preajuste low, y la investigación profunda al preajuste high. Las opciones search_domain_filter y search_recency_filter se mueven dentro de la herramienta web_search como un objeto filters.
Paso 5: guarda la clave y la solicitud en Apidog
Un curl que funciona una vez no es una prueba. Aquí tienes la configuración que usamos en Apidog para que la clave no salga de la nube y la solicitud se ejecute bajo demanda.
Crea un entorno. Añade un entorno llamado Perplexity con dos variables: base_url configurada como https://api.perplexity.ai como valor compartido, y PERPLEXITY_API_KEY con el valor compartido como marcador de posición y la clave real solo en el valor local. Los valores locales residen en la caché de tu cliente y nunca se sincronizan con tus compañeros de equipo, que es el objetivo principal. Nuestra guía sobre entornos y variables secretas en Apidog profundiza en la división entre valores compartidos y locales.
Construye la solicitud. Nueva solicitud, POST {{base_url}}/v1/agent. Añade una cabecera Authorization: Bearer {{PERPLEXITY_API_KEY}}, establece el tipo de cuerpo en JSON y pega el mismo cuerpo que el curl anterior. Selecciona el entorno Perplexity y haz clic en Enviar. Deberías ver el output_text y el bloque search_results en el panel de respuesta.
Conviértelo en una prueba. Añade tres aserciones: el código de estado es 200, $.status es igual a completed, y $.output_text no está vacío. Guarda la solicitud en un escenario de prueba. Ahora cualquiera en el equipo puede obtener el proyecto, pegar su propia clave en el valor local y verificar su configuración con un solo clic. Rotar la clave significa editar un campo, no buscar en scripts.
Si aún no lo tienes, Descarga Apidog gratis; el plan gratuito cubre a cuatro usuarios, suficiente para que un equipo pequeño comparta el proyecto.
Límites de velocidad y costo de una solicitud
Los límites de velocidad en la API de Agente escalan con tu nivel de uso, y los niveles se establecen por las compras de crédito de por vida, según la página de límites de velocidad:
| Nivel | Créditos comprados | Solicitudes por segundo | Solicitudes por minuto |
|---|---|---|---|
| 0 | $0 | 1 | 50 |
| 1 | $50+ | 3 | 150 |
| 2 | $250+ | 8 | 500 |
| 3 | $500+ | 17 | 1.000 |
| 4 | $1.000+ | 33 | 4.000 |
| 5 | $5.000+ | 33 | 8.000 |
Los límites utilizan un algoritmo de "cubo con fugas" (leaky-bucket), por lo que ráfagas cortas hasta el límite pasan. Cuando lo superas, la API devuelve un 429 con una cabecera Retry-After, y las solicitudes rechazadas no se facturan. Tu nivel actual se muestra en la página de Precios de la consola, en la pestaña de niveles de uso.
En cuanto a los precios, un párrafo es suficiente aquí. La página de precios lista perplexity/sonar en la API de Agente a $0.25 por millón de tokens de entrada y $2.50 por millón de tokens de salida, más $0.0025 por invocación de web_search. Los modelos heredados de completaciones de chat de Sonar facturan de manera diferente: sonar a $1 por millón de tokens de entrada y salida, más $5 a $12 por cada mil solicitudes dependiendo del tamaño del contexto de búsqueda. Para un desglose completo y la perspectiva de la cuenta Pro, consulta nuestra guía de la API de Perplexity.
Errores comunes y cómo solucionarlos
401 No autorizado. Tres causas, en orden de probabilidad: la cabecera es incorrecta (debe ser Authorization: Bearer <key>, y la variable de entorno debe exportarse en la misma terminal), la clave fue revocada, o el saldo de crédito está a cero. Revisa la página de facturación antes de regenerar algo. El SDK de Python lanza AuthenticationError para esto.
400 Solicitud incorrecta. Normalmente un cuerpo en formato antiguo enviado al nuevo endpoint: messages en lugar de input, o un ID de modelo sonar-pro simple en /v1/agent. El SDK lo muestra como ValidationError.
404 No encontrado. La ruta es incorrecta. /v1/agent es la API de Agente y /v1/sonar es el endpoint heredado de completaciones de chat; la documentación no lista nada más.
429 Demasiadas solicitudes. Alcanzaste el límite de tu nivel. Lee Retry-After, espera ese tiempo, luego reintenta con retroceso exponencial y fluctuación. Comprar créditos eleva tu nivel si necesitas un rendimiento sostenido. La guía de manejo de errores del SDK muestra el patrón RateLimitError.
500 o 503. Lado del servidor. Reintenta con un retraso; los bucles de reintento ajustados empeoran la limitación de velocidad.
Preguntas frecuentes
¿Existe una clave API de Perplexity gratuita?
No se documenta ningún nivel gratuito. La API es de pago por uso a partir de un saldo de crédito prepago, y un proyecto sin créditos se bloquea. El costo de una primera solicitud con perplexity/sonar y una búsqueda web es una fracción de un centavo, por lo que una pequeña recarga cubre muchas pruebas.
¿Qué ID de modelo debo usar para una primera solicitud?
Usa perplexity/sonar en /v1/agent con la herramienta web_search. Es la opción más económica basada en datos y la que la guía de migración mapea los antiguos IDs sonar y sonar-pro. Cambia a un preajuste como low o medium cuando quieras que Perplexity elija el modelo y el presupuesto de búsqueda por ti.
¿Necesito la API de Agente si solo quiero resultados de búsqueda?
No. La API de Búsqueda separada devuelve resultados clasificados sin ejecutar un modelo, lo cual es más barato cuando estás alimentando páginas en tu propio pipeline. Nuestro recorrido por la API de Búsqueda de Perplexity muestra la forma de la solicitud y los filtros.
¿Cómo roto una clave sin tiempo de inactividad?
Crea una segunda clave en el mismo proyecto, despliégala donde se usaba la antigua, confirma el tráfico en la nueva clave, luego revoca la antigua. La revocación es permanente, así que actualiza cada consumidor primero. Perplexity también expone los endpoints /generate_auth_token y /revoke_auth_token si quieres automatizar la rotación.
Conclusión
Inicia sesión, crea un proyecto, compra créditos, genera una clave, envía una solicitud a /v1/agent con perplexity/sonar. Ese es todo el camino. Guarda la clave como un valor local en Apidog y la solicitud como una prueba, y la siguiente persona de tu equipo obtendrá una configuración verificable en minutos. Si aún tienes código en el endpoint de completaciones de chat, migra antes del 27 de septiembre de 2026.