API de Perplexity AI: acceso, precios, integración y guía de producción

API de Perplexity AI: acceso, precios, integración y guía de producción

Última verificación con la documentación de Perplexity: 24 de octubre de 2026.

La API de Perplexity AI ya no es una única e indiferenciada «API de búsqueda-chat». Ahora cuenta con superficies distintas para respuestas de agentes basadas en la web, enrutamiento de modelos de pesos abiertos, búsqueda sin procesar, embeddings y decisiones tipadas. Elija la superficie que se ajuste al trabajo antes de escribir código: determina el endpoint, el método del SDK, la unidad de precio, el límite de velocidad y lo que debe registrar en producción.

Para la mayoría de las nuevas funciones de investigación o asistencia, comience con la API de Agent. Sigue el formato OpenAI Responses, puede usar búsqueda web y devuelve resultados estructurados con fuentes. Use la API de Orchestrator cuando su código existente de OpenAI Chat Completions necesite acceso a su catálogo de modelos de pesos abiertos. Use Search cuando necesite resultados clasificados sin una respuesta de LLM.

La respuesta corta: ¿qué API de Perplexity debería usar?

Esa distinción es la decisión de diseño más importante de la API de Perplexity AI. La descripción general actual de Perplexity presenta la API de Agent como una API basada en la web y compatible con OpenAI Responses; su API de Orchestrator es una superficie de compatibilidad independiente para modelos alojados de pesos abiertos. Lea la descripción general de Perplexity.

Obtenga acceso a la API de Perplexity AI

1. Cree una cuenta en la Consola de API de Perplexity.
2. Genere una clave desde la página API Keys.
3. Guárdela únicamente en el servidor o en el administrador de secretos de su despliegue.
4. Configure PERPLEXITY_API_KEY en el entorno de ejecución, no en código del navegador, git, ejemplos ni registros.
5. Añada la facturación antes de enviar tráfico de producción. Perplexity documenta la facturación de API de pago por uso sin requisito de suscripción; consulte la página de precios actual antes del lanzamiento, ya que las tarifas de modelos y herramientas pueden cambiar.

En macOS o Linux, configure el secreto sin imprimirlo:

export PERPLEXITY_API_KEY="replace-in-your-secret-manager"
test -n "$PERPLEXITY_API_KEY" && echo "PERPLEXITY_API_KEY is set"

El comando final confirma deliberadamente la presencia sin exponer el valor. Perplexity aconseja explícitamente no imprimir claves ni siquiera fragmentos de claves en la salida de la terminal. Para el resto de su aplicación, siga la misma regla: oculte los encabezados Authorization, rote las claves comprometidas y asigne a cada entorno su propia credencial. Combine esto con un flujo de trabajo de gestión segura de claves API antes de añadir tráfico de clientes.

Integre la API de Agent con el SDK de OpenAI

La API de Agent es la superficie adecuada de la API de Perplexity AI cuando su producto necesita una respuesta basada en la web, citas, uso de herramientas o una respuesta que pueda continuar entre turnos. Perplexity documenta la configuración del SDK de OpenAI como base_url="https://api.perplexity.ai/v1", mediante client.responses.create().

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PERPLEXITY_API_KEY"],
    base_url="https://api.perplexity.ai/v1",
)

response = client.responses.create(
    model="perplexity/sonar",
    input="What changed in the last 30 days for this topic? Cite primary sources.",
    tools=[{"type": "web_search"}],
    max_output_tokens=600,
)

print(response.output_text)

El endpoint canónico es POST /v1/agent; el SDK de OpenAI envía POST /v1/responses, que Perplexity acepta como alias. Esto es compatible en la capa de Responses, no una promesa de que todas las opciones de Chat Completions se asignen limpiamente. La guía de compatibilidad con OpenAI de Perplexity es la fuente de referencia para los campos de solicitud y respuesta compatibles.

Dos detalles de producción son importantes aquí:

• La búsqueda web es opcional. Una solicitud con solo model e input usa el conocimiento del modelo y no devuelve citas; use un nivel de esfuerzo o una herramienta web_search cuando la actualidad y las fuentes sean importantes.
• Mantenga la estructura output, no solo output_text, en el límite de su aplicación. Las citas, la actividad de herramientas, el estado, el uso y el ID de respuesta son datos operativos, no decoración para la interfaz de usuario.

