Com generar pòdcasts amb l'API de Podhoc: guia completa

Genera pòdcasts amb IA de manera programàtica amb l’API de Podhoc

Per generar un pòdcast amb l’API de Podhoc, envia una petició POST a https://api-ext.podhoc.com/v1/podcasts amb la teva capçalera X-Api-Key, els URL font, una durada objectiu entre 1 i 120 minuts i una configuració opcional d’estil i veus. L’endpoint retorna un podcast_id que consultes a /v1/podcasts/{id}/status fins a la finalització (normalment 2-5 minuts), i després crides /v1/podcasts/{id}/download per obtenir un URL MP3 prefirmat vàlid durant una hora.

L’API està dissenyada per a un únic cicle crear-consultar-descarregar. No hi ha streams, ni callbacks, ni webhooks (encara). L’autenticació és una sola capçalera estàtica. Si alguna vegada has cridat una API REST, pots integrar Podhoc en menys d’una hora.

Nota de traducció: a revisar per un parlant nadiu del català.

Per a què serveix l’API

L’API de Podhoc exposa la mateixa pipeline de generació que impulsa l’aplicació web, reduïda a un petit conjunt de primitives:

• Creació programàtica de pòdcasts des d’URL públics.
• Estimació de costos abans de gastar crèdits.
• Inspecció del compte — saldo de crèdits, historial d’ús, nivell actual.
• Gestió del cicle de vida — consulta d’estat i descàrrega prefirmada.

La pipeline darrere d’aquestes primitives és el mateix sistema de cinc etapes descrit a Què és un pòdcast amb IA?: ingestió, comprensió, reformatació per a àudio, elecció de format i síntesi de veu. L’API simplement el fa programable.

Casos d’ús comuns:

• Un producte SaaS que converteix URL pujats per clients en àudio d’incorporació.
• Una eina interna que transforma butlletins setmanals en episodis llestos per al trajecte.
• Una plataforma d’aprenentatge que genera automàticament versions en àudio dels nous mòduls del curs.
• Un flux de recerca que sintetitza un conjunt de papers en una única sessió informativa de 30 minuts.

Per a més, consulta Idees d’integració amb l’API.

Pas 1 — Provisiona un token

L’accés a l’API està limitat al pla Pro (29 €/mes, 3500 crèdits) i superiors. Un cop actualitzada la subscripció, ves a app.podhoc.com/account/api-access i crea un token.

Hi ha dos sabors:

• Tokens de prova — prefix phk_test_…, més barats (multiplicador 1,5x), conjunt de funcions restringit. Usa’’ls durant el desenvolupament i les proves d’‘integració en CI.
• Tokens de producció — prefix phk_prod_…, conjunt complet de funcions, multiplicador 2,5x.

Tracta els tokens com contrasenyes. Emmagatzema’ls en un gestor de secrets (AWS Secrets Manager, HashiCorp Vault, Doppler) i mai els comprometis al control de codi font. L’API rebutja les peticions amb tokens filtrats o revocats amb 401 UNAUTHORIZED.

L’autenticació és una sola capçalera a cada petició:

X-Api-Key: phk_prod_a1b2c3d4e5f6...

L’URL base és https://api-ext.podhoc.com/v1. Tots els endpoints retornen JSON amb un booleà success, un objecte data en èxit, un objecte error en fallada i un objecte meta amb request_id i camps relacionats amb crèdits. El sobre s’inspira en les mateixes convencions que segueixen Anthropic i altres proveïdors moderns d’IA: estructura predictible, gestió d’errors predictible.

Pas 2 — Estima el cost primer

Abans de cridar l’endpoint de creació, pregunta a l’API quant cobrarà. L’endpoint d’estimació és gratuït i et permet implementar controls de despesa netament.

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 resposta desglossa el cost perquè puguis aplicar la teva pròpia lògica de polítiques:

{
  "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 preus té un sostre de 500 crèdits per petició, aplicat després dels multiplicadors de veu, les bonificacions multifont i les de pesos personalitzats. Usa el desglossament per mostrar als teus usuaris finals una vista prèvia “aquest episodi costarà N crèdits” abans que confirmin.

També pots consultar el teu saldo en directe:

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

Pas 3 — Crea el pòdcast

L’endpoint de creació és el que fa feina i cobra crèdits. La càrrega útil mínima és una llista d’URL:

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": "ca",
    "target_duration_minutes": 15,
    "style": "deep_dive",
    "voice_config": { "voices": 2 }
  }'

La resposta (HTTP 202 Accepted) et dóna l’identificador que consultaràs:

{
  "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àmetre style és un dels vuit formats pedagògics que admet Podhoc — deep_dive, didactic, feynman_technique, critique, debate, simplified_explanation, pedagogical_framework, alchemist_formula. Cadascun produeix una sortida notablement diferent per a la mateixa font. Consulta la guia d’estils d’àudio per saber quan triar cadascun.

El paràmetre language accepta qualsevol dels 74 codis d’idioma admesos — en-US, es, fr, de, it, ca, ar, ru i 66 més. L’idioma d’origen i el de sortida estan desacoblats: passa un URL en anglès amb language: "ca" i obtindràs un pòdcast en català.

Pas 4 — Consulta l’endpoint d’estat

La generació és asíncrona. El podcast_id és el teu identificador per a la resta del cicle de vida.

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

L’estat passa per quatre valors:

• requested — acceptat, en cua.
• processing — en execució.
• completed — fet, llest per descarregar.
• failed — error terminal; consulta els detalls de la resposta.

Consulta cada 10 segons amb un petit retrocés. La majoria de pòdcasts es completen en 2-5 minuts independentment de la longitud de la font, perquè la pipeline paral·lelitza a GPUs al núvol. Un client raonable implementa la consulta amb un sostre estricte (15 minuts) i mostra una interfície “en progrés” a l’usuari final.

Pas 5 — Descarrega l’MP3

L’endpoint de descàrrega retorna un URL prefirmat de S3 que caduca 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
  }
}

Transmet l’URL al teu propi emmagatzematge. Si necessites una referència permanent, copia els bytes al teu bucket S3 / GCS / Azure: l’URL prefirmat és de curta durada, però l’àudio que descarreguis viu per sempre al teu entorn.

Una integració completa en Python

Aquí tens el mateix cicle com a script executable. Estima el cost, comprova el saldo, crea, consulta i descarrega. La gestió d’errors és intencionalment explícita perquè vegis on s’aplica cada contracte de l’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="ca",
        style="deep_dive",
    )
    wait_for(pid)
    download(pid, "podcast.mp3")
    print(f"Saved podcast.mp3")

Un equivalent en Node.js usa el mateix flux amb fetch. Tots dos estan documentats a la referència completa de l’API.

Límits de freqüència i com respectar-los

Arribar a un límit retorna HTTP 429 amb capçalera Retry-After. Un client correcte respecta aquesta capçalera i encua el següent intent en conseqüència. Els límits de producció estan calibrats per a integracions SaaS típiques — la majoria d’equips mai s’hi acosten. Si tu sí, parla amb nosaltres per a una quota empresarial.

La pràctica estàndard per endurir qualsevol client API s’aplica aquí: posa un timeout a cada petició (15-30 segons són suficients), limita els reintents (tres intents amb retrocés exponencial) i mostra els errors 5xx al teu operador en lloc d’empassar-los. La RFC OAuth 2.1 és excessiva per a una API de token estàtic com aquesta, però la seva higiene operativa val la pena agafar-la — registra els ID de petició (meta.request_id) en cada error perquè el suport pugui correlacionar.

Què no poden fer els tokens de prova

Els tokens de prova estan deliberadament restringits perquè puguis integrar de manera barata sense gastar crèdits de producció. En concret:

• Durada màxima de l’episodi: 5 minuts.
• Idiomes permesos: només anglès (en-US, en).
• URL per petició: 1.
• Veus màximes: 2.
• custom_focus, source_weights i auto_publish: no disponibles.

Qualsevol intent retorna 400 TEST_TOKEN_RESTRICTED. Canvia a un token de producció (dins del mateix compte Pro) quan estiguis preparat per enviar a producció.

Webhooks, càrregues d’arxius i el que encara no és compatible

Algunes funcions que existeixen a l’aplicació web no estan a l’API avui:

• Càrregues d’arxius. Pots passar URL però no bytes PDF / DOCX / TXT en brut. Si el teu contingut està darrere d’autenticació, hosteja-lo públicament amb un URL signat o contacta’ns per a una ruta empresarial.
• Cossos de text en brut. El paràmetre urls és l’únic mecanisme d’ingestió; no pots enviar un camp text_content.
• Webhooks / callbacks. Els canvis d’estat s’observen mitjançant consulta. Una capa de webhook és al nostre roadmap; per ara, un bucle de consulta de 10 segons és el patró recomanat.

Aquestes mancances són intencionals: l’API es llança amb una superfície mínima viable i l’ampliarem a mesura que els patrons d’integració s’estabilitzin.

Què construir a continuació

Un cop funcioni la teva primera integració, el següent pas natural és adoptar l’API en una superfície de producte real. Alguns punts de partida:

• Combina l’API amb un bot de Telegram perquè els teus usuaris desencadenin la generació des del xat.
• Combina la creació de pòdcasts amb els nostres vuit estils d’àudio perquè els teus usuaris triïn el tractament pedagògic per font.
• Impulsa fluxos de PDF a pòdcast hostejant primer el PDF públicament i passant després l’URL.
• Llegeix Idees d’integració amb l’API per a patrons concrets que hem vist a equips enviar amb l’API en els primers 30 dies.

L’objectiu de l’API és treure Podhoc del navegador i ficar-lo al teu producte. El cicle de cinc passos és petit a propòsit. Construeix l’embolcall fi, prova contra els teus propis URL i itera.

Provisiona un token d’API →