الواجهة البرمجية لصوت ستوديو

البداية

1. أنشئ مفتاحاً من صفحة «مفاتيح API» في لوحة المستخدم. يظهر المفتاح مرة واحدة عند الإنشاء؛ انسخه إلى متغير بيئة أو خزنة أسرار، لا إلى الكود ولا إلى المتصفح.
2. أرسل المفتاح في ترويسة X-API-Key مع كل طلب.
3. العنوان الأساسي: https://api.sawtstudio.com/v1

الحروف تُخصم من محفظة حسابك نفسها، والحركات لا تُحسب. الملفات الناتجة لك: الاستعمال التجاري مسموح، ونكتب في بيانات كل ملف «صوت مولد بالذكاء الاصطناعي».

الواجهة متاحة للباقتين الاحترافية والمتقدمة. الأساسية والمجاني يحصلان على 403 plan_required.

أول طلب في سطر واحد:

curl \
  -X POST https://api.sawtstudio.com/v1/tts \
  -H "X-API-Key: $SAWT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"أهلاً بكم في صوت ستوديو.","voice":"يزن"}' \
  --output hello.mp3

المصادقة

• الترويسة: X-API-Key: ss_live_…
• المفتاح يخص حساباً واحداً ويخصم من محفظته. لكل حساب حتى 3 مفاتيح، تسمّيها وتعطّلها وتحذفها من اللوحة.
• نحفظ عندنا بصمة المفتاح فقط (SHA-256)؛ إن ضاع فاحذفه وأنشئ غيره. التعطيل فوري وقابل للعكس.
• عند التخفيض إلى باقة بلا واجهة برمجية تبقى المفاتيح تعمل حتى نهاية الفترة المدفوعة ثم تُعطّل، ونرسل تنبيهاً قبلها بثلاثة أيام.
• كل الطلبات عبر HTTPS فقط.

توليد الصوت

POST /v1/tts

يرجع الملف الصوتي ثنائياً (audio/mpeg أو audio/wav) مع ترويسات الرصيد. الجسم application/json:

الرد عند النجاح: 200 والجسم هو الملف. الترويسات في القسم «ترويسات الرصيد».

النصوص فوق 5,000 حرف تُقسم من طرفك على طلبات متتابعة عند حدود الجمل؛ ضع ‖ في بداية كل جزء إن أردت وقفة بين الأجزاء عند الدمج.

أمثلة

curl -X POST https://api.sawtstudio.com/v1/tts \
  -H "X-API-Key: $SAWT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "أطلقنا اليوم مجموعة لافندر من عطور الورد الجديدة.",
    "voice": "سلطان",
    "dialect": "sa-najdi",
    "style": "ad",
    "emotion": "friendly",
    "speed": 1.0,
    "format": "mp3",
    "check": true,
    "pauses": true
  }' \
  --output ad.mp3 --dump-header headers.txt

import fs from "node:fs";

const res = await fetch("https://api.sawtstudio.com/v1/tts", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.SAWT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "أطلقنا اليوم مجموعة لافندر من عطور الورد الجديدة.",
    voice: "سلطان",
    dialect: "sa-najdi",
    style: "ad",
    emotion: "friendly",
    format: "mp3",
    check: true,
  }),
});

if (!res.ok) {
  const err = await res.json();
  throw new Error(`${err.code}: ${err.message_ar}`);
}

console.log(res.headers.get("X-Chars-Billed"), res.headers.get("X-Balance-Chars"));
await fs.promises.writeFile("ad.mp3", Buffer.from(await res.arrayBuffer()));

import os
import requests

r = requests.post(
    "https://api.sawtstudio.com/v1/tts",
    headers={"X-API-Key": os.environ["SAWT_API_KEY"]},
    json={
        "text": "أطلقنا اليوم مجموعة لافندر من عطور الورد الجديدة.",
        "voice": "سلطان",
        "dialect": "sa-najdi",
        "style": "ad",
        "emotion": "friendly",
        "format": "mp3",
        "check": True,
    },
    timeout=60,
)
if r.status_code != 200:
    err = r.json()
    raise SystemExit(f"{err['code']}: {err['message_ar']}")

print(r.headers["X-Chars-Billed"], r.headers["X-Balance-Chars"])
with open("ad.mp3", "wb") as f:
    f.write(r.content)

ترويسات الرصيد في الرد

الخصم يحدث مرة واحدة عند نجاح التوليد. الفشل بأي رمز غير 200 لا يخصم شيئاً.

الأصوات واللهجات

GET /v1/voices

القائمة بحالة كل صوت: verified (مثبت) أو pending (قيد التثبيت، قابل للتوليد). الأصوات «قريباً» لا تظهر. لا يخصم حروفاً.