Antes de codificar de forma fija un identificador de modelo, consulta GET /v1/models en tu flujo de despliegue o revisa el catálogo actual de modelos de la Agent API. Perplexity documenta ese endpoint en un formato compatible con OpenAI, lo que lo hace útil para listas de permitidos y comprobaciones de lanzamiento.

Usa la Orchestrator API cuando necesites compatibilidad con Chat Completions

La API de Perplexity AI tiene una segunda vía compatible con OpenAI para una tarea diferente. La Orchestrator API utiliza el formato de Chat Completions y una URL base distinta:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PERPLEXITY_API_KEY"],
    base_url="https://api.perplexity.ai/orchestrator/v1",
)

completion = client.chat.completions.create(
    model=os.environ["PPLX_ORCHESTRATOR_MODEL"],
    max_tokens=500,
    messages=[
        {"role": "user", "content": "Summarize these notes in five bullets."}
    ],
)

print(completion.choices[0].message.content)

Usa una variable de entorno para el ID del modelo y valídala en CI o en una comprobación de lanzamiento. La disponibilidad del catálogo, los alias y las tablas de precios cambian con más frecuencia de la que debería cambiar el código de tu aplicación. El error clave que debes evitar es tratar la Agent API y la Orchestrator API como si fueran intercambiables:

• Agent API: https://api.perplexity.ai/v1 + responses.create().
• Orchestrator API: https://api.perplexity.ai/orchestrator/v1 + chat.completions.create().

Si tu objetivo es obtener una respuesta actual y con citas, no cambies a Chat Completions simplemente porque ese cliente te resulta familiar. Si tu objetivo es una migración directa de OpenAI Chat Completions para el catálogo alojado de modelos de pesos abiertos, no lo dirijas a la URL base de Agent. La guía de inicio rápido de Perplexity muestra ambos patrones.

Precios de la API de Perplexity AI: calcula la solicitud completa

La forma práctica de presupuestar la API de Perplexity AI es separar los cargos por tokens de los cargos por herramientas o solicitudes. La tabla de tarifas exacta está activa y es específica de cada modelo, así que utiliza la página de precios como un dato de entrada para el despliegue, no como una cifra que copias en una diapositiva una vez por trimestre.

Las tarifas anteriores se comprobaron el 24 de octubre de 2026. La página oficial de precios y el catálogo de modelos de Agent API deben revisarse de nuevo antes de establecer un margen, una cuota de cliente o una alerta de presupuesto.

Una fórmula útil para la planificación es:

request_cost =
  (input_tokens / 1,000,000 × input_rate) +
  (output_tokens / 1,000,000 × output_rate) +
  (cache_read_tokens / 1,000,000 × cache_read_rate) +
  tool_invocations × tool_rate +
  search_requests × search_request_rate

No calcules el coste de una respuesta investigada únicamente a partir de los tokens de salida. Los flujos de trabajo de Agent pueden utilizar contexto de entrada, tokens de salida/razonamiento y llamadas a herramientas. Almacena cada una de esas dimensiones junto con tu ID de tenant, nombre de funcionalidad, modelo solicitado, modelo final e ID de respuesta. Ese mismo modelo de eventos hace que las comparaciones de precios de modelos de IA sean mucho más significativas que comparar únicamente los precios de lista.

Crea un flujo de trabajo de API de Perplexity AI listo para producción

1. Haz que la superficie de la API sea una decisión explícita de producto

Define un adaptador pequeño para cada superficie, como perplexity_agent, perplexity_search y perplexity_orchestrator. No ocultes sus diferentes tipos de respuesta detrás de una función chat() genérica hasta que hayas decidido qué ocurre con las citas, los resultados de búsqueda, el uso y los eventos de herramientas.

Para una respuesta de investigación orientada al cliente, tu adaptador debería devolver al menos:

answer_text, citations, response_id, status, requested_model,
served_model, input_tokens, output_tokens, tool_calls, cost, latency_ms

