Cómo generar pódcasts con la API de Podhoc: guía completa

Genera pódcasts con IA de forma programática con la API de Podhoc

Para generar un pódcast con la API de Podhoc, envía una petición POST a https://api-ext.podhoc.com/v1/podcasts con tu cabecera X-Api-Key, las URLs fuente, una duración objetivo entre 1 y 120 minutos y una configuración opcional de estilo y voces. El endpoint devuelve un podcast_id que consultas en /v1/podcasts/{id}/status hasta su finalización (normalmente 2-5 minutos), y luego llamas a /v1/podcasts/{id}/download para obtener una URL MP3 prefirmada válida durante una hora.

La API está diseñada para un único ciclo crear-consultar-descargar. No hay streams, ni callbacks, ni webhooks (todavía). La autenticación es una sola cabecera estática. Si alguna vez has llamado a una API REST, puedes integrar Podhoc en menos de una hora.

Para qué sirve la API

La API de Podhoc expone la misma canalización de generación que impulsa la aplicación web, reducida a un pequeño conjunto de primitivas:

• Creación programática de pódcasts desde URLs públicas.
• Estimación de costes antes de gastar créditos.
• Inspección de cuenta: saldo de créditos, historial de uso, nivel actual.
• Gestión del ciclo de vida: consulta de estado y descarga prefirmada.

La canalización detrás de esas primitivas es el mismo sistema de cinco etapas descrito en ¿Qué es un pódcast con IA?: ingesta, comprensión, reformateo para audio, elección de formato y síntesis de voz. La API simplemente lo hace programable.

Casos de uso comunes:

• Un producto SaaS que convierte URLs subidas por clientes en audio de incorporación.
• Una herramienta interna que transforma boletines semanales en episodios listos para el trayecto.
• Una plataforma de aprendizaje que genera automáticamente versiones en audio de los nuevos módulos del curso.
• Un flujo de investigación que sintetiza un conjunto de papers en una única sesión informativa de 30 minutos.

Para más, consulta Ideas de integración con la API.

Paso 1: provisiona un token

El acceso a la API está limitado al plan Pro (29 €/mes, 3500 créditos) y superiores. Una vez actualizada tu suscripción, ve a app.podhoc.com/account/api-access y crea un token.

Hay dos sabores:

• Tokens de prueba: prefijo phk_test_…, más baratos (multiplicador 1,5x), conjunto de funciones restringido. Úsalos durante el desarrollo y las pruebas de integración en CI.
• Tokens de producción: prefijo phk_prod_…, conjunto completo de funciones, multiplicador 2,5x.

Trata los tokens como contraseñas. Almacénalos en un gestor de secretos (AWS Secrets Manager, HashiCorp Vault, Doppler) y nunca los comprometas al control de código fuente. La API rechaza las peticiones con tokens filtrados o revocados con 401 UNAUTHORIZED.

La autenticación es una sola cabecera en cada petición:

X-Api-Key: phk_prod_a1b2c3d4e5f6...

La URL base es https://api-ext.podhoc.com/v1. Todos los endpoints devuelven JSON con un booleano success, un objeto data en éxito, un objeto error en fallo y un objeto meta con request_id y campos relacionados con créditos. El sobre se inspira en las mismas convenciones que siguen Anthropic y otros proveedores modernos de IA: estructura predecible, manejo de errores predecible.

Paso 2: estima el coste primero

Antes de llamar al endpoint de creación, pregunta a la API cuánto cobrará. El endpoint de estimación es gratuito y te permite implementar controles de gasto limpiamente.

curl "https://api-ext.podhoc.com/v1/estimate-cost?duration_minutes=30&source_count=2&voice_count=2" \
  -H "X-Api-Key: $PODHOC_API_KEY"

La respuesta desglosa el coste para que puedas aplicar tu propia lógica de políticas:

{
  "success": true,
  "data": {
    "base_credits": 114,
    "credit_multiplier": 1.5,
    "final_credits": 171,
    "breakdown": {
      "base_cost": 75,
      "multi_source_bonus": 20,
      "custom_weights_bonus": 0,
      "voice_multiplier": 1.2,
      "subtotal_before_cap": 114,
      "cap_applied": null,
      "tier_max_cost": 500
    },
    "formula": "max(30, ceil(30 x 2.5)) + 20 x 1.2 = 114 x multiplier = 171"
  }
}

La fórmula de precios tiene un tope de 500 créditos por petición, aplicado después de los multiplicadores de voz, las bonificaciones multifuente y las bonificaciones de pesos personalizados. Usa el desglose para mostrar a tus usuarios finales una vista previa “este episodio costará N créditos” antes de que confirmen.