{
  "voices": [
    {
      "id": "sa-najdi-sultan",
      "name": "سلطان",
      "dialect": "sa-najdi",
      "dialect_label": "نجدية — السعودية",
      "gender": "male",
      "age": "30-40",
      "status": "pending",
      "best_for": ["ad", "narration"],
      "sample_url": "https://sawtstudio.com/samples/sa-najdi-sultan.mp3"
    },
    {
      "id": "fusha-yazan",
      "name": "يزن",
      "dialect": "fusha",
      "dialect_label": "فصحى",
      "gender": "male",
      "age": "30-40",
      "status": "pending",
      "best_for": ["ad", "narration"],
      "sample_url": "https://sawtstudio.com/samples/fusha-yazan.mp3"
    }
  ],
  "dialects": [
    { "id": "sa-najdi", "label": "نجدية — السعودية", "status": "pending" },
    { "id": "fusha", "label": "فصحى", "status": "pending" }
  ]
}

قيم best_for: ad إعلان · narration سرد · teaching تعليم · phone رد هاتفي · news إخباري · documentary وثائقي.

الرصيد

GET /v1/balance

{
  "plan": "pro",
  "chars_remaining": 81250,
  "pack_chars": 12500,
  "scripts_remaining": 94,
  "period_end": "2026-11-01T00:00:00Z",
  "daily_cap_remaining": 18870
}

• chars_remaining حصة الباقة المتبقية هذا الشهر · pack_chars رصيد حزم الشحن ولا ينتهي · scripts_remaining نصوص القوالب (لا تُستهلك من الواجهة البرمجية في هذا الإصدار) · period_end موعد التجديد · daily_cap_remaining المتبقي من السقف اليومي.
• لا يخصم حروفاً.

المدقق وحده

POST /v1/check

لمن يريد مراجعة الاقتراحات قبل النطق. الجسم: text (حتى 5,000 حرف) · dialect · level (fusha · white · local). الرد قائمة تعديلات لا نصاً كاملاً، فلا يتغير شيء خارجها. لا يخصم حروفاً.

{
  "edits": [
    { "start": 20, "end": 26, "original": "لافندر", "suggested": "لَافِنْدَر", "kind": "tashkeel", "reason": "أعجمية" },
    { "start": 77, "end": 80, "original": "15%", "suggested": "خمسة عشر بالمئة", "kind": "number", "reason": "نسبة منطوقة" }
  ]
}

• kind من خمس قيم: tashkeel تشكيل · lexicon مفردة لهجة من حزمة اللهجة · number رقم أو تاريخ أو مبلغ منطوق · abbr اختصار لاتيني منطوق · pause وقفة مقترحة ‖.
• start وend مواضع بالحروف في النص الأصلي كما أرسلته. طبّق التعديلات من الآخر إلى الأول حتى لا تتزحزح المواضع.
• قاموس نطق حسابك وأسماء البروفايل تُطبق تلقائياً وتظهر بوسم reason: "من قاموسك".

الأخطاء

كل خطأ JSON بالشكل { "code", "message_ar", "message_en" }. لا نصوص ولا رموز من أي طرف ثالث.

مثال:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "code": "rate_limited",
  "message_ar": "تجاوزت 30 طلباً في الدقيقة؛ أعد المحاولة بعد 12 ثانية.",
  "message_en": "Rate limit of 30 requests per minute exceeded; retry in 12 seconds."
}

message_ar تصلح للعرض لمستخدمك العربي كما هي؛ message_en للسجلات.

الحدود

• الملفات تُرجع في الرد ولا تُحفظ عندنا للواجهة البرمجية؛ احفظها عندك.
• الطلبات تُسجل في «مشاريعي» بعنوان من أول ست كلمات، كطلبات الاستوديو.
• عند 429 انتظر ما تقوله Retry-After ثم أعد المحاولة؛ لا تكرر فوراً.

الاستعمال التجاري مسموح

الملفات التي تولدها ملك لك ضمن شروط الاستخدام: يوتيوب، إعلانات، مساقات، كتب صوتية، ردود هاتفية. نكتب في بيانات كل ملف «صوت ستوديو» و«صوت مولد بالذكاء الاصطناعي»، وننصح بالإفصاح عنه حيث يُعرض الصوت للجمهور، ويُلزم حيث يفرضه القانون.

المحتوى المحظور (انتحال أشخاص حقيقيين، التضليل عن المصدر، الكراهية، الجنسي، القاصرون، الاحتيال) يُرفض برمز 400 وقد يُعلق الحساب بعد إنذارين.

ملاحظات سريعة

• الحرف وحدة الحساب، والحركات لا تُحسب؛ ما يضيفه المدقق من تشكيل أو أرقام منطوقة لا يُخصم.
• اكتب الأسماء والمصطلحات الأعجمية مرة واحدة في قاموس النطق من اللوحة، وتُطبق على كل طلب بـcheck: true.
• السرعة بعد التوليد لا تغير الخصم؛ الأسلوب والانفعال لا يغيرانه أيضاً.
• الإصدار v1 ثابت؛ أي تغيير كاسر يأتي في إصدار جديد مع مهلة.

الدعم: support@sawtstudio.com · أنشئ مفتاحك من لوحة المستخدم.

© مجاز للحلول التسويقية. جميع الحقوق محفوظة. الأصوات مولدة بالذكاء الاصطناعي.