Para Search sin procesar, devuelve los resultados por separado de cualquier síntesis posterior. Esto preserva la procedencia y permite cambiar el modelo de redacción sin cambiar silenciosamente el proveedor de búsqueda.

2. Trata las citas como datos que debes preservar

Cuando tu solicitud a la API de Perplexity AI utiliza búsqueda web, muestra las fuentes citadas junto a la afirmación que respaldan. Guarda la URL de la fuente devuelta, el título cuando se proporcione y el ID de respuesta utilizado para crear la respuesta. Una respuesta amable sin fuentes inspeccionables no es suficiente para una función de investigación, un agente de soporte o un flujo de trabajo interno de toma de decisiones.

Decide tu política antes del lanzamiento:

• ¿Exiges al menos una fuente primaria para una respuesta factual?
• ¿Eliminarás una afirmación cuando ninguna cita la respalde?
• ¿Puede un usuario abrir la URL citada antes de actuar según la respuesta?
• ¿Durante cuánto tiempo conservas los metadatos de las fuentes y los registros de respuestas?

3. Presupuesta para ventanas de límites móviles, no para una única cifra de «solicitudes por minuto»

La API de Agent de Perplexity documenta un límite de solicitudes para toda la organización, compartido entre llamadas de Agent, sondeos, operaciones de cancelación/reanudación y descargas de archivos. También documenta límites de tokens por modelo en ventanas móviles de minutos y horas. El sondeo no es gratuito: en un nivel bajo, sondear una solicitud asíncrona una vez por segundo puede consumir toda la cuota de solicitudes.

Para las respuestas 429, respeta Retry-After. Para errores overloaded relacionados con la capacidad, aplica una espera exponencial con aleatorización y usa una lista de respaldo documentada solo cuando el producto pueda aceptar de forma segura un modelo diferente. No reintentes errores de autenticación, validación o configuración de cuota como si fueran transitorios. Consulta la guía sobre límites de tasa y niveles de uso de Perplexity para conocer los umbrales actuales y la semántica de las respuestas.

Pseudocódigo para una política de reintentos limitada:

for attempt in range(3):
    try:
        return call_perplexity()
    except RateLimitError as error:
        wait_seconds = retry_after_or_jittered_backoff(error, attempt)
        sleep(wait_seconds)
    except TransientCapacityError:
        sleep(jittered_backoff(attempt))

raise ServiceTemporarilyUnavailable()

Mantén bajo el número de reintentos, utiliza una fecha límite de extremo a extremo y haz visible el estado de respaldo para quien llama. Los reintentos que convierten una solicitud de investigación lenta en un indicador de carga de 90 segundos no son fiabilidad.

4. Registra lo suficiente para depurar conjuntamente el coste, la calidad y la actualidad

Realiza un seguimiento del ID de solicitud, la familia de endpoints, el modelo, el nivel de esfuerzo, la lista de herramientas, el tiempo hasta el primer token, el tiempo de finalización, las dimensiones de tokens, el número de llamadas a herramientas, el estado HTTP, el número de reintentos y una clasificación segura de errores. Para las respuestas con citas, realiza un seguimiento del número de citas y los dominios de las fuentes. Para Search, realiza un seguimiento del número de consultas y de resultados.

Esto te proporciona la evidencia para responder preguntas como: «¿Aumentó la latencia porque habilitamos la búsqueda?», «¿Qué tenant está gastando en sesiones de sandbox?» y «¿Un respaldo mejoró la disponibilidad pero redujo la cobertura de citas?». Para una arquitectura más general, consulta la guía de gateway de API de IA y la guía sobre límites de tasa de LLM.

5. Planifica una migración de Sonar si tienes código heredado

La guía de migración actual de Perplexity indica que la compatibilidad con Sonar Chat Completions finalizó el 27 de septiembre de 2026. Recomienda la API de Agent para proyectos nuevos; las solicitudes heredadas síncronas y de streaming se están reformulando gradualmente, mientras que las solicitudes asíncronas de Sonar ya no son compatibles. Si todavía llamas a un endpoint de Sonar, prueba ahora un adaptador para la API de Agent en lugar de descubrir una interrupción asíncrona en producción. Lee la guía de migración.

