Podcasts mit der Podhoc-API erzeugen: vollständige Anleitung

Erzeuge KI-Podcasts programmatisch mit der Podhoc-API

Um einen Podcast mit der Podhoc-API zu erzeugen, sende eine POST-Anfrage an https://api-ext.podhoc.com/v1/podcasts mit deinem X-Api-Key-Header, den Quell-URLs, einer Zieldauer zwischen 1 und 120 Minuten und einer optionalen Stil- und Stimmkonfiguration. Der Endpunkt liefert eine podcast_id, die du unter /v1/podcasts/{id}/status bis zur Fertigstellung abfragst (üblicherweise 2-5 Minuten), dann rufst du /v1/podcasts/{id}/download auf, um eine eine Stunde gültige vorsignierte MP3-URL zu erhalten.

Die API ist auf einen einzelnen Erstellen-Abfragen-Herunterladen-Lebenszyklus ausgelegt. Es gibt keine Streams, keine Callbacks, keine Webhooks (noch nicht). Authentifizierung ist ein einziger statischer Header. Wenn du jemals eine REST-API aufgerufen hast, kannst du Podhoc in unter einer Stunde integrieren.

Übersetzungshinweis: von einem deutschen Muttersprachler zu prüfen.

Wozu die API dient

Die Podhoc-API stellt dieselbe Generierungspipeline bereit, die auch die Web-App antreibt, reduziert auf eine kleine Menge von Primitiven:

• Programmatische Podcast-Erstellung aus öffentlichen URLs.
• Kostenschätzung vor dem Ausgeben von Credits.
• Konto-Introspektion — Kreditstand, Nutzungshistorie, aktueller Tarif.
• Lebenszyklus-Verwaltung — Statusabfrage und vorsigniertes Herunterladen.

Die Pipeline hinter diesen Primitiven ist dasselbe fünfstufige System, das in Was ist ein KI-Podcast? beschrieben wird: Aufnahme, Verstehen, Audio-Reformatierung, Formatauswahl und Sprachsynthese. Die API macht es einfach skriptfähig.

Häufige Anwendungsfälle:

• Ein SaaS-Produkt, das von Kunden hochgeladene URLs in Onboarding-Audio verwandelt.
• Ein internes Tool, das wöchentliche Newsletter in pendlerfreundliche Episoden umwandelt.
• Eine Lernplattform, die automatisch Audioversionen neuer Kursmodule generiert.
• Ein Forschungs-Workflow, der eine Reihe von Papieren zu einer einzigen 30-minütigen Briefing zusammenfasst.

Mehr dazu unter API-Integrationsideen.

Schritt 1 — Token bereitstellen

API-Zugang ist auf den Pro-Tarif (29 €/Monat, 3500 Credits) und höher beschränkt. Sobald du upgegradet hast, gehe zu app.podhoc.com/account/api-access und erstelle ein Token.

Es gibt zwei Varianten:

• Test-Tokens — Präfix phk_test_…, günstiger (1,5x Kredit-Multiplikator), eingeschränkter Funktionsumfang. Verwende sie während Entwicklung und CI-Integrationstests.
• Produktions-Tokens — Präfix phk_prod_…, voller Funktionsumfang, 2,5x Kredit-Multiplikator.

Behandle Tokens wie Passwörter. Speichere sie in einem Secrets Manager (AWS Secrets Manager, HashiCorp Vault, Doppler) und committe sie niemals in die Versionskontrolle. Die API lehnt Anfragen mit geleakten oder widerrufenen Tokens mit 401 UNAUTHORIZED ab.

Authentifizierung ist ein einzelner Header in jeder Anfrage:

X-Api-Key: phk_prod_a1b2c3d4e5f6...

Die Basis-URL ist https://api-ext.podhoc.com/v1. Alle Endpunkte liefern JSON mit einem success-Boolean, einem data-Objekt bei Erfolg, einem error-Objekt bei Fehlern und einem meta-Objekt mit request_id und kreditbezogenen Feldern. Der Umschlag orientiert sich an denselben Konventionen, denen Anthropic und andere moderne KI-Anbieter folgen — vorhersagbare Struktur, vorhersagbare Fehlerbehandlung.

