Как генерировать подкасты через API Podhoc: полное руководство

Генерируйте ИИ-подкасты программно через API Podhoc

Чтобы сгенерировать подкаст через API Podhoc, отправьте POST-запрос на https://api-ext.podhoc.com/v1/podcasts с заголовком X-Api-Key, исходными URL, целевой длительностью от 1 до 120 минут и опциональной конфигурацией стиля и голосов. Эндпоинт возвращает podcast_id, который вы опрашиваете на /v1/podcasts/{id}/status до завершения (обычно 2-5 минут), затем вызываете /v1/podcasts/{id}/download, чтобы получить предподписанный MP3-URL, действительный в течение часа.

API спроектирован под единственный цикл создание-опрос-загрузка. Нет потоков, нет колбэков, нет вебхуков (пока). Аутентификация — один статический заголовок. Если вы когда-либо вызывали REST API, вы интегрируете Podhoc меньше чем за час.

Примечание о переводе: требуется проверка носителем русского языка.

Для чего нужен API

API Podhoc раскрывает тот же конвейер генерации, что питает веб-приложение, сведённый к небольшому набору примитивов:

• Программное создание подкастов из публичных URL.
• Оценка стоимости перед тратой кредитов.
• Интроспекция аккаунта — баланс кредитов, история использования, текущий уровень.
• Управление жизненным циклом — опрос статуса и предподписанная загрузка.

Конвейер за этими примитивами — та же пятиэтапная система, описанная в Что такое ИИ-подкаст?: загрузка, понимание, переформатирование под аудио, выбор формата и синтез голоса. API просто делает её скриптуемой.

Распространённые сценарии:

• SaaS-продукт, превращающий загруженные клиентами URL в аудио для онбординга.
• Внутренний инструмент, превращающий еженедельные новостные рассылки в эпизоды для дороги.
• Обучающая платформа, автоматически генерирующая аудиоверсии новых модулей курса.
• Исследовательский процесс, синтезирующий набор статей в один 30-минутный брифинг.

Подробнее — в идеях интеграции API.

Шаг 1 — Получите токен

Доступ к API ограничен планом Pro (29 €/мес, 3500 кредитов) и выше. После апгрейда подписки перейдите на app.podhoc.com/account/api-access и создайте токен.

Есть две разновидности:

• Тестовые токены — префикс phk_test_…, дешевле (множитель 1,5x), ограниченный набор функций. Используйте при разработке и интеграционных тестах в CI.
• Продакшен-токены — префикс phk_prod_…, полный набор функций, множитель 2,5x.

Относитесь к токенам как к паролям. Храните их в менеджере секретов (AWS Secrets Manager, HashiCorp Vault, Doppler) и никогда не коммитьте в систему контроля версий. API отклоняет запросы с утёкшими или отозванными токенами с ответом 401 UNAUTHORIZED.

Аутентификация — один заголовок в каждом запросе:

X-Api-Key: phk_prod_a1b2c3d4e5f6...

Базовый URL — https://api-ext.podhoc.com/v1. Все эндпоинты возвращают JSON с булевым success, объектом data при успехе, объектом error при ошибке и объектом meta с request_id и полями, связанными с кредитами. Конверт заимствует те же соглашения, что и Anthropic и другие современные ИИ-провайдеры — предсказуемая структура, предсказуемая обработка ошибок.

Шаг 2 — Сначала оцените стоимость

Перед вызовом эндпоинта создания спросите API, сколько он спишет. Эндпоинт оценки бесплатен и позволяет аккуратно реализовать контроль расходов.

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"

Ответ детализирует стоимость, чтобы вы могли применить собственную логику политик:

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

Формула цены имеет потолок 500 кредитов за запрос, применяемый после голосовых множителей, бонусов за несколько источников и за пользовательские веса. Используйте детализацию, чтобы показывать пользователям предварительный просмотр «этот эпизод будет стоить N кредитов» перед подтверждением.

Также можно получить актуальный баланс:

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

Шаг 3 — Создайте подкаст

Эндпоинт создания — тот, что выполняет работу и списывает кредиты. Минимальная нагрузка — список 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": "ru",
    "target_duration_minutes": 15,
    "style": "deep_dive",
    "voice_config": { "voices": 2 }
  }'

Ответ (HTTP 202 Accepted) даёт идентификатор для опроса:

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

Параметр style — один из восьми педагогических форматов, поддерживаемых Podhoc, — deep_dive, didactic, feynman_technique, critique, debate, simplified_explanation, pedagogical_framework, alchemist_formula. Каждый из них производит заметно разный результат для одного и того же источника. См. руководство по аудио-стилям, чтобы понимать, когда какой выбирать.

Параметр language принимает любой из 74 поддерживаемых кодов языков — en-US, es, fr, de, it, ca, ar, ru плюс ещё 66. Язык источника и язык вывода независимы: передайте URL на английском с language: "ru" и получите подкаст на русском.

