كيفية توليد بودكاست باستخدام واجهة Podhoc البرمجية: دليل شامل

ولّد بودكاست بالذكاء الاصطناعي برمجيًا عبر واجهة Podhoc البرمجية

لتوليد بودكاست عبر واجهة Podhoc البرمجية، أرسل طلب POST إلى https://api-ext.podhoc.com/v1/podcasts مع ترويسة X-Api-Key، روابط المصادر، مدة مستهدفة بين 1 و 120 دقيقة، وإعداد اختياري للنمط والأصوات. يعيد الـ endpoint قيمة podcast_id تستعلم عنها في /v1/podcasts/{id}/status حتى الاكتمال (عادة 2-5 دقائق)، ثم تستدعي /v1/podcasts/{id}/download لجلب رابط MP3 موقَّع مسبقًا صالح لساعة واحدة.

الـ API مصمَّمة لدورة واحدة من النمط إنشاء-استعلام-تنزيل. لا توجد بثوث، ولا callbacks، ولا webhooks (بعد). المصادقة ترويسة ساكنة واحدة. إن سبق لك استدعاء أي API REST، فيمكنك دمج Podhoc في أقل من ساعة.

ملاحظة ترجمة: للمراجعة من قبل ناطق أصلي بالعربية.

ما الفائدة من الـ API

تكشف واجهة Podhoc البرمجية مسار التوليد ذاته الذي يُغذّي التطبيق الويب، مختزَلًا إلى مجموعة صغيرة من العمليات الأولية:

• إنشاء برمجي للبودكاست من روابط عامة.
• تقدير التكلفة قبل إنفاق الأرصدة.
• استعلام الحساب — رصيد الأرصدة، سجل الاستخدام، المستوى الحالي.
• إدارة دورة الحياة — استعلام الحالة والتنزيل الموقَّع مسبقًا.

المسار خلف هذه العمليات هو نفسه نظام الخمس مراحل الموصوف في ما هو البودكاست بالذكاء الاصطناعي؟: الاستيعاب، الفهم، إعادة التشكيل للصوت، اختيار الصيغة، وتركيب الصوت. الـ API تجعله قابلًا للأتمتة فحسب.

حالات استخدام شائعة:

• منتج SaaS يحوّل روابط رفعها العملاء إلى صوت تأهيل.
• أداة داخلية تحوّل النشرات الأسبوعية إلى حلقات جاهزة لرحلة الذهاب والإياب.
• منصة تعلّم تولّد تلقائيًا نسخًا صوتية للوحدات الجديدة.
• تدفّق بحثي يوحّد مجموعة من الأوراق في إفادة واحدة مدتها 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...

الرابط الأساسي هو https://api-ext.podhoc.com/v1. تُعيد كل النقاط الطرفية JSON بقيمة منطقية success، وكائن data عند النجاح، وكائن error عند الفشل، وكائن meta به request_id وحقول مرتبطة بالأرصدة. المظروف يستلهم من نفس الأعراف التي يتبعها Anthropic ومزوّدو الذكاء الاصطناعي الحديثون الآخرون — بنية يمكن التنبؤ بها ومعالجة أخطاء يمكن التنبؤ بها.

الخطوة 2 — قدّر التكلفة أولًا

قبل استدعاء endpoint الإنشاء، اسأل الـ API كم ستحتسب. endpoint التقدير مجاني ويتيح لك تنفيذ ضوابط الإنفاق بنظافة.

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 — أنشئ البودكاست

endpoint الإنشاء هو الذي يقوم بالعمل ويستهلك الأرصدة. أقل حمولة هي قائمة روابط:

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": "ar",
    "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 لغة أخرى. لغة المصدر ولغة الإخراج منفصلتان: مرّر رابطًا بالإنجليزية مع language: "ar" وستحصل على بودكاست بالعربية.

الخطوة 4 — استعلم عن endpoint الحالة

التوليد يجري لاتزامنيًا. الـ 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

endpoint التنزيل يعيد رابط 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
  }
}

ابثّ الرابط إلى تخزينك الخاص. إذا احتجت مرجعًا دائمًا، انسخ البايتات إلى دلوك في S3 / GCS / Azure — الرابط الموقَّع مسبقًا قصير العمر، لكن الصوت الذي تجلبه يحيا للأبد في بيئتك.

تكامل 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="ar",
        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 تنطبق هنا: ضع timeout على كل طلب (15-30 ثانية تكفي)، حُدّ المحاولات (ثلاث محاولات بتراجع أُسّي)، واعرض أخطاء 5xx على المشغّل بدلًا من ابتلاعها. RFC OAuth 2.1 مبالَغ بها لـ API ذي رمز ساكن مثل هذه، لكن نظافتها التشغيلية تستحق الاستعارة — سجّل معرّفات الطلب (meta.request_id) عند كل خطأ ليتمكّن الدعم من الربط.

ما لا يستطيع رمز الاختبار فعله

رموز الاختبار مقيَّدة عمدًا لتدمج بتكلفة منخفضة دون حرق أرصدة الإنتاج. تحديدًا:

• أقصى مدة للحلقة: 5 دقائق.
• اللغات المسموحة: الإنجليزية فقط (en-US، en).
• روابط لكل طلب: 1.
• أقصى عدد أصوات: 2.
• custom_focus، source_weights، وauto_publish: غير متاحة.

أي محاولة تعيد 400 TEST_TOKEN_RESTRICTED. انتقل إلى رمز إنتاج (في نفس حساب Pro) عندما تكون مستعدًا للنشر.

Webhooks، رفع الملفات، وما هو غير مدعوم (بعد)

بعض القدرات الموجودة في التطبيق الويب ليست في الـ API اليوم:

• رفع الملفات. يمكنك تمرير روابط لكن ليس بايتات PDF / DOCX / TXT خام. إن كان محتواك خلف مصادقة، استضفه علنيًا برابط موقَّع أو تواصل معنا للحصول على مسار مؤسّسي.
• متون نص خام. المعامل urls هو الآلية الوحيدة للاستيعاب؛ لا يمكنك إرسال حقل text_content بـ POST.
• Webhooks / callbacks. تغيّرات الحالة تُرصد عبر الاستعلام. طبقة webhook على خارطة طريقنا؛ في الوقت الحالي، حلقة استعلام كل 10 ثوانٍ هي النمط الموصى به.

هذه الفجوات مقصودة — تنطلق الـ API بسطح أدنى صالح وسنوسّعه عندما تستقر أنماط التكامل.

ماذا تبني تاليًا

بمجرد تشغيل تكاملك الأول، الخطوة الطبيعية التالية هي تبني الـ API في سطح منتج حقيقي. بعض نقاط البداية:

• ادمج الـ API مع بوت تيليجرام ليسمح لمستخدميك بتشغيل التوليد من المحادثة.
• ادمج إنشاء البودكاست مع أنماط الصوت الثمانية لدينا ليختار مستخدموك المعالجة التربوية لكل مصدر.
• شغّل تدفّقات PDF إلى بودكاست باستضافة الـ PDF علنيًا أولًا، ثم تمرير الرابط.
• اقرأ أفكار تكامل الـ API للأنماط الملموسة التي رأينا فرقًا تطلقها بالـ API في أول 30 يومًا.

هدف الـ API إخراج Podhoc من المتصفّح وإدخاله في منتجك. دورة الخمس خطوات صغيرة عمدًا. ابنِ الغلاف الرفيع، اختبر مع روابطك، وكرّر.

احصل على رمز API ←