Schritt 2 — Zuerst die Kosten schätzen

Bevor du den Erstellen-Endpunkt aufrufst, frage die API, wie viel sie berechnen wird. Der Schätz-Endpunkt ist kostenlos und erlaubt dir, Ausgabenkontrollen sauber zu implementieren.

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"

Die Antwort schlüsselt die Kosten auf, sodass du deine eigene Richtlinienlogik anwenden kannst:

{
  "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"
  }
}

Die Preisformel hat eine Obergrenze von 500 Credits pro Anfrage, die nach Stimm-Multiplikatoren, Multi-Source-Boni und Custom-Weights-Boni angewendet wird. Verwende die Aufschlüsselung, um deinen Endbenutzern eine “Diese Episode kostet N Credits”-Vorschau zu zeigen, bevor sie bestätigen.

Du kannst auch deinen aktuellen Kontostand abfragen:

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

Schritt 3 — Den Podcast erstellen

Der Erstellen-Endpunkt ist derjenige, der Arbeit erledigt und Credits berechnet. Die minimale Nutzlast ist eine Liste von 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": "de",
    "target_duration_minutes": 15,
    "style": "deep_dive",
    "voice_config": { "voices": 2 }
  }'

Die Antwort (HTTP 202 Accepted) liefert dir den Identifier, den du abfragen wirst:

{
  "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
  }
}

Der Parameter style ist eines der acht pädagogischen Formate, die Podhoc unterstützt — deep_dive, didactic, feynman_technique, critique, debate, simplified_explanation, pedagogical_framework, alchemist_formula. Jedes liefert für dieselbe Quelle deutlich unterschiedliche Ausgaben. Siehe den Audio-Stil-Leitfaden, um zu erfahren, wann welches gewählt werden sollte.

Der Parameter language akzeptiert jeden der 74 unterstützten Sprachcodes — en-US, es, fr, de, it, ca, ar, ru und 66 weitere. Quellsprache und Ausgabesprache sind entkoppelt: Übergib eine englische URL und das Flag language: "de" und du erhältst einen deutschen Podcast.

Schritt 4 — Statusendpunkt abfragen

Die Generierung läuft asynchron. Die podcast_id ist dein Handle für den Rest des Lebenszyklus.

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

Der Status durchläuft vier Werte:

• requested — angenommen, in Warteschlange.
• processing — wird ausgeführt.
• completed — fertig, bereit zum Herunterladen.
• failed — terminaler Fehler; siehe Antwortdetails.

Frage alle 10 Sekunden mit kleinem Backoff ab. Die meisten Podcasts sind in 2-5 Minuten fertig, unabhängig von der Quelllänge, weil die Pipeline auf Cloud-GPUs parallelisiert. Ein vernünftiger Client implementiert die Abfrage mit einer harten Obergrenze (15 Minuten) und zeigt dem Endbenutzer eine “in Bearbeitung”-Oberfläche.

Schritt 5 — MP3 herunterladen

Der Download-Endpunkt liefert eine vorsignierte S3-URL, die nach einer Stunde abläuft:

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
  }
}

Streame die URL in deinen eigenen Speicher. Wenn du eine permanente Referenz brauchst, kopiere die Bytes in deinen S3-/GCS-/Azure-Bucket — die vorsignierte URL ist kurzlebig, aber das Audio, das du holst, lebt für immer in deiner Umgebung.

Eine vollständige Python-Integration

Hier ist derselbe Lebenszyklus als ausführbares Skript. Es schätzt Kosten, prüft den Kontostand, erstellt, fragt ab und lädt herunter. Die Fehlerbehandlung ist absichtlich explizit, damit du siehst, wo jeder API-Vertrag durchgesetzt wird.

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="de",
        style="deep_dive",
    )
    wait_for(pid)
    download(pid, "podcast.mp3")
    print(f"Saved podcast.mp3")