Шаг 4 — Опрашивайте эндпоинт состояния

Генерация выполняется асинхронно. podcast_id — ваш идентификатор для остального жизненного цикла.

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

Состояние проходит через четыре значения:

• requested — принят, в очереди.
• processing — активно выполняется.
• completed — готово, можно скачивать.
• failed — терминальная ошибка; смотрите детали ответа.

Опрашивайте каждые 10 секунд с небольшим откатом. Большинство подкастов завершается за 2-5 минут независимо от длины источника, потому что конвейер распараллеливается на облачных GPU. Разумный клиент реализует опрос с жёстким потолком (15 минут) и показывает конечному пользователю интерфейс «в процессе».

Шаг 5 — Скачайте MP3

Эндпоинт загрузки возвращает предподписанный URL S3, который истекает через час:

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

Стримьте URL в собственное хранилище. Если нужна постоянная ссылка, скопируйте байты в свой бакет S3 / GCS / Azure: предподписанный URL короткоживущий, но скачанное аудио живёт в вашей среде вечно.

Полная интеграция на Python

Вот тот же цикл в виде исполняемого скрипта. Он оценивает стоимость, проверяет баланс, создаёт, опрашивает и скачивает. Обработка ошибок намеренно явная, чтобы было видно, где применяется каждый контракт 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="ru",
        style="deep_dive",
    )
    wait_for(pid)
    download(pid, "podcast.mp3")
    print(f"Saved podcast.mp3")

Аналог на Node.js использует тот же поток с fetch. Оба задокументированы в полной справочной документации API.

Лимиты частоты и как их соблюдать

Достижение лимита возвращает HTTP 429 с заголовком Retry-After. Корректный клиент уважает этот заголовок и ставит следующую попытку в очередь соответствующим образом. Продакшен-лимиты откалиброваны под типичные SaaS-интеграции — большинство команд никогда к ним не приближаются. Если вы — приближаетесь, поговорите с нами о корпоративной квоте.

Стандартная практика закаливания любого API-клиента применима и здесь: ставьте таймаут на каждый запрос (15-30 секунд достаточно), ограничивайте повторы (три попытки с экспоненциальным откатом) и показывайте 5xx-ошибки оператору вместо того, чтобы их глотать. RFC OAuth 2.1 избыточен для API со статическим токеном, как этот, но его операционную гигиену стоит позаимствовать — логируйте идентификаторы запросов (meta.request_id) при каждой ошибке, чтобы поддержка могла корелировать.

Чего не могут тестовые токены

Тестовые токены намеренно ограничены, чтобы вы могли интегрироваться дёшево, не сжигая продакшен-кредиты. А именно:

• Максимальная длительность эпизода: 5 минут.
• Разрешённые языки: только английский (en-US, en).
• URL за запрос: 1.
• Максимум голосов: 2.
• custom_focus, source_weights и auto_publish: недоступны.

Любая попытка возвращает 400 TEST_TOKEN_RESTRICTED. Переключитесь на продакшен-токен (всё в том же Pro-аккаунте), когда будете готовы выкатывать.

Вебхуки, загрузки файлов и что не поддерживается (пока)

Несколько возможностей, которые есть в веб-приложении, отсутствуют в API сегодня:

• Загрузка файлов. Можно передавать URL, но не сырые байты PDF / DOCX / TXT. Если ваш контент за аутентификацией, разместите его публично с подписанным URL или свяжитесь с нами для корпоративного маршрута.
• Сырое тело текста. Параметр urls — единственный механизм загрузки; вы не можете POST’ить поле text_content.
• Вебхуки / колбэки. Изменения статуса наблюдаются через опрос. Слой вебхуков в дорожной карте; пока цикл опроса каждые 10 секунд — рекомендованный паттерн.

Эти пробелы намеренные — API запускается с минимально жизнеспособной поверхностью, и мы будем её расширять по мере стабилизации интеграционных паттернов.

Что собрать дальше

Когда первая интеграция работает, естественный следующий шаг — внедрить API в реальную поверхность продукта. Несколько отправных точек:

• Сочетайте API с ботом Telegram, чтобы пользователи запускали генерацию из чата.
• Сочетайте создание подкастов с нашими восемью аудио-стилями, чтобы пользователи выбирали педагогическую обработку для каждого источника.
• Запускайте сценарии PDF в подкаст, сначала разместив PDF публично, потом передав URL.
• Прочтите идеи интеграции API — конкретные паттерны, которые мы видели у команд, выкатывающих с API в первые 30 дней.

Цель API — вывести Podhoc из браузера в ваш продукт. Цикл из пяти шагов специально маленький. Соберите тонкую обёртку, тестируйте на собственных URL и итерируйте.

Получить API-токен →