Skip to main content

API de Podhoc: crea pódcasts privados desde URL

Usa la API Pro de Podhoc con estimaciones de créditos, reintentos seguros, resultados privados y límites claros. Incluye peticiones y contrato OpenAPI.

Acceso y coste

Para crear o rotar tokens de prueba o producción necesitas Pro activo o en prueba. Los tokens de prueba gastan créditos reales; no es un entorno gratuito. Guarda las claves en el servidor, fuera del navegador, URL, registros y repositorios.

Las fuentes deben ser URL públicas compatibles. La API no acepta archivos subidos ni texto pegado. No publiques documentos confidenciales para usarla.

Pro · API tokens

X-Api-Key: phk_test_… / X-Api-Key: phk_prod_…

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

Primera petición segura

El ejemplo usa una fuente pública ficticia. Genera audio y gasta créditos: consulta saldo y estimación y aprueba un presupuesto. Cinco minutos con una voz cuestan 72 créditos con el multiplicador de prueba predeterminado; usa la estimación recibida si cambia la configuración.

export PODHOC_API_KEY='phk_test_REPLACE_LOCALLY'
export PODHOC_IDEMPOTENCY_KEY='REPLACE_WITH_A_NEW_UUID'

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

curl --fail-with-body 'https://api-ext.podhoc.com/v1/estimate-cost?duration_minutes=5&source_count=1&voice_count=1' \
  -H "X-Api-Key: $PODHOC_API_KEY"

Guarda un Idempotency-Key nuevo para cada generación deseada antes de enviar. Si la respuesta es incierta, repite la misma clave y contenido. Se devuelve el recibo original; cambiar el contenido con esa clave da 409. Un timeout no justifica inventar otra clave.

sleep 60
curl --fail-with-body 'https://api-ext.podhoc.com/v1/podcasts' \
  -H "X-Api-Key: $PODHOC_API_KEY" \
  -H "Idempotency-Key: $PODHOC_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"urls":["https://podhoc.com/integrations/ai-agents/example-source/"],"language":"en","auto_publish":false,"target_duration_minutes":5,"style":"deep_dive","max_credits":72,"voice_config":{"voice_count":1,"voices":{"speaker1":"Kore"}}}'

Límites y precios

Prueba: 2 peticiones/minuto, 20/hora, 1 generación simultánea, hasta 5 minutos, 1 URL e inglés. Producción: 30/minuto, 300/hora y 5 generaciones simultáneas, según límites Pro. Respeta Retry-After ante 429.

Base: max(36, ceil(minutos × 10 / 3)). Varias fuentes añaden 27 créditos; pesos personalizados, 13; varias voces estándar multiplican el subtotal por 1,2, con redondeo y límite aplicable. Después se aplica el multiplicador API: 2× prueba y 3,5× producción por defecto. La configuración puede variar. Treinta minutos con una fuente y voz: 100 × 3,5 = 350 créditos en producción. Un token de prueba no permite 30 minutos.

Usa estimate-cost con los mismos ajustes y revisa final_credits y credit_multiplier. Comprueba el saldo restante antes de aprobar. La duración es aproximada; el coste corresponde a los ajustes solicitados, no al cronómetro del audio final.

Estado, descarga y errores

Con tokens de prueba consulta cada 240 segundos como máximo, hasta 12 veces, reservando capacidad para otras peticiones. En producción usa esperas limitadas y respeta las cabeceras. Si sigue pendiente, guarda el ID y vuelve después; no dupliques la creación. Este documento no promete un webhook de finalización.

Descarga solo al llegar a completed. Un fallo debe mostrar un motivo final; revisa el saldo y reembolso antes de otro intento. La URL de descarga es temporal y privada: no la publiques ni la guardes como dirección permanente.

GET /v1/podcasts/{id}/status → requested / processing / completed / failed

GET /v1/podcasts/{id}/download

Privacidad, publicación y borrado

El resultado es público por defecto. Creator y Pro permiten elegir privado antes de generar; los episodios privados se pueden publicar después confirmando los derechos. La API de producción respeta la elección del propietario suscrito; la generación de prueba rechaza la publicación automática; cambiar la visibilidad después es una operación distinta. Para crear en privado, envía explícitamente auto_publish=false con tu cuenta Pro.

PATCH /v1/podcasts/{id}/visibility

{ "is_public": true, "rights_confirmed": true }

DELETE /v1/podcasts/{id}

Referencia

El contrato versionado define campos, tipos y errores. Usa estilos canónicos; valores desconocidos se rechazan. Una petición inválida no debe gastar créditos. 401/403: credenciales o permisos; 402: saldo; 404: contenido no disponible o ajeno; 409: conflicto de idempotencia; 429: límite. No repitas a ciegas operaciones cobradas tras un 5xx.

OpenAPI v1 · AI agents

Comparación con Google

Google documenta una API empresarial de audio. Su API independiente de pódcasts está obsoleta y cerrada a clientes nuevos. Compara acceso y autenticación actuales en lugar de afirmar que Google no tiene API.

Google audio-overview API · Google Podcast API status

Elige una vía de configuración en la guía de integraciones o usa la fuente de la biblioteca ficticia para una primera petición sin publicar material personal.