También puedes consultar tu saldo en vivo:

curl https://api-ext.podhoc.com/v1/account/credits \
  -H "X-Api-Key: $PODHOC_API_KEY"

Paso 3: crea el pódcast

El endpoint de creación es el que realiza el trabajo y cobra créditos. La carga útil mínima es una lista de URLs:

curl -X POST https://api-ext.podhoc.com/v1/podcasts \
  -H "X-Api-Key: $PODHOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/article"],
    "language": "es",
    "target_duration_minutes": 15,
    "style": "deep_dive",
    "voice_config": { "voices": 2 }
  }'

La respuesta (HTTP 202 Accepted) te da el identificador que usarás para consultar:

{
  "success": true,
  "data": {
    "podcast_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "processing",
    "estimated_duration_minutes": 15,
    "credits_charged": 113
  },
  "meta": {
    "request_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "credits_charged": 113,
    "credit_balance": 3387
  }
}

El parámetro style es uno de los ocho formatos pedagógicos que admite Podhoc: deep_dive, didactic, feynman_technique, critique, debate, simplified_explanation, pedagogical_framework, alchemist_formula. Cada uno produce una salida notablemente distinta para la misma fuente. Consulta la guía de estilos de audio para saber cuándo elegir cada uno.

El parámetro language acepta cualquiera de los 74 códigos de idioma admitidos: en-US, es, fr, de, it, ca, ar, ru y otros 66. El idioma de origen y el de salida están desacoplados: pasa una URL en inglés con language: "es" y obtendrás un pódcast en español.

Paso 4: consulta el endpoint de estado

La generación es asíncrona. El podcast_id es tu identificador para el resto del ciclo de vida.

curl https://api-ext.podhoc.com/v1/podcasts/$PODCAST_ID/status \
  -H "X-Api-Key: $PODHOC_API_KEY"

El estado pasa por cuatro valores:

• requested: aceptado, en cola.
• processing: en ejecución.
• completed: listo para descargar.
• failed: error terminal; consulta los detalles de la respuesta.

Consulta cada 10 segundos con un pequeño retroceso. La mayoría de los pódcasts se completan en 2-5 minutos independientemente de la longitud de la fuente, porque la canalización paraleliza en GPUs en la nube. Un cliente razonable implementa la consulta con un tope estricto (15 minutos) y muestra una interfaz “en progreso” al usuario final.

Paso 5: descarga el MP3

El endpoint de descarga devuelve una URL prefirmada de S3 que expira en una hora:

curl https://api-ext.podhoc.com/v1/podcasts/$PODCAST_ID/download \
  -H "X-Api-Key: $PODHOC_API_KEY"

{
  "success": true,
  "data": {
    "download_url": "https://s3.amazonaws.com/...",
    "expires_at": "2026-05-06T11:00:00+00:00",
    "format": "mp3",
    "duration_seconds": 900
  }
}

Transmite la URL a tu propio almacenamiento. Si necesitas una referencia permanente, copia los bytes a tu bucket de S3 / GCS / Azure: la URL prefirmada es de corta duración, pero el audio que descargues vive para siempre en tu entorno.

Una integración completa en Python

Aquí tienes el mismo ciclo como un script ejecutable. Estima el coste, comprueba el saldo, crea, consulta y descarga. El manejo de errores es intencionalmente explícito para que veas dónde se aplica cada contrato de la API.

import os
import time

import requests

API_KEY = os.environ["PODHOC_API_KEY"]
BASE = "https://api-ext.podhoc.com/v1"
HEADERS = {"X-Api-Key": API_KEY, "Content-Type": "application/json"}


def estimate(duration: int, sources: int, voices: int) -> int:
    r = requests.get(
        f"{BASE}/estimate-cost",
        headers={"X-Api-Key": API_KEY},
        params={
            "duration_minutes": duration,
            "source_count": sources,
            "voice_count": voices,
        },
        timeout=15,
    )
    r.raise_for_status()
    return r.json()["data"]["final_credits"]


def balance() -> int:
    r = requests.get(f"{BASE}/account/credits", headers={"X-Api-Key": API_KEY}, timeout=15)
    r.raise_for_status()
    return r.json()["data"]["credits"]


def create(urls: list[str], duration: int, language: str, style: str) -> str:
    r = requests.post(
        f"{BASE}/podcasts",
        headers=HEADERS,
        json={
            "urls": urls,
            "language": language,
            "target_duration_minutes": duration,
            "style": style,
        },
        timeout=30,
    )
    r.raise_for_status()
    return r.json()["data"]["podcast_id"]


