مفتاح واجهة برمجة التطبيقات TTS في Python: الإعداد، البث المتدفق، وضع JSON

تحقق مما يفتحه المفتاح

الأشخاص الذين يبحثون عن مثال مفتاح واجهة برمجة التطبيقات TTS في Python يريدون عادة تحويل النص إلى صوت مسموع. المفتاح من هذه الخدمة لا يفعل ذلك. إنه يصادق على الطلبات إلى LLM للنص: POST /v1/chat/completions و GET /v1/models، باستخدام النموذج uncensored. لا يوجد تركيب كلام، ولا رفع صوت، ولا تضمينات.

إذا كان ذلك يناسب مشروعك، على سبيل المثال لأنك تولد نصوصًا أو حوارًا أو سردًا تمرره إلى أداة كلام منفصلة، فإن بقية هذه الصفحة تعطيك Python يعمل. إذا كنت بحاجة إلى إخراج صوت من واجهة برمجة التطبيقات نفسها، فهذه الخدمة غير الصحيحة، ومن الأفضل معرفة ذلك الآن. الdocs يسردون مجموعة الميزات الدقيقة.

طريقة عملية لاستخدام توليد النصوص في مشروع صوتي هي اعتبارها مرحلة الكتابة. يقوم النموذج بكتابة السرد، أو إعادة كتابة سطر ليناسب حدًا زمنيًا، أو تحويل الملاحظات إلى حوار مع عدة متحدثين. بعد ذلك، يمرّر كود Python النص النهائي إلى أي أداة تحويل النص إلى كلام تستخدمها. يعني فصل المراحل أيضًا أنه يمكنك استبدال أي منها دون التأثير على الأخرى، ولا تدفع مقابل هذا الـ API إلا مقابل الكلمات التي يكتبها.

للمتابعة، تحتاج إلى Python 3.9 أو أحدث ومفتاح. سجّل في صفحة مفتاح API واحصل على رصيد تجريبي مجاني بقيمة $0.50 بنقرة واحدة؛ يستمر لمدة 7 أيام ولا يتطلب بطاقة.

احفظ المفتاح وثبّت الحزمة

لا تكتب المفتاح في ملف تقوم بإدراجه في المستودع. ضعه في متغير بيئة واقرأه عند وقت التشغيل.

Copy# base URL used below: https://api.ttsapihub.com/v1 , model: uncensored
pip install openai
export API_KEY="paste-your-key-here"

في PowerShell على Windows، المعادل هو $env:API_KEY = "paste-your-key-here". بالنسبة لمشروع، يُعد ملف .env الذي يُحمّل بحزمة مثل python-dotenv نمطًا شائعًا، طالما أن .env موجود في .gitignore الخاص بك.

إذا تسرّب المفتاح إلى مستودع، تعامل معه على أنه مستهلك: أزلّه من السجل إذا أمكن، واطلب مفتاحًا جديدًا. تذكر أن المفاتيح تنفد رصيد مسبق الدفع، لذا فإن المفتاح المتسرب هو أيضًا تسرب مالي.

أنشِئ العميل وأجرِ أول استدعاء

يقبل الحزمة الرسمية base_url. وباقي الأمر يتبع شكل استدعاء OpenAI المعتاد.

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.ttsapihub.com/v1",
    api_key=os.environ["API_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You write short narration scripts."},
        {"role": "user", "content": "Draft a 40-word intro for a podcast about night trains."},
    ],
    temperature=0.8,
    max_tokens=200,
)

print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

يُظهر الكائن usage عدد الرموز التي استخدمها الطلب، مما يتيح لك حساب التكلفة: عدد رموز الإدخال مضروبًا في $0.15 لكل مليون، بالإضافة إلى عدد رموز الإخراج مضروبًا في $0.50 لكل مليون. إذا استخدم الطلب أعلاه 60 رمز إدخال و80 رمز إخراج، فإن التكلفة هي $0.000009 بالإضافة إلى $0.00004، أي ما مجموعه $0.000049. الطلبات الفاشلة أو المرفوضة لا تُفرض عليها التكلفة.

