Documentacion de la API de Podhoc

Integra la generacion de podcasts en tus aplicaciones

Podhoc ofrece una API REST en Pro para generar audio a partir de URL. Google Cloud documenta una API en Preview para Audio Overviews de cuadernos y una API independiente de pódcast. La configuración, autenticación y los límites son distintos; consulta la documentación vigente antes de integrar.

API de audio de Google Cloud. Comparación revisada el 16 de septiembre de 2026.

Publicación por defecto: con tokens de producción, omitir auto_publish equivale a true: el pódcast generado puede ser público en Discover. Envía "auto_publish": false explícitamente para solicitar audio privado; la cuenta debe permitir controlar la publicación. Los tokens de prueba usan false por defecto y no pueden publicar automáticamente. Una fuente privada no hace privado el audio generado.

Cambio incompatible – ahora se valida style. Un style enviado explicitamente que no sea uno de los nueve identificadores canonicos devuelve ahora 400 INVALID_STYLE. Hasta este cambio, un valor no reconocido se aceptaba en silencio y se generaba como deep_dive. Versiones anteriores de esta pagina usaban "style": "conversational" en los ejemplos: conversational nunca fue un identificador real, asi que esas llamadas producian deep_dive desde siempre y el audio recibido no era el que la documentacion daba a entender. Cambia cualquier valor no reconocido por un identificador canonico. Omitir style, o enviar null o una cadena vacia, sigue usando deep_dive por defecto, asi que quien nunca fijo el campo no se ve afectado.

Fuentes de contenido: La API acepta solo URLs de acceso publico. La carga de archivos y el texto sin formato no estan soportados actualmente. Si su organizacion tiene requisitos de cumplimiento o seguridad que impiden el alojamiento publico, cree un ticket de soporte para discutir opciones de integracion empresarial.

Inicio rapido

1. Consigue una suscripcion PRO en app.podhoc.com
2. Crea un token de API en app.podhoc.com/account/api-access
3. Haz tu primera peticion usando los ejemplos de abajo

Autenticacion

Todas las peticiones a la API requieren una cabecera X-Api-Key con tu token:

X-Api-Key: phk_test_a1b2c3d4e5f6...

URL base: https://api-ext.podhoc.com/v1

Tipos de token:

• Tokens de prueba (phk_test_...) – Mas economico, funciones limitadas. Para desarrollo y pruebas.
• Tokens de produccion (phk_prod_...) – Mas costoso, acceso completo. Para uso en produccion.

Endpoints

POST /v1/podcasts – Crear un podcast

Inicia la generacion de un nuevo podcast a partir de una o mas fuentes.

Parametros de la peticion:

Nota: Solo se admiten URLs de acceso publico. La carga de archivos (file_ids) y el contenido de texto (text_content) no estan disponibles a traves de la API.

Identificadores validos de style – exactamente estos nueve y ninguno mas:

deep_dive, critique, didactic, debate, feynman_technique, simplified_explanation, pedagogical_framework, alchemist_formula, references_recall

Cualquier otro valor enviado explicitamente devuelve 400 INVALID_STYLE. Omitir el campo, o enviar null o una cadena vacia, usa deep_dive por defecto. Ademas, references_recall (Repaso de Referencias y Datos Clave) requiere un plan Creator o Pro: cualquier otro plan recibe 403 TIER_FEATURE_BLOCKED. Consulta la guia de estilos de audio para saber que produce cada uno.

Ejemplo de peticion:

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

Ejemplo de respuesta (202 Accepted):

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

GET /v1/podcasts/{id}/status – Consultar estado de generacion

Comprueba el progreso de un podcast en generacion.

curl https://api-ext.podhoc.com/v1/podcasts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status \
  -H "X-Api-Key: phk_test_..."

Valores de estado: requested, processing, completed, failed.

GET /v1/podcasts/{id}/download – Descargar podcast

Obtiene una URL de descarga prefirmada para un podcast completado. La URL caduca en 1 hora.

curl https://api-ext.podhoc.com/v1/podcasts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/download \
  -H "X-Api-Key: phk_test_..."

GET /v1/estimate-cost – Estimar coste en creditos

Previsualiza el coste en creditos antes de crear un podcast.

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

GET /v1/account/credits – Consultar saldo de creditos

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

Precios

La generacion de podcasts usa precios dinamicos basados en creditos. La API aplica un multiplicador adicional segun el tipo de token.

Formula:

Coste base:         max(30, ceil(duracion_minutos x 2.5))
Bonificaciones:     + 20 si mas de 1 fuente
                    + 10 si se habilitan pesos personalizados
Escalado de voces:  x 1.2 si mas de 1 voz
Limite:             min(500, coste_maximo_del_tier)
Coste API:          creditos_base x multiplicador_creditos

Ejemplos de coste por duracion (1 fuente, 1 voz, sin pesos personalizados):

Impacto de configuraciones avanzadas:

Multiplicadores de creditos:

Los multiplicadores de creditos (Mas economico para test, Mas costoso para produccion) son los niveles por defecto. Pueden ajustarse – el multiplicador real aplicado a tu solicitud se muestra en los metadatos de la respuesta.

Ejemplos de codigo

Python – flujo completo

import requests
import time

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

# Paso 1: Crear un podcast
resp = requests.post(f"{BASE}/podcasts", headers=HEADERS, json={
    "urls": ["https://example.com/article"],
    "language": "es",
    "target_duration_minutes": 10,
    "style": "deep_dive",
})
podcast_id = resp.json()["data"]["podcast_id"]

# Paso 2: Consultar hasta completar
while True:
    status_resp = requests.get(
        f"{BASE}/podcasts/{podcast_id}/status",
        headers={"X-Api-Key": API_KEY},
    )
    data = status_resp.json()["data"]
    if data["status"] == "completed":
        break
    if data["status"] == "failed":
        raise Exception("Fallo en la generacion")
    time.sleep(10)

# Paso 3: Descargar
dl_resp = requests.get(
    f"{BASE}/podcasts/{podcast_id}/download",
    headers={"X-Api-Key": API_KEY},
)
download_url = dl_resp.json()["data"]["download_url"]
audio = requests.get(download_url)
with open("podcast.mp3", "wb") as f:
    f.write(audio.content)

Limites de velocidad

Cuando se supera el limite, la respuesta incluye una cabecera Retry-After indicando cuando reintentar.

Codigos de error

Tokens de prueba vs produccion