Ein Node.js-Äquivalent verwendet denselben Ablauf mit fetch. Beide sind in der vollständigen API-Referenz dokumentiert.

Rate-Limits und wie man sie respektiert

Das Erreichen eines Limits liefert HTTP 429 mit einem Retry-After-Header. Ein korrekter Client respektiert diesen Header und reiht den nächsten Versuch entsprechend ein. Produktionslimits sind für typische SaaS-Integrationen kalibriert — die meisten Teams kommen ihnen nie nahe. Wenn doch, sprich mit uns über ein Enterprise-Kontingent.

Die übliche Praxis zur Härtung jedes API-Clients gilt auch hier: setze ein Timeout auf jede Anfrage (15-30 Sekunden reichen), begrenze Wiederholungen (drei Versuche mit exponentiellem Backoff) und gib 5xx-Fehler an deinen Operator weiter, statt sie zu schlucken. Die OAuth-2.1-RFC ist für eine API mit statischem Token wie diese überdimensioniert, aber ihre operative Hygiene ist es wert geliehen zu werden — protokolliere Anfrage-IDs (meta.request_id) bei jedem Fehler, damit der Support korrelieren kann.

Was Test-Tokens nicht können

Test-Tokens sind absichtlich eingeschränkt, sodass du günstig integrieren kannst, ohne Produktions-Credits zu verbrennen. Konkret:

• Maximale Episodendauer: 5 Minuten.
• Erlaubte Sprachen: nur Englisch (en-US, en).
• URLs pro Anfrage: 1.
• Maximale Stimmen: 2.
• custom_focus, source_weights und auto_publish: nicht verfügbar.

Der Versuch davon liefert 400 TEST_TOKEN_RESTRICTED. Wechsle zu einem Produktions-Token (im selben Pro-Konto), wenn du bereit bist, in Produktion zu gehen.

Webhooks, Datei-Uploads und was (noch) nicht unterstützt wird

Einige Funktionen, die in der Web-App existieren, sind heute nicht in der API:

• Datei-Uploads. Du kannst URLs übergeben, aber keine rohen PDF-/DOCX-/TXT-Bytes. Wenn dein Inhalt authentifizierungsgeschützt ist, hoste ihn öffentlich mit einer signierten URL oder kontaktiere uns für einen Enterprise-Weg.
• Roher Textkörper. Der urls-Parameter ist der einzige Aufnahmemechanismus; du kannst kein text_content-Feld posten.
• Webhooks / Callbacks. Statusänderungen werden per Abfrage beobachtet. Eine Webhook-Schicht ist auf unserer Roadmap; derzeit ist eine Abfrageschleife alle 10 Sekunden das empfohlene Muster.

Diese Lücken sind beabsichtigt — die API startet mit minimaler tragfähiger Oberfläche und wir werden sie erweitern, sobald sich Integrationsmuster stabilisieren.

Was als Nächstes zu bauen

Sobald deine erste Integration läuft, ist der natürliche nächste Schritt, die API in eine echte Produktoberfläche zu integrieren. Einige Ausgangspunkte:

• Kombiniere die API mit einem Telegram-Bot, damit deine Nutzer Generierung aus dem Chat heraus auslösen können.
• Kombiniere Podcast-Erstellung mit unseren acht Audio-Stilen, damit deine Nutzer die pädagogische Behandlung pro Quelle wählen.
• Treibe PDF-zu-Podcast-Workflows an, indem du das PDF zuerst öffentlich hostest und dann die URL übergibst.
• Lies API-Integrationsideen für konkrete Muster, die wir in den ersten 30 Tagen mit der API gesehen haben.

Das Ziel der API ist es, Podhoc aus dem Browser zu holen und in dein Produkt zu bringen. Der Fünf-Schritte-Lebenszyklus ist absichtlich klein. Baue den dünnen Wrapper, teste gegen deine eigenen URLs und iteriere.

API-Token bereitstellen →