max_tokens اختياري. بدونه، يمكن أن يستخدم الإكمال ما تبقى من نافذة السياق المكونة من 100,000 رمز، لذا اضبطه عندما تريد حدًا صارمًا للطول والتكلفة.

بث الرد

يعيد البث المتدفق الرموز بمجرد توليدها باستخدام أحداث مُرسَلة من الخادم (SSE). اضبط stream=True وقم بالتكرار.

Copyimport os
from openai import OpenAI

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"])

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Describe a rainy station platform in four sentences."}],
    stream=True,
)

parts = []
for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta.content or ""
    parts.append(delta)
    print(delta, end="", flush=True)

text = "".join(parts)

يوجد فحص لقائمة choices الفارغة لأن الحدث الأخير في التدفق قد يحمل بيانات الاستخدام ولا يحتوي على نص. تخطيه يتجنب خطأ الفهرس. تفصيل تشغيلي: يحتفظ الطلب المتدفق بخانة التزامن الخاصة به حتى ينتهي التدفق. إذا بدأت العديد من التدفقات في خيوط ولم تنهِ قراءتها أبدًا، فستصل إلى حدّ التزامن حتى إذا كان معدل طلباتك منخفضًا.

اطلب JSON واستدعِ الأدوات

وضع JSON

اضبط response_format على كائن JSON لجعل الرد قابلاً للتحليل. أخبر النموذج أيضًا في الموجّه أنك تريد JSON؛ فإعداد القيد يحدد الشكل، والموجّه يخبر النموذج بالشكل المطلوب.

Copyimport json, os
from openai import OpenAI

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"])

resp = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Reply only with JSON: {\"title\": str, \"beats\": [str]}"},
        {"role": "user", "content": "Outline a three-beat radio drama about a lost key."},
    ],
)

data = json.loads(resp.choices[0].message.content)
print(data["title"], len(data["beats"]))

لفّ json.loads في كتلة try على أي حال. يمكن أن يُقطع الرد الذي يصل إلى max_tokens في منتصف الكائن.

استدعاء الدوال

مرر tools وtool_choice اختياريًا. عندما يطلب النموذج أداة، قم بتشغيلها بنفسك وأرسل النتيجة مرة أخرى كرسالة مع role: "tool".

Copyimport json, os
from openai import OpenAI

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"])

tools = [{
    "type": "function",
    "function": {
        "name": "word_count",
        "description": "Count the words in a text",
        "parameters": {
            "type": "object",
            "properties": {"text": {"type": "string"}},
            "required": ["text"],
        },
    },
}]