¿API de Perplexity directa o un gateway multimodelo independiente?

Utiliza una integración directa con la API de Perplexity AI cuando la función dependa de Agent, Search, citas, niveles de esfuerzo o comportamiento de API específicos de Perplexity. Así se mantiene claro el contrato de producción.

Utiliza un gateway multimodelo independiente solo para los modelos y endpoints que ese gateway enumere actualmente como compatibles. Por ejemplo, Flatkey documenta una URL base compatible con OpenAI en https://router.flatkey.ai/v1 para su catálogo compatible y un panel de uso por solicitud. Su directorio público de modelos debe comprobarse en tiempo real antes de asumir que un proveedor o modelo está disponible. Comienza con la guía de inicio rápido de la API de Flatkey.

Para los equipos que necesitan ambos, utiliza dos clientes explícitos:

No enrutes un endpoint directo de Perplexity a través de otro servicio a menos que su documentación actual admita explícitamente esa ruta. El objetivo no es forzar todas las llamadas a través de una capa; es preservar la capacidad y el comportamiento de facturación de los que realmente depende tu función.

Lista de verificación para el lanzamiento en producción

• [ ] Cada funcionalidad ha seleccionado intencionadamente Agent, Orchestrator, Search, Embeddings o Decisions.
• [ ] Las claves de API están del lado del servidor, tienen un ámbito definido por entorno y no están presentes en los paquetes de cliente ni en los registros.
• [ ] La URL base de Agent (/v1) y la URL base de Orchestrator (/orchestrator/v1) no se confunden.
• [ ] Los ID de modelo y las tarjetas de precios vigentes se validan en una comprobación de lanzamiento.
• [ ] La búsqueda web se habilita explícitamente solo cuando la actualidad de las citas es útil.
• [ ] Las respuestas con citas conservan los metadatos de las fuentes y un ID de respuesta.
• [ ] Los eventos de coste incluyen dimensiones de tokens y recuentos de invocaciones de herramientas o búsquedas.
• [ ] 429 respeta Retry-After; los fallos transitorios de capacidad usan una espera exponencial limitada con jitter.
• [ ] El sondeo reduce su frecuencia o se sustituye por un comportamiento de streaming/reconexión.
• [ ] Una prueba por fases cubre la calidad de las fuentes, la latencia, el coste, el comportamiento de reintentos y las alternativas visibles para el usuario.

Preguntas frecuentes sobre la API de Perplexity AI

¿La API de Perplexity AI es compatible con el SDK de OpenAI?

Sí, pero elige la estructura de API correspondiente. La API de Agent utiliza el formato OpenAI Responses en https://api.perplexity.ai/v1; la API de Orchestrator utiliza Chat Completions en https://api.perplexity.ai/orchestrator/v1.

¿Cada solicitud a la API de Agent busca en la web e incluye citas?

No. Perplexity documenta la búsqueda web como opcional. Añade un nivel de esfuerzo o la herramienta web_search cuando necesites resultados basados en la web; conserva la salida estructurada para que tu aplicación pueda mostrar y auditar las citas.

¿Cuánto cuesta la API de Perplexity AI?

Depende de la superficie de API seleccionada, el modelo, el uso de tokens, las lecturas de caché, los tokens de razonamiento y las herramientas. Utiliza la tarjeta de tarifas oficial vigente y mide el uso real de las solicitudes. Una solicitud de agente con búsqueda habilitada tiene componentes de coste tanto de tokens del modelo como de herramientas.

¿Qué debo hacer después de un error de límite de tasa?

Respeta Retry-After, modera las nuevas solicitudes y utiliza una espera exponencial limitada con jitter. No realices sondeos agresivos; los sondeos de la API de Agent cuentan para el límite de solicitudes compartido de la organización.

Siguiente paso

Empieza con un caso de uso de producción específico: una respuesta de investigación con citas, una funcionalidad de búsqueda sin procesar o una llamada a un modelo compatible con Chat Completions. Instrumenta su seguimiento antes de ampliar el tráfico. Si el resto de tu aplicación también necesita modelos compatibles detrás de un único cliente compatible con OpenAI, explora el catálogo de modelos de Flatkey y mantén explícito el límite de su cliente.