def wait_for(podcast_id: str, max_seconds: int = 900) -> None:
    started = time.time()
    while time.time() - started < max_seconds:
        r = requests.get(
            f"{BASE}/podcasts/{podcast_id}/status",
            headers={"X-Api-Key": API_KEY},
            timeout=15,
        )
        r.raise_for_status()
        status = r.json()["data"]["status"]
        if status == "completed":
            return
        if status == "failed":
            raise RuntimeError(f"Generation failed: {r.json()}")
        time.sleep(10)
    raise TimeoutError(f"Podcast {podcast_id} did not complete within {max_seconds}s")


def download(podcast_id: str, dest: str) -> None:
    r = requests.get(
        f"{BASE}/podcasts/{podcast_id}/download",
        headers={"X-Api-Key": API_KEY},
        timeout=15,
    )
    r.raise_for_status()
    audio = requests.get(r.json()["data"]["download_url"], timeout=60)
    audio.raise_for_status()
    with open(dest, "wb") as f:
        f.write(audio.content)


if __name__ == "__main__":
    cost = estimate(duration=15, sources=1, voices=2)
    if balance() < cost:
        raise SystemExit(f"Insufficient credits ({balance()} < {cost})")

    pid = create(
        urls=["https://example.com/article"],
        duration=15,
        language="es",
        style="deep_dive",
    )
    wait_for(pid)
    download(pid, "podcast.mp3")
    print(f"Saved podcast.mp3")

Un equivalente en Node.js usa el mismo flujo con fetch. Ambos están documentados en la referencia completa de la API.

Límites de tasa y cómo respetarlos

Alcanzar un límite devuelve HTTP 429 con cabecera Retry-After. Un cliente correcto respeta esa cabecera y encola el siguiente intento. Los límites de producción están calibrados para integraciones SaaS típicas — la mayoría de los equipos nunca se acercan. Si lo haces, habla con nosotros para una cuota empresarial.

La práctica estándar para endurecer cualquier cliente API se aplica aquí: pon un timeout a cada petición (15-30 segundos sobra), limita los reintentos (tres intentos con retroceso exponencial) y muestra los errores 5xx a tu operador en lugar de tragártelos. La RFC OAuth 2.1 es excesiva para una API de token estático como esta, pero su higiene operativa merece la pena: registra los IDs de petición (meta.request_id) en cada error para que soporte pueda correlacionar.

Lo que los tokens de prueba no pueden hacer

Los tokens de prueba están deliberadamente restringidos para que puedas integrar de forma barata sin gastar créditos de producción. En concreto:

• Duración máxima del episodio: 5 minutos.
• Idiomas permitidos: solo inglés (en-US, en).
• URLs por petición: 1.
• Voces máximas: 2.
• custom_focus, source_weights y auto_publish: no disponibles.

Cualquier intento devuelve 400 TEST_TOKEN_RESTRICTED. Cambia a un token de producción (dentro de la misma cuenta Pro) cuando estés listo para enviar a producción.

Webhooks, cargas de archivos y lo que aún no es compatible

Algunas funciones que existen en la aplicación web no están en la API hoy:

• Cargas de archivos. Puedes pasar URLs pero no bytes PDF / DOCX / TXT en bruto. Si tu contenido está detrás de autenticación, hospédalo públicamente con una URL firmada o contáctanos para una ruta empresarial.
• Cuerpos de texto en bruto. El parámetro urls es el único mecanismo de ingesta; no puedes enviar un campo text_content.
• Webhooks / callbacks. Los cambios de estado se observan mediante consulta. Una capa de webhook está en nuestro roadmap; por ahora, un bucle de consulta de 10 segundos es el patrón recomendado.

Estas brechas son intencionales: la API se lanza con una superficie mínima viable y la ampliaremos a medida que se estabilicen los patrones de integración.

Qué construir a continuación

Una vez funcione tu primera integración, el siguiente paso natural es adoptar la API en una superficie de producto real. Algunos puntos de partida:

• Combina la API con un bot de Telegram para que tus usuarios disparen la generación desde el chat.
• Combina la creación de pódcasts con nuestros ocho estilos de audio para que tus usuarios elijan el tratamiento pedagógico por fuente.
• Impulsa flujos de PDF a pódcast hospedando el PDF públicamente primero y pasando luego la URL.
• Lee Ideas de integración con la API para patrones concretos que hemos visto a equipos enviar con la API en los primeros 30 días.

El objetivo de la API es sacar Podhoc del navegador y meterlo en tu producto. El ciclo de cinco pasos es pequeño a propósito. Construye el envoltorio fino, prueba contra tus propias URLs e itera.

Provisiona un token de API →