messages = [{"role": "user", "content": "How many words are in: the quick brown fox?"}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
msg = first.choices[0].message

if msg.tool_calls:
    call = msg.tool_calls[0]
    args = json.loads(call.function.arguments)
    result = len(args["text"].split())
    messages.append(msg)
    messages.append({"role": "tool", "tool_call_id": call.id, "content": str(result)})
    final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
    print(final.choices[0].message.content)

حافظ على المحادثة وراقب ميزانية الرموز

واجهة API عديمة الحالة. إذا كنت تريد دردشة تتذكر ما قيل، فاحتفظ بقائمة الرسائل في برنامجك وأرسلها جميعًا مع كل طلب. تقوم فئة صغيرة بهذا العمل، وهي أيضًا المكان المناسب لحدّ حجم السجل التاريخي حتى لا تزيد التكلفة.

Copyimport os
from openai import OpenAI

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"])

history = [{"role": "system", "content": "You are a dialogue writer. Keep replies under 120 words."}]

def say(user_text, keep_last=12):
    history.append({"role": "user", "content": user_text})
    # keep the system message plus the most recent turns
    trimmed = [history[0]] + history[1:][-keep_last:]
    resp = client.chat.completions.create(model="uncensored", messages=trimmed, max_tokens=250)
    reply = resp.choices[0].message.content
    history.append({"role": "assistant", "content": reply})
    return reply, resp.usage.total_tokens

print(say("Open a scene in a ticket office at closing time.")[0])

يهم التقليم من حيث المال أكثر من نافذة السياق. يقبل النموذج ما مجموعه 100,000 رمز، ولكن إذا أعاد كل دور إرسال 30,000 رمز من السجل التاريخي، فإن كل طلب يكلف $0.0045 في الإدخال وحده (30,000 مضروبًا في $0.15 لكل مليون). تضيف خمسون من هذه الأدوار ما مجموعه $0.225 قبل حساب رمز إخراج واحد. الاحتفاظ بآخر اثني عشر دورًا، أو تلخيص الأدوار الأقدم في ملاحظة قصيرة، عادةً ما يحافظ على الجودة ويخفض الفاتورة بشكل حاد.

التزامن هو الجانب الآخر الذي يجب تصميمه. إذا كان برنامجك يخدم عدة مستخدمين في وقت واحد، فإن مفتاح التزامن بحجم حد مفتاحك (8 لمفتاح كامل، 2 لمفتاح تجريبي) يمنعك من تجاوز خطأ concurrency. تنتظر الطلبات التي تتجاوز الحد في طابورك الخاص بدلاً من الفشل، وهو أكثر ودًا من إعادة المحاولة على خطأ 429.

يُستحق الاختبار كلمة أيضًا. اكتب سكريبت صغيرًا واحدًا يستدعي واجهة API برمز seed ثابت، ودرجة حرارة منخفضة، وmax_tokens قصير، وشغله كلما غيّرت الموجّهات أو الإعدادات. يجعل البذرة ودرجة الحرارة المنخفضة المخرجات أكثر تكرارًا، مما يتيح لك مقارنة نسختين من الموجّه دون ضوضاء. اجعل هذه الفحوصات صغيرة؛ يمكن تشغيل اختبار يكلف جزءًا من سنت واحد في كل التزام دون أن يلاحظ أحد الفاتورة.

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

تعامل مع الحدود والأخطاء والرصيد

يسمح المفتاح الكامل بـ 8 طلبات متزامنة و300 طلب في الدقيقة. يسمح مفتاح التجربة بـ 2 و60. يؤدي تجاوز الأول إلى إرجاع HTTP 429 مع رمز الخطأ concurrency، ويؤدي تجاوز الثاني إلى إرجاع 429 مع rate_limited. يؤدي الحمل الزائد المؤقت أيضًا إلى إرجاع 429 مع رأس Retry-After: 5.

يعيد حزمة OpenAI محاولة بعض الأخطاء تلقائيًا، ويمكنك رفع ذلك باستخدام max_retries. بالنسبة لوظيفة الدفع، أضف حدك الخاص للعمل المتزامن أيضًا، بحيث تظل تحت حدّ التزامن بدلاً من الاعتماد على إعادة المحاولة.

Copyimport os
from openai import OpenAI, RateLimitError

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"], max_retries=3)

raw = client.chat.completions.with_raw_response.create(
    model="uncensored",
    messages=[{"role": "user", "content": "One sentence about trains."}],
    max_tokens=60,
)
print("balance:", raw.headers.get("X-Balance-USD"))
print("request id:", raw.headers.get("X-Request-Id"))
print(raw.parse().choices[0].message.content)

تُعد رؤوس الاستجابة X-Request-Id وX-Balance-USD مفيدة في السجلات. اذكر معرف الطلب عند التواصل مع الدعم. تُدرج التكاليف في صفحة الأسعار: $0.15 لكل مليون رمز مدخل و$0.50 لكل مليون رمز مخرج، مع شحنات من $20 إلى $500 ومكافآت بنسبة 5% و10% و15% عند $50 و$100 و$200. تُقبل البطاقات (Visa، Mastercard، Apple Pay، Google Pay) والعملات المشفرة (USDT على TRC20، USDC على Base). لا تُستخدم الموجّهات للتدريب. يُقصد بالنموذج للاستخدام القانوني للبالغين، ولا يُسمح مطلقاً بمحتوى جنسي يتضمن القاصرين.

المزيد من الأدلة

• API مجاني لـ SillyTavern: رصيد تجريبي وإعداد
• عنوان URL الأساسي لواجهة برمجة تطبيقات TTS: ما هو وما الذي يجب إدخاله
• قائمة مراجعة API Elevenlabs: خط أنابيب TTS بدون رقابة