Documentacion de la API de Podhoc

Integra la generacion de podcasts en tus aplicaciones

La API de Podhoc te permite crear podcasts generados por IA de forma programatica a partir de URLs de acceso publico. Integra la generacion de podcasts en tus flujos de trabajo, aplicaciones y plataformas.

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.

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": "conversational"
  }'

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": "conversational",
})
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