مرجع API · نسخه‌ی ۱

مستندات API آلفا

آلفا ارزان‌ترین ارائه‌دهنده‌ی API هوش مصنوعی در تمام اینترنت است و هر 12 مدل از یک مسیر واحد صدا زده می‌شوند. یک درخواست POST می‌فرستید، یک شناسه می‌گیرید، و تا آماده شدن خروجی وضعیت را می‌پرسید — و در این فاصله می‌توانید درصد پیشرفت واقعی را هم بگیرید. تنها استثنا چت‌بات است که پاسخش در همان درخواست برمی‌گردد. تمام پاسخ‌ها JSON هستند.

BASEhttps://api.appalpha.ir/v1

سه چیز که خوب است از ابتدا بدانید.
یک: پردازش‌ها ناهم‌زمان‌اند و همیشه باید وضعیت را پرسید — تنها استثنا چت‌بات است که پاسخش در همان درخواست برمی‌گردد.
دو: هزینه هنگام ثبت فقط رزرو می‌شود و تنها پس از تحویل خروجی سالم کسر می‌شود؛ اگر خروجی تحویل نشود، هیچ مبلغی کم نمی‌شود.
سه: متن فارسی را مستقیم بفرستید؛ ترجمه‌ی داخلی خودکار انجام می‌شود.

احراز هویت

هر درخواست باید کلید شما را در هدر Authorization با پیشوند Bearer داشته باشد. کلیدها از پنل کاربری ساخته و لغو می‌شوند.

header

Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxx

اگر کتابخانه‌ی شما هدر سفارشی راحت‌تر است، X-API-Key هم پذیرفته می‌شود.

کلید را سمت مرورگر نگذارید. هر کسی کلید را داشته باشد می‌تواند از اعتبار شما خرج کند. درخواست‌ها را از سرور خودتان بفرستید و کلید را در متغیر محیطی نگه دارید. اگر کلیدی لو رفت، از پنل لغوش کنید؛ بقیه‌ی کلیدها بدون وقفه کار می‌کنند.

اولین درخواست

این نمونه یک تصویر می‌سازد و تا آماده شدن منتظر می‌ماند.

python

import os, time, requests

BASE = "https://api.appalpha.ir/v1"
H = {"Authorization": f"Bearer {os.environ['ALPHA_KEY']}"}

job = requests.post(f"{BASE}/generations", headers=H, json={
    "model": "flux-dev",
    "prompt": "یک باغ ایرانی در بهار، نور طلایی عصر",
    "width": 1024,
    "height": 1024,
}).json()

# اگر درخواست پذیرفته نشود، به‌جای شناسه یک پیام فارسی برمی‌گردد
if "error" in job:
    raise SystemExit("خطا: " + job["error"]["message"])

print(job["id"], job["cost_toman"])

while True:
    time.sleep(3)
    out = requests.get(f"{BASE}/generations/{job['id']}", headers=H).json()
    if out["status"] != "processing":
        break

if out["status"] == "ready":
    print(out["output"]["url"])
else:
    print("خطا:", out["error"]["message"])

ساخت درخواست

POST/v1/generations

فیلد model همیشه لازم است. بقیه‌ی فیلدها به مدل انتخابی بستگی دارند و در فهرست مدل‌ها برای هر کدام جداگانه آمده است.

فیلد	نوع	توضیح
`model`	string	شناسه‌ی مدل، مثلاً `flux-dev`. الزامی.
`prompt`	string	توضیح خروجی. فارسی یا انگلیسی.
`image`	string	آدرس اینترنتی یا base64. برای مدل‌های تصویر به تصویر و ویدیو.
`audio`	string	آدرس یا base64 فایل صوتی.
`width` / `height`	int	ابعاد خروجی؛ پیش‌فرض ۱۰۲۴ در ۱۰۲۴.
`stem`	string	`vocal` یا `background`، فقط برای `vocal-separate`.

پاسخ — کد ۲۰۲

json

{
  "id": "9f2c4b81-7d3e-4a11-9c02-5f8b1d2e6a44",
  "model": "flux-dev",
  "status": "processing",
  "price_toman": 500,
  "cost_toman": 0,
  "charged": false,
  "held_toman": 500,
  "balance_toman": 5000,
  "available_toman": 4500,
  "output": null,
  "poll_url": "https://api.appalpha.ir/v1/generations/9f2c4b81-…",
  "created_at": 1755100000,
  "expires_at": 1755100900,
  "max_processing_seconds": 900
}

در این لحظه هیچ مبلغی از موجودی کسر نشده؛ قیمت فقط رزرو شده است (charged: false). مبلغ فقط وقتی کسر می‌شود که خروجی سالم آماده و تحویل شود. expires_at سقف زمانی این درخواست است؛ اگر تا آن لحظه خروجی سالم آماده نشود، درخواست خودکار failed می‌شود و رزرو بدون هیچ کسری آزاد می‌شود.

گرفتن خروجی

GET/v1/generations/{id}

هر سه تا پنج ثانیه یک بار بپرسید. پرسیدن وضعیت کاملاً رایگان است و هر چند بار که بپرسید هیچ هزینه‌ای ندارد. سه حالت ممکن است برگردد:

وضعیت	یعنی	کار بعدی
`processing`	هنوز در حال ساخت است. هیچ مبلغی کسر نشده.	چند ثانیه صبر و دوباره بپرسید. `seconds_left` زمان باقی‌مانده تا سقف را می‌گوید.
`ready`	خروجی آماده و فایلش بررسی شده است. فقط در این حالت مبلغ کسر می‌شود.	فایل را از `output.url` بردارید.
`failed`	پردازش شکست خورد، از سقف زمانی گذشت یا فایل خالی/ناقص بود.	هیچ مبلغی کسر نشده؛ می‌توانید دوباره تلاش کنید.

json — ready

{
  "id": "9f2c4b81-…",
  "model": "flux-dev",
  "status": "ready",
  "price_toman": 500,
  "cost_toman": 500,
  "charged": true,
  "output": {
    "url": "https://…/static/images/9f2c4b81-….png",
    "type": "image"
  }
}

تضمین «بدون تحویل، بدون هزینه»

هنگام ثبت درخواست، قیمت فقط رزرو می‌شود و از موجودی کم نمی‌شود.
وقتی موتور پردازش خروجی را آماده اعلام کرد، پیش از هر کسری خودِ فایل بررسی می‌شود: باید واقعاً دانلودشدنی باشد، خالی یا ناقص نباشد و صفحه‌ی خطا نباشد. فقط بعد از این بررسی وضعیت ready می‌شود و مبلغ کسر می‌شود.
هیچ درخواستی بی‌پایان در processing نمی‌ماند. سقف زمانی هر نوع خروجی: ویدیو ۲۵ دقیقه، تصویر و صدا ۱۵ دقیقه. بعد از آن درخواست خودکار failed می‌شود و رزرو آزاد می‌شود. زمان عادی ساخت ویدیوی Wan 2.2 معمولاً چند دقیقه است و در ساعات شلوغ بیشتر می‌شود.
این بررسی روی سرور ما و در پس‌زمینه هم انجام می‌شود؛ حتی اگر برنامه‌ی شما دیگر هرگز وضعیت را نپرسد، رزرو آزاد یا تسویه می‌شود.
پرسیدن وضعیت (GET) و نوار پیشرفت هیچ هزینه‌ای ندارند.

فایل خروجی را نزد خودتان نگه دارید. آدرس خروجی برای دانلود فوری است، نه بایگانی دائمی. بلافاصله بعد از آماده شدن، فایل را روی فضای ذخیره‌سازی خودتان کپی کنید.

وقتی وضعیت processing است، همین پاسخ یک کلید progress هم دارد که درصد واقعی ساخت را نشان می‌دهد. توضیح کامل و مسیر سبک‌ترش را در بخش نوار پیشرفت ببینید.

نوار پیشرفت واقعی

GET/v1/generations/{id}/progress

همان چیزی که کاربران خودتان بیشتر از هر چیز می‌خواهند: بدانند ساخت چقدر مانده. این عدد تخمینی نیست — خودِ مدل حین اجرا مرحله‌ی جاری را گزارش می‌کند و ما فقط آن را به شما می‌رسانیم. یعنی وقتی می‌نویسد ۶۰ درصد، واقعاً ۶۰ درصد مراحل تمام شده است.

json

{
  "id": "9f2c4b81-…",
  "status": "processing",
  "percent": 62,
  "progress": { "percent": 62, "step": 31, "total": 50 },
  "supported": true
}

فیلد	یعنی
`percent`	عدد صفر تا ۹۹. اگر هنوز چیزی گزارش نشده باشد `null` است.
`progress.step`	مرحله‌ی جاری مدل. برای نوشتن «مرحله ۳۱ از ۵۰».
`progress.total`	تعداد کل مراحل. بعضی مدل‌ها فقط درصد می‌دهند و این دو فیلد را ندارند.
`supported`	آیا این مدل اصلاً پیشرفت گزارش می‌کند یا نه.

چرا یک مسیر جداگانه؟ مسیر /v1/generations/{id} هر بار با موتور پردازش حرف می‌زند، وضعیت را ثبت می‌کند و در صورت شکست بازگشت وجه می‌زند؛ صدا زدنش هر ثانیه درست نیست. این مسیر فقط یک عدد می‌خواند و سبک است. الگوی پیشنهادی: هر یک ثانیه این مسیر برای حرکت نرم نوار، و هر سه تا پنج ثانیه مسیر اصلی برای دیدن اینکه خروجی آماده شده یا نه.

نمونه‌ی کامل — نوار پیشرفت برای کاربر شما

python

import os, time, requests

BASE = "https://api.appalpha.ir/v1"
H = {"Authorization": f"Bearer {os.environ['ALPHA_KEY']}"}

job = requests.post(f"{BASE}/generations", headers=H, json={
    "model": "video-wan22",
    "image": "https://example.com/photo.jpg",
    "prompt": "دوربین آرام به سوژه نزدیک می‌شود",
}).json()

jid = job["id"]
last_check = 0

while True:
    # هر ثانیه: فقط درصد
    p = requests.get(f"{BASE}/generations/{jid}/progress", headers=H).json()
    if p["percent"] is not None:
        print(f"\rدر حال ساخت… {p['percent']}%", end="")

    # هر چهار ثانیه: وضعیت واقعی
    if time.time() - last_check > 4:
        last_check = time.time()
        out = requests.get(f"{BASE}/generations/{jid}", headers=H).json()
        if out["status"] != "processing":
            break

    time.sleep(1)

print()
print(out["output"]["url"] if out["status"] == "ready" else out["error"]["message"])

اگر ترجیح می‌دهید فقط یک مسیر را صدا بزنید، لازم نیست کاری کنید: پاسخ /v1/generations/{id} هم وقتی وضعیت processing است همان درصد را زیر کلید progress دارد. مسیر جداگانه فقط برای وقتی است که نوار را نرم‌تر می‌خواهید.

کدام مدل‌ها پیشرفت می‌دهند؟

همه‌ی مدل‌ها این عدد را نمی‌سازند و ما هم عدد ساختگی جای خالی‌اش نمی‌گذاریم. مدل‌هایی که پیشرفت واقعی گزارش می‌کنند:

flux-dev — فلاکس Dev
z-image — ز ایمیج (Z-Image)
cartoon-create — ساخت تصویر کارتونی
qwen-image-edit — ویرایش تصویر
video-wan22 — ویدیو Wan 2.2 (۱۴B)

برای بقیه، percent همیشه null و supported برابر false برمی‌گردد. در آن حالت به‌جای نوار درصدی، یک نوار رفت‌وبرگشتی (بی‌نهایت) نشان بدهید — بهتر از نشان دادن عددی است که واقعی نیست. نکته‌ی دیگر: در چند ثانیه‌ی اول هر ساخت، حتی مدل‌های پشتیبانی‌شده هم null می‌دهند، چون مدل هنوز پشت صف است و شروع نکرده. این خطا نیست.

چت‌بات — آیا چت

POST/v1/chat

تنها بخش هم‌زمان API: درخواست می‌فرستید و متن پاسخ در همان جواب برمی‌گردد. هیچ شناسه‌ای، هیچ حلقه‌ی انتظاری. هر پیام سی تومان. اگر بخواهید، پاسخ کلمه‌به‌کلمه استریم هم می‌شود تا کاربرتان ببیند جواب دارد نوشته می‌شود.

واحد محاسبه «پیام» است، نه توکن. طول سؤال هیچ اثری روی مبلغ ندارد و طول جواب هم همین‌طور. فرستادن تاریخچه‌ی مکالمه هم هزینه‌ی جداگانه ندارد: ورودی و خروجی روی هم یک پیام حساب می‌شوند و همان سی تومان است. یعنی صورتحساب شما دقیقاً برابر است با «تعداد پیام‌های کاربران × ۳۰ تومان» و از قبل قابل پیش‌بینی است.

فیلد	نوع	توضیح
`model`	string	`aya-chat`. اگر نفرستید هم همین انتخاب می‌شود. برای تحلیل تصویر، `chat-vision`.
`messages`	array	تاریخچه‌ی گفتگو. هر عضو `{"role": "user"\|"assistant", "content": "…"}`. آخرین عضو باید پیام تازه‌ی کاربر باشد.
`message`	string	جایگزین ساده‌ی `messages` برای سؤال‌های تک‌مرحله‌ای بدون حافظه.
`system`	string	اختیاری. شخصیت و قوانین چت‌بات؛ در هر درخواست بفرستیدش.
`stream`	bool	اگر `true` باشد، پاسخ کلمه‌به‌کلمه و به شکل SSE فرستاده می‌شود. پیش‌فرض `false`.

پاسخ — کد ۲۰۰

json

{
  "id": "chat_7c1e…",
  "model": "aya-chat",
  "status": "ready",
  "reply": "سفارش ۱۰۴۲ امروز از انبار خارج شده و تا فردا به دستتان می‌رسد.",
  "output": { "type": "text", "text": "سفارش ۱۰۴۲ امروز…" },
  "cost_toman": 30,
  "balance_toman": 118970,
  "created_at": 1755100000
}

استریم — پاسخ کلمه‌به‌کلمه

اگر stream را true بگذارید، پاسخ به‌جای اینکه یک‌جا و در پایان برسد، همان‌طور که تولید می‌شود تکه‌تکه فرستاده می‌شود؛ دقیقاً همان چیزی که در چت‌بات‌های حرفه‌ای می‌بینید. برای کاربر شما تفاوتش زیاد است: به‌جای چند ثانیه نگاه کردن به یک صفحه‌ی ساکن، از همان لحظه‌ی اول می‌بیند که جواب دارد نوشته می‌شود.

قالب خروجی Server-Sent Events است: هر رویداد یک خط data: با یک شیء JSON، و بین رویدادها یک خط خالی. سه نوع رویداد وجود دارد:

type	یعنی
`open`	اتصال برقرار شد. هیچ محتوایی ندارد و می‌توانید نادیده‌اش بگیرید؛ فقط تضمین می‌کند جریان از همان لحظه‌ی اول باز شده است.
`delta`	یک تکه‌ی تازه از متن، در کلید `text`. تکه‌ها را پشت سر هم بچسبانید. این فقط بخش تازه است، نه کل متن تا اینجا.
`done`	پایان موفق. همان بدنه‌ی پاسخ عادی است: `reply` کامل، `cost_toman` و `balance_toman`.
`error`	چیزی خراب شد. در این حالت هیچ مبلغی از شما کسر نشده (`charged: false`).

در آخر یک data: [DONE] فرستاده می‌شود تا بدانید جریان تمام شده است.

خط‌هایی که با : شروع می‌شوند را نادیده بگیرید. این‌ها کامنت استاندارد SSE هستند و ما هر چند ثانیه یکی می‌فرستیم تا وقتی مدل هنوز مشغول فکر کردن است، اتصال زنده بماند و هیچ پراکسی‌ای وسط کار آن را نبُرد. محتوایی ندارند. اگر مثل نمونه‌های همین صفحه فقط خط‌های شروع‌شده با data: را پردازش کنید، خودکار رد می‌شوند.

python — استریم

import os, json, requests

BASE = "https://api.appalpha.ir/v1"
H = {"Authorization": f"Bearer {os.environ['ALPHA_KEY']}"}

with requests.post(f"{BASE}/chat", headers=H, stream=True, json={
    "model": "aya-chat",
    "messages": [{"role": "user", "content": "یک داستان کوتاه بگو"}],
    "stream": True,
}) as r:
    reply = ""
    for line in r.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data:"):
            continue
        raw = line[5:].strip()
        if raw == "[DONE]":
            break
        ev = json.loads(raw)
        if ev["type"] == "delta":
            reply += ev["text"]
            print(ev["text"], end="", flush=True)   # چاپ زنده
        elif ev["type"] == "done":
            print("\n هزینه:", ev["cost_toman"], "تومان")
        elif ev["type"] == "error":
            print("\n خطا:", ev["message"])

javascript — استریم در مرورگر

const res = await fetch("https://api.appalpha.ir/v1/chat", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "aya-chat",
    messages: history,
    stream: true,
  }),
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "", reply = "";

while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });

  // یک رویداد ممکن است بین دو تکه‌ی شبکه نصف شود، پس فقط
  // رویدادهای کاملِ جداشده با خط خالی پردازش می‌شوند.
  let cut;
  while ((cut = buffer.indexOf("\n\n")) !== -1) {
    const chunk = buffer.slice(0, cut).trim();
    buffer = buffer.slice(cut + 2);
    if (!chunk.startsWith("data:")) continue;

    const raw = chunk.slice(5).trim();
    if (raw === "[DONE]") continue;

    const ev = JSON.parse(raw);
    if (ev.type === "delta") {
      reply += ev.text;
      bubble.textContent = reply;      // نمایش زنده
    } else if (ev.type === "done") {
      console.log("هزینه:", ev.cost_toman);
    } else if (ev.type === "error") {
      console.error(ev.message);
    }
  }
}

کلید را در مرورگر نگذارید. نمونه‌ی بالا برای نشان دادن روش خواندن استریم است. در محصول واقعی، این درخواست را از سرور خودتان بفرستید و همان استریم را به مرورگر کاربر پاس بدهید؛ وگرنه هر بازدیدکننده‌ای کلید شما را می‌بیند.

اگر استریم برقرار نشد، درخواست شکست نمی‌خورد. در شرایطی که اتصال استریمی ممکن نباشد، سرور بی‌صدا به حالت عادی برمی‌گردد و کل پاسخ را در یک رویداد delta می‌فرستد. یعنی بدترین حالت «استریم نشدن» است، نه «کار نکردن» — کد شما لازم نیست برای این حالت چیز جداگانه‌ای بنویسد.

حافظه‌ی مکالمه چطور کار می‌کند

سرور مکالمه‌ی شما را نگه نمی‌دارد. تاریخچه را خودتان نگه می‌دارید و هر بار کامل می‌فرستید؛ سرور آن را برای مدل بازسازی می‌کند و پاسخ را با در نظر گرفتن کل گفتگو می‌دهد. الگویش ساده است: پاسخ هر مرحله را با نقش assistant به آرایه اضافه کنید و در درخواست بعدی همان آرایه را بفرستید.

python — گفتگوی ادامه‌دار

import os, requests

BASE = "https://api.appalpha.ir/v1"
H = {"Authorization": f"Bearer {os.environ['ALPHA_KEY']}"}

SYSTEM = "تو پشتیبان فروشگاه لوازم خانگی هستی و فقط درباره‌ی محصولات همین فروشگاه جواب می‌دهی."
history = []

def ask(text):
    history.append({"role": "user", "content": text})
    r = requests.post(f"{BASE}/chat", headers=H, json={
        "model": "aya-chat",
        "system": SYSTEM,
        "messages": history,
    }).json()
    if "error" in r:                      # کلید، اعتبار، مدل اشتباه و…
        raise SystemExit("خطا: " + r["error"]["message"])
    history.append({"role": "assistant", "content": r["reply"]})
    return r["reply"]

print(ask("سلام، یخچال ساید بای ساید دارید؟"))
print(ask("همان که گفتی چند است؟"))   # می‌فهمد «همان» یعنی چه

حداکثر شانزده پیام آخر استفاده می‌شود؛ اگر آرایه‌ی بلندتری بفرستید، قدیمی‌ترها خودکار کنار گذاشته می‌شوند تا مکالمه‌های طولانی هم بدون خطا ادامه پیدا کنند. لازم نیست خودتان تاریخچه را کوتاه کنید.

متن گفتگو نگهداری نمی‌شود. پاسخ فقط یک بار و در همان درخواست به شما داده می‌شود؛ روی سرور ما نمی‌ماند. برای همین GET /v1/generations/{id} روی یک شناسه‌ی چت، وضعیت ready را نشان می‌دهد ولی متن را برنمی‌گرداند. اگر تاریخچه برای محصولتان لازم است، همان‌جا ذخیره‌اش کنید.

اگر تمام محصولتان را دور /v1/generations ساخته‌اید، لازم نیست چیزی را بازنویسی کنید: همان مسیر هم مدل aya-chat را می‌پذیرد و به‌جای شناسه، مستقیم پاسخ آماده را با وضعیت ready برمی‌گرداند.

چت بات با تحلیل تصویر

POST/v1/chat

همان چت‌بات، با یک توانایی اضافه: عکس را می‌بیند. مسیر، قالب پاسخ، استریم و قیمت هیچ فرقی با چت‌بات متنی ندارد؛ فقط مقدار model را chat-vision بگذارید و تصویر را در فیلد image بفرستید. هر پیام سی تومان، با تصویر یا بدون تصویر.

فیلد	نوع	توضیح
`model`	string	`chat-vision`
`image`	string	اختیاری. تصویری که باید تحلیل شود، به یکی از سه شکل: آدرس اینترنتی (`https://…`)، data URI (`data:image/jpeg;base64,…`) یا base64 خام. فرمت JPG، PNG یا WebP و حداکثر ۸ مگابایت.
`message`	string	سؤال یا دستور شما درباره‌ی تصویر. اگر تصویر را بدون متن بفرستید، مدل خودش آن را با جزئیات توضیح می‌دهد.
`messages`	array	تاریخچه‌ی گفتگو، دقیقاً مثل چت‌بات متنی.
`system`	string	اختیاری. شخصیت و قوانین چت‌بات.
`stream`	bool	اگر `true` باشد، پاسخ کلمه‌به‌کلمه می‌آید؛ با همان رویدادهای `delta`، `done` و `error`.

python

import base64, requests

# تصویر با آدرس اینترنتی
r = requests.post(f"{BASE}/chat", headers=H, json={
    "model": "chat-vision",
    "message": "در این تصویر چه می‌بینی؟",
    "image": "https://example.com/photo.jpg",
}).json()
print(r["reply"])

# یا فایل روی دیسک، به شکل base64
with open("photo.jpg", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode()

r = requests.post(f"{BASE}/chat", headers=H, json={
    "model": "chat-vision",
    "message": "متن داخل این تصویر را بنویس.",
    "image": image_b64,
}).json()
print(r["reply"])

در هر درخواست فقط یک تصویر دیده می‌شود: تصویرِ همین پیام. حافظه‌ی مکالمه متنی است و تصویر پیام‌های قبلی داخلش نمی‌ماند. اگر کاربر درباره‌ی همان عکس سؤال دوم پرسید، image را دوباره در همان درخواست بفرستید. اگر image را نفرستید، مدل مثل یک چت‌بات معمولی جواب متنی می‌دهد؛ پس می‌توانید کل گفتگو را روی همین یک مدل نگه دارید.

اگر پاسخی تحویل نشود — تصویر خوانده نشود، سرویس شلوغ باشد یا جواب خالی بیاید — هیچ مبلغی کسر نمی‌شود و پیام خطا علت را می‌گوید.

آلفا TTS — تبدیل متن به صدا

POST/v1/generations

متن را با یکی از 30 گوینده می‌خواند و یک فایل MP3 تحویل می‌دهد. شناسه‌ی مدل alpha-tts است و مثل بقیه‌ی مدل‌ها ناهم‌زمان کار می‌کند: شناسه می‌گیرید و تا آماده شدن فایل وضعیت را می‌پرسید. تنها تفاوتش با بقیه این است که قیمتش ثابت نیست و از روی طول متن حساب می‌شود.

همه‌ی زبان‌های دنیا. لازم نیست زبان را جایی اعلام کنید؛ از روی خودِ متن تشخیص داده می‌شود. فارسی، انگلیسی، عربی، ترکی، فرانسه، آلمانی، اسپانیایی، روسی، چینی و بقیه همگی با همین گویندگان خوانده می‌شوند — یعنی یک گوینده‌ی ثابت می‌تواند در کل محصول شما به چند زبان صحبت کند. متن دوزبانه هم مشکلی ندارد.

فیلدهای درخواست

فیلد	نوع	لازم	توضیح
`model`	string	بله	`alpha-tts`
`text`	string	بله	متنی که خوانده می‌شود؛ به هر زبانی. حداکثر 2500 نویسه. همین فیلد مبنای قیمت است.
`speaker`	string	—	شناسه‌ی فینگلیش گوینده؛ جدول پایین. پیش‌فرض `shahab`.
`tone`	string	—	توصیف لحن و احساس، به فارسی ساده — مثلاً «آرام و نجواگونه» یا «رسمی و خبری». این متن خوانده نمی‌شود و در شمارش نویسه‌ها و قیمت هم نمی‌آید.

لحن و احساس — آکولاد `{ }`

لحن با آکولاد مشخص می‌شود و همیشه در انتهای متن می‌آید. هر چه داخل آکولاد بنویسید خوانده نمی‌شود؛ فقط به گوینده می‌گوید متن را چطور ادا کند.

نمونه

وای تبدیل متن شما به صدایی که همدلی و درک را برمی‌انگیزد.{با تعجب و هیجان زیاد}

هی، گوش کن! یه راز دارم که فقط به تو می‌گم. {با لحنی مرموز، شیطنت‌آمیز و نجواگونه}

دو راه برای گفتنش هست و هر دو به یک چیز می‌رسند:

راه	چطور	کِی بهتر است
داخل خودِ متن	آکولاد را در انتهای `text` بگذارید.	وقتی متن را خودتان می‌نویسید و لحن هر جمله فرق می‌کند.
فیلد `tone`	همان توصیف را بدون آکولاد بفرستید؛ آکولاد خودکار به انتهای متن اضافه می‌شود.	وقتی متن از جای دیگری می‌آید و نمی‌خواهید دستکاریش کنید، یا یک لحن ثابت را روی چند تکه اعمال می‌کنید.

json — همان نتیجه، با فیلد جدا

{
  "model":   "alpha-tts",
  "text":    "هی، گوش کن! یه راز دارم که فقط به تو می‌گم.",
  "speaker": "pouya",
  "tone":    "با لحنی مرموز، شیطنت‌آمیز و نجواگونه"
}

اگر هر دو را بفرستید، آکولادی که خودتان داخل متن گذاشته‌اید دست‌نخورده می‌ماند.

نمونه‌های آزمایش‌شده

کاربرد	توصیف لحن
گویندگی خبر	`{با لحنی رسمی، خنثی و خبری، مانند مجری بخش خبری شبانگاهی}`
کتاب صوتی	`{با لحنی آرام، ملایم و دلنشین، مانند گوینده‌ی کتاب صوتی}`
تعجب و شوک	`{با صدایی مملو از تعجب و ناباوری شدید}`
فرماندهی	`{با لحنی قاطع، محکم و فرماندهانه}`
انگیزشی	`{با لحنی انگیزشی و الهام‌بخش، مانند مربی که روحیه می‌دهد}`
راز گفتن	`{با لحنی مرموز، شیطنت‌آمیز و نجواگونه}`
خنده وسط جمله	`{خنده}` یا `{خنده زیاد}`

هرچه توصیف تصویری‌تر، نتیجه نزدیک‌تر. «با لحنی مرموز و نجواگونه، انگار رازی را در گوش کسی می‌گوید» خیلی بهتر از «مرموز» جواب می‌دهد. توصیف را به فارسی ساده بنویسید — لازم نیست انگلیسی باشد.

یک نکته درباره‌ی قیمت. اگر از فیلد tone استفاده کنید، محتوای آن در شمارش نویسه‌ها نمی‌آید و روی مبلغ اثری ندارد. اما اگر آکولاد را داخل خودِ text بگذارید، چون بخشی از همان رشته است شمرده می‌شود. برای متن‌های نزدیک به سقف 2500 نویسه، فیلد tone انتخاب بهتری است.

قیمت — بر اساس طول متن

سه پله بیشتر ندارد و هر کدام «دانه‌ای» است: هر درخواست یک فایل صوتی و یک بار همین مبلغ. شمارش روی متن پس از حذف فاصله‌های ابتدا و انتها انجام می‌شود و فاصله‌های میان کلمه‌ها هم مثل بقیه‌ی نویسه‌ها شمرده می‌شوند.

طول متن	قیمت هر درخواست
تا ۱۰۰ نویسه	500 تومان
۱۰۱ تا ۶۰۰ نویسه	1000 تومان
۶۰۱ تا ۲٬۵۰۰ نویسه	3000 تومان

مبلغی که واقعاً کسر شده همیشه در پاسخ زیر cost_toman دیده می‌شود و کنارش chars تعداد نویسه‌ها را می‌گوید؛ پس لازم نیست خودتان پله را حدس بزنید. اگر ساخت به هر دلیلی شکست بخورد، هیچ مبلغی از کیف پول کسر نمی‌شود.

سقف هر درخواست 2500 نویسه است. متن بلندتر پیش از هر کسری از اعتبار با کد text_too_long رد می‌شود و در همان پاسخ می‌بینید متن شما چند نویسه بوده و سقف چند است:

json — کد ۴۰۰

{
  "error": {
    "message": "متن شما ۳٬۱۲۰ نویسه است و از سقف مجاز عبور کرده. سقف هر درخواست ۲٬۵۰۰ نویسه است…",
    "code": "text_too_long",
    "chars": 3120,
    "max_chars": 2500
  }
}

برای متن‌های بلندتر، خودتان متن را از روی پاراگراف یا نقطه به تکه‌های زیر سقف بشکنید و برای هر تکه یک درخواست بفرستید؛ فایل‌ها را بعداً پشت سر هم بچسبانید. برای اینکه لحن بین تکه‌ها یکدست بماند، همان speaker و همان tone را برای همه‌ی تکه‌ها بفرستید.

گویندگان

هر گوینده دو نام دارد: نام فارسی که به کاربر خودتان نشان می‌دهید، و شناسه‌ی فینگلیش که در فیلد speaker می‌فرستید. قاعده‌اش ساده است — تلفظ همان اسم فارسی با حروف انگلیسی کوچک. «شهاب» می‌شود shahab و «مهتاب» می‌شود mahtab. همین فهرست به شکل ماشین‌خوان از GET https://api.appalpha.ir/v1/voices هم گرفته می‌شود و آن مسیر کلید نمی‌خواهد.

نام فارسی	شناسه‌ی API	جنسیت	ویژگی صدا
شهاب	`shahab`	مرد	قدرتمند و رسا
آوا	`ava`	زن	لطیف و دلنشین
نوید	`navid`	مرد	جوان و پرانرژی
آرمان	`arman`	مرد	گرم و صمیمی
مهسا	`mahsa`	زن	باوقار و رسمی
دانا	`dana`	مرد	خبری و آموزنده
سامان	`saman`	مرد	شاداب و پویا
آرش	`arash`	مرد	مطمئن و تأثیرگذار
شبنم	`shabnam`	زن	آرام و متین
سحر	`sahar`	زن	دوستانه و گیرا
مریم	`maryam`	زن	حرفه‌ای و واضح
بهرام	`bahram`	مرد	حماسی و نافذ
نیکان	`nikan`	مرد	مهربان و شیرین
فرناز	`farnaz`	زن	پخته و قابل اعتماد
سارا	`sara`	زن	جذاب و مدرن
مانی	`mani`	مرد	خلاق و متفاوت
آرتین	`artin`	مرد	با اصالت و شیک
دلنواز	`delnavaz`	زن	هنری و احساسی
روژان	`rozhan`	زن	شفاف و گویا
امید	`omid`	مرد	انگیزه‌بخش و مثبت
بردیا	`bardia`	مرد	ورزشی و پرهیجان
ترانه	`taraneh`	زن	موزیکال و خوش‌آهنگ
نیکو	`niko`	زن	روایتگر و قصه‌گو
هستی	`hasti`	زن	طبیعی و خودمانی
کامیار	`kamyar`	مرد	مصمم و جدی
کیانوش	`kianoosh`	مرد	درخشان و گیرا
پویا	`pouya`	مرد	بازیگوش و سرزنده
مهتاب	`mahtab`	زن	نجواگر و آرامش‌بخش
سام	`sam`	مرد	جسور و بی‌باک
لیدا	`lida`	زن	کلاسیک و باوقار

شناسه‌ی نامعتبر با یک خطای روشن رد می‌شود و اعتباری کسر نمی‌گردد. اگر speaker را اصلاً نفرستید، shahab انتخاب می‌شود.

نمونه‌ی کامل

python

import os, time, requests

BASE = "https://api.appalpha.ir/v1"
H = {"Authorization": f"Bearer {os.environ['ALPHA_KEY']}"}

job = requests.post(f"{BASE}/generations", headers=H, json={
    "model":   "alpha-tts",
    "text":    "هی، گوش کن! یه راز دارم که فقط به تو می‌گم.",
    "speaker": "mahtab",
    "tone":    "با لحنی مرموز، شیطنت‌آمیز و نجواگونه",
}).json()

if "error" in job:                       # متن بلند، گوینده‌ی اشتباه، اعتبار کم و…
    raise SystemExit("خطا: " + job["error"]["message"])

print(job["chars"], "نویسه ·", job["cost_toman"], "تومان")

while True:
    time.sleep(3)
    r = requests.get(job["poll_url"], headers=H).json()
    if r["status"] != "processing":
        break

print(r["output"]["url"] if r["status"] == "ready" else r["error"]["message"])

python — متن بلند، تکه‌تکه

# متن بلندتر از سقف را خودتان از روی جمله‌ها می‌شکنید و برای هر تکه
# یک درخواست می‌فرستید. همان speaker و همان tone برای همه‌ی تکه‌ها،
# تا لحن گوینده بین فایل‌ها عوض نشود.
LIMIT = 2500

def split_text(text, limit=LIMIT):
    parts, current = [], ""
    for sentence in text.replace("!", ".").replace("؟", ".").split("."):
        sentence = sentence.strip()
        if not sentence:
            continue
        sentence += "."
        if len(current) + len(sentence) + 1 > limit:
            parts.append(current.strip())
            current = sentence
        else:
            current += " " + sentence
    if current.strip():
        parts.append(current.strip())
    return parts

for i, part in enumerate(split_text(long_text), 1):
    print(f"تکه {i} — {len(part)} نویسه")
    # همان درخواست بالا، فقط با text=part

فایل‌های ورودی

هر فیلدی که فایل می‌گیرد، سه شکل ورودی را می‌پذیرد:

آدرس اینترنتی — ساده‌ترین راه. باید بدون نیاز به ورود قابل دانلود باشد.
data URI — مثل data:image/png;base64,iVBORw0…
base64 خام — بدون پیشوند؛ نوع فایل خودکار تشخیص داده می‌شود.

حداکثر حجم هر فایل ۴۰ مگابایت است. تصویر: png، jpg، webp. صدا: mp3، wav، ogg، m4a. ویدیو: mp4، webm، mov.

python — base64

import base64, requests

with open("portrait.jpg", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

requests.post(f"{BASE}/generations", headers=H, json={
    "model": "video-wan22",
    "image": f"data:image/jpeg;base64,{b64}",
    "prompt": "دوربین آرام به جلو حرکت می‌کند",
})

موجودی

GET/v1/balance

پیش از ارسال درخواست‌های سنگین، موجودی را بررسی کنید تا کار وسط راه متوقف نشود.

json

{ "balance_toman": 240500, "held_toman": 5000, "available_toman": 235500,
  "requests": 128, "spent_toman": 359500 }

held_toman مبلغی است که برای درخواست‌های در حال ساخت رزرو شده ولی هنوز کسر نشده. درخواست تازه فقط وقتی پذیرفته می‌شود که available_toman به اندازه‌ی قیمتش باشد.

فهرست درخواست‌ها

GET/v1/generations

پنجاه درخواست آخر شما، از تازه به قدیم. برای بازیابی خروجی‌هایی که شناسه‌شان را گم کرده‌اید مفید است.

فهرست مدل‌ها به شکل ماشین‌خوان

GET/v1/models

این مسیر کلید نمی‌خواهد. اگر قیمت‌ها را داخل محصول خودتان نمایش می‌دهید، به‌جای کپی کردن دستی از همین بگیرید.

فهرست مدل‌ها

روی هر مدل بزنید تا فیلدهای ورودی‌اش باز شود. قیمت‌ها به تومان و به ازای هر خروجی است.

ساخت تصویر — متن به تصویر و تصویر کارتونی

فلاکس Dev flux-dev 1000 تومان برای هر 2 خروجی

مدل پایه‌ی تولید تصویر با کیفیت بالا و پایبندی دقیق به متن. برای پوستر، محتوای شبکه‌های اجتماعی، تصویرسازی تبلیغاتی و کانسپت‌آرت.

قیمت‌گذاری بسته‌ای. هر خروجی 500 تومان حساب می‌شود؛ یعنی 2 خروجی روی هم 1000 تومان. کسر اعتبار در همان لحظه و به ازای هر درخواست انجام می‌شود، نه به شکل بسته‌ای.

فلاکس Dev انتخاب پیش‌فرض برای تصویر عمومی است: ترکیب‌بندی درست، نورپردازی طبیعی و دنبال کردن دقیق جزئیاتی که در متن نوشته‌اید. متن فارسی را مستقیم بفرستید؛ پیش از رسیدن به مدل خودکار ترجمه می‌شود.

فیلد	نوع	لازم	پیش‌فرض	توضیح
`prompt`	string	بله	—	توضیح تصویر؛ فارسی یا انگلیسی. هرچه دقیق‌تر بنویسید نتیجه نزدیک‌تر است.
`width`	int	—	`1024` 256 تا 2048	عرض تصویر به پیکسل
`height`	int	—	`1024` 256 تا 2048	ارتفاع تصویر به پیکسل

موتور: FLUX.1-dev

curl https://api.appalpha.ir/v1/generations \
  -H "Authorization: Bearer $ALPHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "flux-dev", "prompt": "یک فنجان چای روی میز چوبی کنار پنجره، نور ملایم صبح"}'

ز ایمیج (Z-Image) z-image 1000 تومان برای هر 4 خروجی

سریع‌ترین و ارزان‌ترین مدل تصویر در آلفا. خروجی تمیز با تعداد مراحل کم، مناسب تولید انبوه تصویر، تست ایده و محصولاتی که حجم درخواست بالایی دارند.

قیمت‌گذاری بسته‌ای. هر خروجی 250 تومان حساب می‌شود؛ یعنی 4 خروجی روی هم 1000 تومان. کسر اعتبار در همان لحظه و به ازای هر درخواست انجام می‌شود، نه به شکل بسته‌ای.

ز ایمیج برای وقتی است که تعداد برایتان مهم‌تر از حداکثر جزئیات است: با یک چهارم قیمت فلاکس، در چند ثانیه خروجی می‌دهد. برای گالری محصول، تصویر شاخص مقاله و کاربردهای انبوه بهترین نسبت قیمت به کیفیت را دارد. نکته درباره‌ی ابعاد: این مدل به‌جای عرض و ارتفاع آزاد، فهرستی از نسبت‌های آماده دارد. عددی که می‌فرستید به نزدیک‌ترین نسبت موجود نگاشت می‌شود، پس ممکن است خروجی دقیقاً همان پیکسل درخواستی نباشد.

فیلد	نوع	لازم	پیش‌فرض	توضیح
`prompt`	string	بله	—	توضیح تصویر؛ فارسی یا انگلیسی.
`width`	int	—	`1024` 256 تا 2048	عرض تصویر به پیکسل. سرور نزدیک‌ترین نسبت تصویر موجود را انتخاب می‌کند.
`height`	int	—	`1024` 256 تا 2048	ارتفاع تصویر به پیکسل. سرور نزدیک‌ترین نسبت تصویر موجود را انتخاب می‌کند.

موتور: Z-Image Turbo

curl https://api.appalpha.ir/v1/generations \
  -H "Authorization: Bearer $ALPHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "z-image", "prompt": "پرتره‌ی یک گربه‌ی ایرانی سفید روی پس‌زمینه‌ی آبی"}'

ساخت تصویر کارتونی cartoon-create 1000 تومان هر تصویر

از روی متن، تصویر کارتونی می‌سازد. سبک تخت و خطی با رنگ‌های شاد؛ برای کتاب کودک، استیکر، شخصیت‌پردازی و تصویرسازی آموزشی.

این مدل از صفر و فقط از روی متن تصویر کارتونی می‌سازد و ورودی تصویری نمی‌گیرد.

فیلد	نوع	لازم	پیش‌فرض	توضیح
`prompt`	string	بله	—	توضیح صحنه یا شخصیت کارتونی؛ فارسی یا انگلیسی.
`width`	int	—	`1024` 256 تا 2048	عرض تصویر به پیکسل
`height`	int	—	`1024` 256 تا 2048	ارتفاع تصویر به پیکسل

موتور: Flux Long-Toon LoRA

curl https://api.appalpha.ir/v1/generations \
  -H "Authorization: Bearer $ALPHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "cartoon-create", "prompt": "یک روباه بامزه با کلاه قرمز در جنگل پاییزی"}'

ویرایش تصویر — ویرایش و گسترش کادر

ویرایش تصویر qwen-image-edit 999 تومان برای هر 3 خروجی

تصویر را با یک جمله ویرایش می‌کند: تعویض پس‌زمینه، تغییر لباس و رنگ، حذف یا اضافه کردن شیء، تغییر حالت چهره و ترکیب چند تصویر در یک صحنه.

قیمت‌گذاری بسته‌ای. هر خروجی 333 تومان حساب می‌شود؛ یعنی 3 خروجی روی هم 999 تومان. کسر اعتبار در همان لحظه و به ازای هر درخواست انجام می‌شود، نه به شکل بسته‌ای.

تنها موتور ویرایش آلفا Qwen Image Edit است و انتخاب دیگری وجود ندارد. دستور را مثل حرف زدن با یک طراح بنویسید: «پس‌زمینه را به ساحل غروب تغییر بده» یا «کت مشکی را به کت چرم قهوه‌ای عوض کن». می‌توانید تا سه تصویر بفرستید تا عناصرشان را با هم ترکیب کند.

فیلد	نوع	لازم	پیش‌فرض	توضیح
`prompt`	string	بله	—	دستور ویرایش، مثلاً «پس‌زمینه را به ساحل تغییر بده».
`image`	file image	بله	—	تصویر اصلی که باید ویرایش شود.
`image2`	file image	—	—	تصویر دوم برای ترکیب (اختیاری).
`image3`	file image	—	—	تصویر سوم برای ترکیب (اختیاری).

موتور: Qwen Image Edit

curl https://api.appalpha.ir/v1/generations \
  -H "Authorization: Bearer $ALPHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen-image-edit", "prompt": "پس‌زمینه را به ساحل غروب تغییر بده", "image": "https://example.com/photo.jpg"}'

گسترش تصویر image-expand 1000 تومان برای هر 2 خروجی

کادر تصویر را به هر سمتی که بخواهید باز می‌کند و بخش تازه را متناسب با خودِ عکس می‌سازد. برای تبدیل عکس عمودی به افقی، ساخت بنر و پر کردن حاشیه.

همه‌ی تنظیمات این مدل در اختیار شماست: • directions — جهت‌های گسترش. هر ترکیبی از left، right، top و bottom. پیش‌فرض چپ و راست است. اگر می‌خواهید عکس عمودی افقی شود فقط left و right را بدهید. • size — اندازه‌ی نهایی، یکی از چهار حالت آماده: مربع ۱۰۲۴×۱۰۲۴، افقی ۱۲۸۰×۷۲۰، عمودی ۷۲۰×۱۲۸۰ یا افقی ۱۰۲۴×۷۶۸. اندازه باید در جهتی که انتخاب کرده‌اید بزرگ‌تر از عکس اصلی باشد وگرنه چیزی اضافه نمی‌شود؛ مثلاً برای افقی کردن یک عکس عمودی، ۱۲۸۰×۷۲۰ را با جهت‌های چپ و راست بگیرید. • steps — تعداد مراحل تولید، بین ۴ تا ۱۲. عدد بالاتر یعنی ناحیه‌ی جدید پرجزئیات‌تر و زمان بیشتر. پیش‌فرض ۸ برای بیشتر عکس‌ها کافی است. • prompt — اختیاری. اگر خالی بگذارید، مدل خودش ادامه‌ی منطقی صحنه را می‌سازد. اگر بنویسید «ادامه‌ی ساحل و آسمان ابری»، ناحیه‌ی جدید را طبق همان می‌سازد.

فیلد	نوع	لازم	پیش‌فرض	توضیح
`image`	file image	بله	—	تصویر ورودی که باید کادرش باز شود.
`directions`	multiselect	—	`left, right`	جهت‌هایی که تصویر در آن‌ها گسترش پیدا می‌کند. مقادیر مجاز: `left` · `right` · `top` · `bottom`
`size`	select	—	`1024x1024`	اندازه‌ی نهایی تصویر بعد از گسترش. مقادیر مجاز: `1024x1024` · `1280x720` · `720x1280` · `1024x768`
`steps`	int	—	`8` 4 تا 12	تعداد مراحل تولید؛ بیشتر یعنی دقیق‌تر و کندتر
`prompt`	string	—	—	توضیح اختیاری برای ناحیه‌ی جدید. خالی بگذارید تا خودکار تصمیم بگیرد.

موتور: Diffusers Image Outpaint

curl https://api.appalpha.ir/v1/generations \
  -H "Authorization: Bearer $ALPHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "image-expand", "image": "https://example.com/photo.jpg", "directions": ["left", "right"], "size": "1024x1024", "prompt": "ادامه‌ی ساحل و آسمان ابری"}'

ساخت ویدیو — تبدیل تصویر به ویدیو

ویدیو Wan 2.2 (۱۴B) video-wan22 5000 تومان هر ویدیو

یک تصویر ثابت را به کلیپ متحرک تبدیل می‌کند، با حرکت دوربین و حرکت طبیعی سوژه. دستور شما پیش از ساخت، خودکار به یک دستور سینمایی حرفه‌ای بازنویسی می‌شود.

این مدل دو مرحله دارد و هر دو در همین یک درخواست انجام می‌شود: ۱) ساخت دستور سینمایی — متن ساده‌ی شما (مثلاً «دوربین جلو بره») همراه با خودِ تصویر به یک مدل زبانی داده می‌شود که تصویر را می‌بیند و یک دستور کامل سینمایی می‌نویسد: حرکت دوربین، لنز، نورپردازی، ریتم و جزئیات حرکت سوژه. ۲) ساخت ویدیو — دستور بازنویسی‌شده به Wan 2.2 داده می‌شود. اگر خودتان دستور انگلیسی دقیقی دارید، cinematic را false بگذارید تا متن شما دست‌نخورده استفاده شود. دستور نهایی همیشه در خروجی زیر کلید cinematic_prompt برگردانده می‌شود.

فیلد	نوع	لازم	پیش‌فرض	توضیح
`image`	file image	بله	—	تصویر شروع ویدیو. کیفیت این عکس مستقیماً روی کیفیت ویدیو اثر دارد.
`prompt`	string	—	—	توضیح حرکت دلخواه؛ فارسی کافی است. مثلاً «دوربین آرام به سوژه نزدیک می‌شود».
`cinematic`	bool	—	`true`	بازنویسی خودکار دستور به سبک سینمایی

موتور: Wan 2.2 i2v 14B

curl https://api.appalpha.ir/v1/generations \
  -H "Authorization: Bearer $ALPHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "video-wan22", "image": "https://example.com/photo.jpg", "prompt": "دوربین آرام به سوژه نزدیک می‌شود"}'

متن به صدا — خواندن متن با صدای انسانی

آلفا TTS — تبدیل متن به صدا alpha-tts از 500 تومان بر اساس طول متن

آلفا TTS — تبدیل متن به صدا با هوش مصنوعی آلفا. متن را با یکی از سی گوینده‌ی فارسی و با لحن دلخواه می‌خواند و یک فایل MP3 تحویل می‌دهد. همه‌ی زبان‌های دنیا پشتیبانی می‌شوند.

قیمت بر اساس طول متن. تا ۱۰۰ نویسه — 500 تومان · ۱۰۱ تا ۶۰۰ نویسه — 1000 تومان · ۶۰۱ تا ۲٬۵۰۰ نویسه — 3000 تومان. هر درخواست یک بار همین مبلغ. متن بلندتر از 2500 نویسه پیش از هر کسری از اعتبار رد می‌شود. جزئیات کامل و فهرست گویندگان را در بخش متن به صدا ببینید.

آلفا TTS متنی که می‌فرستید را با صدای انسانی می‌خواند و خروجی را به شکل یک فایل MP3 آماده تحویل می‌دهد. برای گویندگی ویدیو، کتاب صوتی، پیام‌گیر تلفنی، خواندن مقاله، آموزش و هر جایی که به یک صدای طبیعی نیاز دارید. ━━ زبان‌ها ━━ این مدل به همه‌ی زبان‌های دنیا حرف می‌زند و لازم نیست زبان را جایی اعلام کنید؛ زبان از روی خودِ متن تشخیص داده می‌شود. فارسی، انگلیسی، عربی، ترکی، فرانسه، آلمانی، اسپانیایی، روسی، چینی و بقیه همگی با همان سی گوینده خوانده می‌شوند — یعنی یک گوینده‌ی ثابت می‌تواند در کل محصول شما به چند زبان صحبت کند. متن دوزبانه هم مشکلی ندارد و همان‌طور که نوشته شده خوانده می‌شود. ━━ گوینده‌ها ━━ سی گوینده دارید. در فیلد speaker شناسه‌ی فینگلیش گوینده را بفرستید؛ همان اسم فارسی است با حروف انگلیسی و همه با حروف کوچک: «شهاب» یعنی shahab، «مهتاب» یعنی mahtab، «کیانوش» یعنی kianoosh. جدول کامل نام‌ها در مستندات و در خروجی GET /v1/voices آمده است. اگر این فیلد را نفرستید، shahab انتخاب می‌شود. شناسه‌ی نامعتبر با یک خطای روشن رد می‌شود و اعتباری کسر نمی‌گردد. ━━ لحن و احساس ━━ لحن با آکولاد { } مشخص می‌شود و همیشه در انتهای متن می‌آید. هر چه داخل آکولاد بنویسید خوانده نمی‌شود؛ فقط به گوینده می‌گوید متن را چطور ادا کند. دو راه برای گفتنش هست و هر دو به یک چیز می‌رسند: ۱) داخل خودِ متن — آکولاد را در انتهای text بگذارید: وای تبدیل متن شما به صدایی که همدلی و درک را برمی‌انگیزد.{با تعجب و هیجان زیاد} هی، گوش کن! یه راز دارم که فقط به تو می‌گم. {با لحنی مرموز، شیطنت‌آمیز و نجواگونه} ۲) با فیلد جدا — همان توصیف را بدون آکولاد در فیلد tone بفرستید و آکولاد خودکار اضافه می‌شود: {"text": "هی، گوش کن! یه راز دارم…", "tone": "با لحنی مرموز و نجواگونه"} راه دوم برای وقتی بهتر است که متن از جای دیگری می‌آید و نمی‌خواهید دستکاریش کنید، یا یک لحن ثابت را روی چند تکه‌ی مختلف اعمال می‌کنید. اگر هر دو را بفرستید، آکولادی که خودتان داخل متن گذاشته‌اید دست‌نخورده می‌ماند. چند نمونه‌ی آزمایش‌شده از توصیف لحن: • {با لحنی رسمی، خنثی و خبری، مانند مجری بخش خبری شبانگاهی} • {با لحنی آرام، ملایم و دلنشین، مانند گوینده‌ی کتاب صوتی} • {با صدایی مملو از تعجب و ناباوری شدید} • {با لحنی قاطع، محکم و فرماندهانه} • {با لحنی انگیزشی و الهام‌بخش، مانند یک مربی که روحیه می‌دهد} • {خنده} و {خنده زیاد} برای خنداندن خودِ گوینده وسط جمله هرچه توصیف دقیق‌تر و تصویری‌تر باشد نتیجه نزدیک‌تر است؛ «با لحنی مرموز و نجواگونه، انگار رازی را در گوش کسی می‌گوید» خیلی بهتر از «مرموز» جواب می‌دهد. توصیف را به فارسی ساده بنویسید. آنچه داخل آکولاد است در شمارش نویسه‌ها و قیمت هم به حساب نمی‌آید وقتی از فیلد tone استفاده کنید. اگر آکولاد را داخل خودِ text بگذارید، چون بخشی از همان رشته است شمرده می‌شود — پس برای متن‌های نزدیک به سقف، فیلد tone انتخاب بهتری است. ━━ سقف طول متن ━━ هر درخواست حداکثر ۲٬۵۰۰ نویسه می‌گیرد. اگر متن بلندتری بفرستید، درخواست پیش از هر کسری از اعتبار و با کد خطای text_too_long رد می‌شود و در همان پاسخ می‌بینید متن شما چند نویسه بوده و سقف چند است. برای متن‌های بلندتر، خودتان متن را از روی پاراگراف یا نقطه به تکه‌های زیر ۲٬۵۰۰ نویسه بشکنید و برای هر تکه یک درخواست بفرستید؛ فایل‌ها را می‌توانید بعداً پشت سر هم بچسبانید. برای اینکه لحن بین تکه‌ها یکدست بماند، همان speaker و همان tone را برای همه‌ی تکه‌ها بفرستید. ━━ قیمت ━━ قیمت این مدل ثابت نیست و از روی تعداد نویسه‌های فیلد text حساب می‌شود. سه پله بیشتر ندارد و هر کدام «دانه‌ای» است، یعنی هر درخواست یک بار همین مبلغ: • تا ۱۰۰ نویسه — ۵۰۰ تومان • از ۱۰۱ تا ۶۰۰ نویسه — ۱٬۰۰۰ تومان • از ۶۰۱ تا ۲٬۵۰۰ نویسه — ۳٬۰۰۰ تومان شمارش روی متن پس از حذف فاصله‌های ابتدا و انتها انجام می‌شود و فاصله‌های میان کلمه‌ها هم مثل بقیه‌ی نویسه‌ها شمرده می‌شوند. مبلغی که واقعاً کسر شده همیشه در پاسخ زیر کلید cost_toman دیده می‌شود و کنارش chars تعداد نویسه‌ها را می‌گوید — پس لازم نیست خودتان پله را حدس بزنید. اگر ساخت به هر دلیلی شکست بخورد، مبلغ خودکار به کیف پول برمی‌گردد. ━━ نحوه‌ی کار ━━ این مدل مثل بقیه‌ی مدل‌های آلفا ناهم‌زمان است: در پاسخ اول یک شناسه و poll_url می‌گیرید و تا آماده شدن فایل، هر چند ثانیه وضعیت را می‌پرسید. متن‌های کوتاه معمولاً چند ثانیه و متن‌های نزدیک به سقف تا حدود یک دقیقه طول می‌کشند؛ فاصله‌ی ۳ تا ۵ ثانیه بین پرسش‌ها مناسب است. خروجی یک فایل MP3 با کیفیت ۱۹۲ کیلوبیت است.

فیلد	نوع	لازم	پیش‌فرض	توضیح
`text`	string	بله	—	متنی که باید خوانده شود؛ به هر زبانی. حداکثر ۲٬۵۰۰ نویسه. می‌توانید لحن را داخل آکولاد در انتهای همین متن بگذارید: «… .{با تعجب و هیجان زیاد}»
`speaker`	select	—	`shahab`	گوینده. شناسه‌ی فینگلیش همان نام فارسی است. مقادیر مجاز: `shahab` · `ava` · `navid` · `arman` · `mahsa` · `dana` · `saman` · `arash` · `shabnam` · `sahar` · `maryam` · `bahram` · `nikan` · `farnaz` · `sara` · `mani` · `artin` · `delnavaz` · `rozhan` · `omid` · `bardia` · `taraneh` · `niko` · `hasti` · `kamyar` · `kianoosh` · `pouya` · `mahtab` · `sam` · `lida`
`tone`	string	—	—	توصیف لحن و احساس (اختیاری) — مثلاً «با لحنی مرموز و نجواگونه». بدون آکولاد بنویسید؛ خودکار به انتهای متن اضافه می‌شود. خوانده نمی‌شود و در قیمت هم حساب نمی‌شود.

موتور: Alpha TTS

curl https://api.appalpha.ir/v1/generations \
  -H "Authorization: Bearer $ALPHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "alpha-tts", "text": "هی، گوش کن! یه راز دارم که فقط به تو می‌گم.", "speaker": "shahab", "tone": "با لحنی مرموز، شیطنت‌آمیز و نجواگونه"}'

صدا — تغییر، تقویت و جداسازی صدا

تغییر صدا با مدل آلفا alpha-change-voice 1000 تومان برای هر 2 خروجی

نمونه‌ی صدای خودتان و نمونه‌ی صدای مدل را می‌دهید؛ صدای شما با حفظ همان جمله‌ها و لحن، به صدای آن مدل تبدیل می‌شود.

این یک مدل توسعه‌داده‌شده توسط تیم آلفاست؛ یک مدل فوق‌العاده پیشرفته که بدون نیاز به سیستم‌های قدیمی RVC، فقط با یک نمونه صدا هر صدایی را با کیفیت بالا به همان صدا تبدیل می‌کند. در روش قدیمی RVC برای هر صدای مقصد باید یک مدل جداگانه آموزش می‌دادید: ساعت‌ها پردازش، ده‌ها دقیقه دیتای صوتی، و یک فایل مدل چندصد مگابایتی که باید جایی نگه داشته می‌شد. اینجا هیچ‌کدام لازم نیست. یک فایل صوتی کوتاه از صدای مقصد کافی است و همان لحظه تبدیل انجام می‌شود. از این مدل می‌توانید برای وب‌سایت‌های تغییر صدا استفاده کنید و هر چقدر مدل که خواستید با یک نمونه صدا بسازید، یا ساخت مدل را کلاً سمت کاربران خودتان بگذارید: کاربر شما فایل صدای دلخواهش را آپلود می‌کند و بدون هیچ مرحله‌ی آموزشی، بلافاصله صاحب یک «مدل صدا» می‌شود. دو ورودی لازم است: • source_audio — فایلی که محتوای گفتار را دارد؛ همان جمله‌هایی که باید شنیده شود. • reference_audio — نمونه‌ی صدای مقصد؛ فقط برای اینکه مدل بفهمد خروجی باید چه جنس صدایی داشته باشد. حدود ده ثانیه‌ی تمیز و بدون نویز بهترین نتیجه را می‌دهد.

فیلد	نوع	لازم	پیش‌فرض	توضیح
`source_audio`	file audio	بله	—	فایل صدای اصلی؛ همان جمله‌هایی که باید شنیده شود.
`reference_audio`	file audio	بله	—	نمونه‌ی صدای مدل مقصد؛ حدود ده ثانیه‌ی تمیز کافی است.

موتور: Alpha Change Voice

curl https://api.appalpha.ir/v1/generations \
  -H "Authorization: Bearer $ALPHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "alpha-change-voice", "source_audio": "https://example.com/voice.mp3", "reference_audio": "https://example.com/voice.mp3"}'

تقویت صدا voice-enhance 1000 تومان برای هر 2 خروجی

نویز پس‌زمینه و پژواک را حذف می‌کند و وضوح گفتار را بالا می‌برد. برای ضبط با موبایل، جلسه‌ی آنلاین و پادکست خانگی.

فایل‌های بلندتر از یک دقیقه خودکار از روی نقاط سکوت برش می‌خورند، تکه‌تکه پردازش می‌شوند و دوباره به هم می‌چسبند؛ پس لازم نیست خودتان فایل را تکه کنید. گزینه‌ی denoise را روشن بگذارید مگر اینکه فقط می‌خواهید وضوح بالا برود و نویز محیط عمداً حفظ شود.

فیلد	نوع	لازم	پیش‌فرض	توضیح
`audio`	file audio	بله	—	فایل صوتی ورودی با هر فرمتی.
`denoise`	bool	—	`true`	حذف نویز پیش از تقویت

موتور: Resemble Enhance

curl https://api.appalpha.ir/v1/generations \
  -H "Authorization: Bearer $ALPHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "voice-enhance", "audio": "https://example.com/voice.mp3"}'

جداسازی صدای خواننده از موزیک vocal-separate 1000 تومان هر جداسازی

آهنگ را می‌گیرد و یا فقط صدای خواننده را برمی‌گرداند یا فقط موسیقی بی‌کلام را. برای کارائوکه، ریمیکس، کاور خوانی و نمونه‌برداری.

خروجی این مدل با فیلد stem مشخص می‌شود و هر بار فقط یکی از دو حالت را می‌دهد: • برای گرفتن ووکال (صدای خواننده): مقدار stem را vocal بگذارید. خروجی فقط صدای خواننده است، بدون ساز و بدون بیت. اگر می‌خواهید روی یک بیت دیگر بگذاریدش یا متن آهنگ را پیاده کنید، همین حالت را بخواهید. • برای گرفتن پس‌زمینه (موسیقی بی‌کلام): مقدار stem را background بگذارید. خروجی همان آهنگ بدون صدای خواننده است؛ یعنی نسخه‌ی کارائوکه. برای کاور خواندن یا استفاده به‌عنوان موسیقی متن همین را بخواهید. اگر هر دو را لازم دارید باید دو درخواست جدا بفرستید و هزینه‌ی هر کدام جداگانه حساب می‌شود. فیلد format فرمت فایل خروجی را تعیین می‌کند: WAV کیفیت کامل و بدون افت، MP3 حجم کمتر، FLAC فشرده‌ی بدون افت. برای پردازش‌های بعدی WAV را انتخاب کنید. بهترین نتیجه از فایل اصلی و باکیفیت آهنگ به دست می‌آید؛ فایلی که خودش قبلاً چند بار فشرده شده، خروجی مبهم‌تری می‌دهد.

فیلد	نوع	لازم	پیش‌فرض	توضیح
`audio`	file audio	بله	—	فایل آهنگ ورودی.
`stem`	select	—	`vocal`	کدام بخش برگردانده شود. مقادیر مجاز: `vocal` · `background`
`format`	select	—	`WAV`	فرمت فایل خروجی. مقادیر مجاز: `WAV` · `MP3` · `FLAC`
`dereverb`	bool	—	`false`	حذف پژواک و اکوی سالن پیش از جداسازی

موتور: Audio Separator

curl https://api.appalpha.ir/v1/generations \
  -H "Authorization: Bearer $ALPHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "vocal-separate", "audio": "https://example.com/voice.mp3", "stem": "vocal", "format": "WAV"}'

چت‌بات — گفتگوی متنی با حافظه‌ی مکالمه

آیا چت aya-chat 30 تومان هر پیام

چت‌بات متنی فارسی با حافظه‌ی مکالمه. هر پیام سی تومان، بدون توجه به طول سؤال و جواب. برای پشتیبانی خودکار، دستیار داخل اپ و هر جایی که به یک مدل زبانی ارزان نیاز دارید.

آیا چت ارزان‌ترین راه اضافه کردن یک چت‌بات واقعی به محصول شماست. برخلاف سرویس‌هایی که بر اساس توکن حساب می‌کنند، اینجا واحد محاسبه «پیام» است: • هر پاسخ، سی تومان. تمام. • طول سؤال هیچ اثری روی مبلغ ندارد؛ یک کلمه یا هزار کلمه، سی تومان. • طول جواب هم هیچ اثری ندارد؛ یک خط یا ده پاراگراف، سی تومان. • فرستادن تاریخچه‌ی مکالمه (کانتکست) هزینه‌ی جداگانه ندارد. ورودی و خروجی با هم یک پیام حساب می‌شوند و همان سی تومان است. یعنی صورتحساب شما دقیقاً برابر است با «تعداد پیام‌های کاربران × ۳۰ تومان» و می‌توانید هزینه‌ی محصولتان را از قبل و با دقت پیش‌بینی کنید. حافظه‌ی مکالمه چطور کار می‌کند: آرایه‌ی messages را بفرستید؛ هر عضو یک شیء با دو کلید role و content است و role یکی از user یا assistant. سرور تاریخچه را برای مدل بازسازی می‌کند و پاسخ را با در نظر گرفتن کل مکالمه می‌دهد. حداکثر شانزده پیام آخر استفاده می‌شود؛ قدیمی‌ترها خودکار کنار گذاشته می‌شوند تا مکالمه‌های طولانی هم بدون خطا ادامه پیدا کنند. اگر فقط یک سؤال تک‌مرحله‌ای دارید و به حافظه نیازی نیست، به‌جای messages کافی است فیلد message را با متن سؤال بفرستید. فیلد system اختیاری است و شخصیت و قوانین چت‌بات را تعیین می‌کند؛ مثلاً «تو پشتیبان فروشگاه لوازم خانگی هستی و فقط درباره‌ی محصولات همین فروشگاه پاسخ می‌دهی». همیشه بفرستیدش تا رفتار ربات در همه‌ی پیام‌ها یکسان بماند. برخلاف بقیه‌ی مدل‌های آلفا، این مدل ناهم‌زمان نیست: پاسخ در همان درخواست برمی‌گردد و لازم نیست وضعیت را بپرسید. متن پاسخ هم روی سرور ما نگهداری نمی‌شود؛ فقط یک بار به شما داده می‌شود. ━━ استریم: پاسخ کلمه‌به‌کلمه ━━ به‌طور پیش‌فرض کل جواب یک‌جا و در پایان می‌رسد؛ یعنی کاربر شما چند ثانیه به یک صفحه‌ی ساکن نگاه می‌کند و بعد ناگهان یک متن کامل ظاهر می‌شود. برای یک چت‌بات این بدترین حالت است. کافی است در همان بدنه‌ی درخواست، کنار messages، فیلد stream را true بگذارید: {"model": "aya-chat", "messages": [...], "stream": true} با این یک فیلد، پاسخ همان‌طور که تولید می‌شود تکه‌تکه فرستاده می‌شود. هیچ اندپوینت جداگانه‌ای وجود ندارد و آدرس همان /v1/chat است. قالب خروجی Server-Sent Events است: هر رویداد یک خط که با data: شروع می‌شود و یک شیء JSON دارد، و بین رویدادها یک خط خالی. سه نوع رویداد می‌آید: • delta — یک تکه‌ی تازه از متن، در کلید text. تکه‌ها را پشت سر هم بچسبانید؛ هر تکه فقط بخش تازه است، نه کل متن تا اینجا. • done — پایان موفق. همان بدنه‌ی پاسخ عادی است: reply کامل، cost_toman و balance_toman. • error — چیزی خراب شد. اگر refunded برابر true باشد، مبلغ برگشته و چیزی از شما کسر نشده. در آخر یک خط data: [DONE] فرستاده می‌شود تا بدانید جریان تمام شد. دو نکته‌ی عملی: اول اینکه هزینه با استریم هیچ فرقی نمی‌کند و باز هم همان سی تومان برای کل پیام است. دوم اینکه یک رویداد ممکن است بین دو تکه‌ی شبکه نصف شود، پس در کد خودتان بافر نگه دارید و فقط رویدادهای کاملِ جداشده با خط خالی را پردازش کنید — نمونه‌ی آماده‌اش را همین‌جا زیر زبانه‌های کد می‌بینید. اگر اتصال استریمی به هر دلیلی ممکن نباشد، درخواست شکست نمی‌خورد: سرور بی‌صدا به حالت عادی برمی‌گردد و کل پاسخ را در یک رویداد delta می‌فرستد. یعنی بدترین حالت «استریم نشدن» است، نه «کار نکردن»، و کد شما لازم نیست برای این حالت چیز جداگانه‌ای بنویسد.

فیلد	نوع	لازم	پیش‌فرض	توضیح
`message`	string	—	—	متن پیام کاربر. اگر messages را بفرستید لازم نیست.
`messages`	array	—	—	تاریخچه‌ی گفتگو؛ آرایه‌ای از {"role": "user"\|"assistant", "content": "…"}. آخرین عضو باید پیام تازه‌ی کاربر باشد.
`system`	string	—	—	دستور سیستمی؛ شخصیت و قوانین چت‌بات.

موتور: Aya Chat

# پاسخ کامل، یک‌جا
curl https://api.appalpha.ir/v1/chat \
  -H "Authorization: Bearer $ALPHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "aya-chat", "system": "تو پشتیبان فروشگاه هستی و کوتاه و مؤدب جواب می‌دهی.", "messages": [{"role": "user", "content": "سلام، سفارشم کی می‌رسد؟"}, {"role": "assistant", "content": "سلام! شماره‌ی سفارش را بفرمایید تا بررسی کنم."}, {"role": "user", "content": "شماره‌اش ۱۰۴۲ است"}]}'

# پاسخ کلمه‌به‌کلمه (استریم) — فقط با افزودن "stream": true
curl -N https://api.appalpha.ir/v1/chat \
  -H "Authorization: Bearer $ALPHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "aya-chat", "system": "تو پشتیبان فروشگاه هستی و کوتاه و مؤدب جواب می‌دهی.", "messages": [{"role": "user", "content": "سلام، سفارشم کی می‌رسد؟"}, {"role": "assistant", "content": "سلام! شماره‌ی سفارش را بفرمایید تا بررسی کنم."}, {"role": "user", "content": "شماره‌اش ۱۰۴۲ است"}], "stream": true}'

چت بات با تحلیل تصویر chat-vision 30 تومان هر پیام

چت‌باتی که عکس هم می‌بیند. یک تصویر کنار پیام بفرستید تا آن را توضیح بدهد، متن داخلش را بخواند یا به سؤال شما درباره‌اش جواب بدهد. هر پیام سی تومان، با تصویر یا بدون تصویر.

این مدل همان چت‌بات متنی است، با یک توانایی اضافه: تصویر را می‌بیند و تحلیل می‌کند. کافی است کنار پیام، فیلد image را هم بفرستید. چه کارهایی می‌شود با آن کرد: • توضیح دادن محتوای یک عکس یا اسکرین‌شات • خواندن و رونویسی متن داخل تصویر (فاکتور، تابلو، دست‌نوشته، سند) • جواب دادن به سؤال درباره‌ی نمودار، جدول یا عکس محصول • نوشتن کپشن، توضیح محصول یا متن جایگزین (alt) از روی عکس قیمت دقیقاً مثل چت‌بات متنی است و واحد محاسبه «پیام» است: • هر پاسخ، سی تومان — چه تصویر داشته باشد چه نداشته باشد. • حجم و ابعاد تصویر، طول سؤال و طول جواب هیچ اثری روی مبلغ ندارند. • اگر پاسخی تحویل نشود، هیچ مبلغی کسر نمی‌شود. فیلد image چطور پر می‌شود: یکی از این سه شکل را بفرستید: آدرس اینترنتی تصویر (https://…)، یک data URI (data:image/jpeg;base64,…) یا رشته‌ی base64 خام. فرمت‌های JPG، PNG و WebP پذیرفته می‌شوند و سقف حجم هر تصویر ۸ مگابایت است. تصویر اختیاری است. اگر image را نفرستید، مدل مثل یک چت‌بات معمولی جواب متنی می‌دهد؛ پس می‌توانید کل گفتگوی محصولتان را روی همین یک مدل نگه دارید و فقط هر جا کاربر عکس فرستاد، image را اضافه کنید. اگر تصویر را بدون هیچ متنی بفرستید، مدل خودش آن را با جزئیات توضیح می‌دهد. حافظه‌ی مکالمه و تصویر: آرایه‌ی messages، فیلد message و فیلد system دقیقاً مثل چت‌بات متنی کار می‌کنند و حداکثر شانزده پیام آخر به‌عنوان حافظه استفاده می‌شود. یک نکته‌ی مهم: در هر درخواست فقط یک تصویر دیده می‌شود و آن تصویرِ همین پیام است. حافظه‌ی مکالمه متنی است و تصویر پیام‌های قبلی داخلش نمی‌ماند؛ پس اگر کاربر درباره‌ی همان عکس سؤال دوم پرسید، image را دوباره در همان درخواست بفرستید. استریم هم مثل چت‌بات متنی است: با "stream": true پاسخ کلمه‌به‌کلمه و با همان رویدادهای delta، done و error روی همان آدرس /v1/chat می‌آید. تنها فرق این مدل با چت‌بات متنی، مقدار model و فیلد image است.

فیلد	نوع	لازم	پیش‌فرض	توضیح
`message`	string	—	—	متن پیام یا سؤال درباره‌ی تصویر. اگر messages را بفرستید لازم نیست.
`image`	file image	—	—	تصویری که باید تحلیل شود: آدرس اینترنتی، data URI یا base64. JPG، PNG یا WebP تا ۸ مگابایت. اختیاری.
`messages`	array	—	—	تاریخچه‌ی گفتگو؛ آرایه‌ای از {"role": "user"\|"assistant", "content": "…"}. آخرین عضو باید پیام تازه‌ی کاربر باشد.
`system`	string	—	—	دستور سیستمی؛ شخصیت و قوانین چت‌بات.

موتور: Vision Chat

# تصویر با آدرس اینترنتی — پاسخ کامل، یک‌جا
curl https://api.appalpha.ir/v1/chat \
  -H "Authorization: Bearer $ALPHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "chat-vision", "message": "در این تصویر چه می‌بینی؟", "image": "https://example.com/photo.jpg"}'

# همان درخواست، کلمه‌به‌کلمه (استریم)
curl -N https://api.appalpha.ir/v1/chat \
  -H "Authorization: Bearer $ALPHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "chat-vision", "message": "در این تصویر چه می‌بینی؟", "image": "https://example.com/photo.jpg", "stream": true}'

نحوه‌ی محاسبه

قیمت‌گذاری بر پایه‌ی تعداد خروجی است، نه توکن. یک تصویر یعنی یک بار قیمت همان مدل؛ طول پرامپت هیچ تأثیری روی مبلغ ندارد. مبلغ فقط پس از تحویل خروجی سالم کسر می‌شود؛ تا آن لحظه فقط رزرو است.

خروجی سالم تحویل شد (ready) ← مبلغ کسر و در گردش حساب ثبت می‌شود.
پردازش ناموفق، گذشتن از سقف زمانی یا فایل خالی/ناقص (failed) ← هیچ مبلغی کسر نمی‌شود.
خطای اعتبارسنجی پیش از ارسال به موتور ← هیچ مبلغی کسر یا رزرو نمی‌شود.
پرسیدن وضعیت و پیشرفت ← رایگان.

بعضی مدل‌ها بسته‌ای معرفی شده‌اند (مثلاً «هر دو تصویر ۱٬۰۰۰ تومان»). این فقط شکل نمایش است؛ در عمل هر درخواست جداگانه و به قیمت یک خروجی حساب می‌شود و لازم نیست حتماً بسته را کامل کنید.

دو مدل واحد شمارش متفاوتی دارند و بد نیست جداگانه بدانید:

aya-chat و chat-vision — واحدشان «پیام» است. هر پاسخ سی تومان، بدون توجه به طول سؤال، طول جواب یا حجم تاریخچه‌ای که فرستاده‌اید.
alpha-tts — تنها مدلی که قیمتش ثابت نیست: سه پله بر اساس تعداد نویسه‌های فیلد text. جدول پله‌ها و سقف 2500 نویسه‌ای در بخش متن به صدا.

نرخ مرجع تبدیل برای مقایسه با سرویس‌های خارجی: هر دلار 190000 تومان. قیمت‌های آلفا عمداً پایین‌تر از پایین‌ترین تعرفه‌ی موجود در بازار تنظیم شده است.

کدهای خطا

خطاها همیشه با همین ساختار برمی‌گردند:

json

{ "error": { "message": "اعتبار کافی نیست…", "code": "insufficient_credit" } }

در پایتون KeyError گرفتید؟ یعنی درخواست خطا داشته و کد شما مستقیم سراغ کلید پاسخ موفق رفته است. مثلاً KeyError: 'reply' یا KeyError: 'poll_url' خودِ مشکل نیست؛ فقط نشان می‌دهد پیام خطای سرور خوانده نشده. پیش از استفاده از پاسخ، همیشه این دو خط را بگذارید:

python

if "error" in r:
    raise SystemExit("خطا: " + r["error"]["message"])

برای دیدن سریع علت هم print(r.status_code, r.text) کافی است.

کد	معنی	کار بعدی
`400`	یکی از فیلدهای لازم نیامده یا مقدارش پذیرفته نشده.	پیام خطا نام دقیق فیلد را می‌گوید.
`400` text_too_long	متن مدل `alpha-tts` از سقف 2500 نویسه رد شده.	پاسخ، `chars` و `max_chars` را هم می‌دهد. متن را به تکه‌های کوچک‌تر بشکنید. هیچ مبلغی کسر نشده.
`401`	کلید نیامده، نامعتبر است یا لغو شده.	هدر `Authorization` و وضعیت کلید را بررسی کنید.
`402`	موجودی کیف پول کمتر از هزینه‌ی درخواست است.	از صفحه‌ی `/topup` اعتبار شارژ کنید.
`404`	مدل یا شناسه‌ی درخواست پیدا نشد.	شناسه‌ی مدل را از `/v1/models` بگیرید.
`410` model_discontinued	این مدل دیگر ارائه نمی‌شود.	یکی از مدل‌های فعال `/v1/models` را انتخاب کنید. هیچ مبلغی کسر نشده.
`413`	حجم فایل ورودی بیش از حد مجاز است.	فایل را زیر ۴۰ مگابایت فشرده کنید.
`502` / `503`	سرور موقتاً در دسترس نیست.	با فاصله‌ی فزاینده دوباره تلاش کنید. مبلغی کسر نشده.

پرسش‌ها

پشتیبانی از کجاست؟

شارژ اعتبار مستقیم و آنلاین از صفحه‌ی شارژ کیف پول با درگاه زرین‌پال انجام می‌شود و بلافاصله در حسابتان می‌نشیند. برای پشتیبانی فنی، رزرو ظرفیت یا گزارش مشکل، در تلگرام به @App_alpha_support پیام بدهید.

چند درخواست هم‌زمان می‌توانم بفرستم؟

سقف سختی تعیین نشده، اما ارسال ده‌ها درخواست موازی صف را کند می‌کند. برای بار سنگین، یک صف داخلی بگذارید و پیش از شروع در تلگرام هماهنگ کنید.

پیش از شروع کارِ سنگین، موجودی کیف پول را یک بار از /v1/balance بخوانید و اگر کم بود کاربر را به صفحه‌ی شارژ بفرستید؛ این‌طور وسط کار با خطای 402 متوقف نمی‌شوید.

خروجی تا چه زمانی در دسترس است؟

آدرس خروجی برای دانلود فوری در نظر گرفته شده. بلافاصله بعد از آماده شدن، فایل را روی فضای خودتان کپی کنید.

حداکثر زمان ساخت چقدر است؟

ویدیو ۲۵ دقیقه، تصویر و صدا ۱۵ دقیقه. زمان عادی بیشتر مدل‌ها چند ثانیه تا چند دقیقه است. اگر درخواستی تا سقف زمانی خروجی سالم نداشته باشد، خودکار failed می‌شود و هیچ مبلغی کسر نمی‌شود. کلید expires_at در پاسخ، همین سقف را برای هر درخواست مشخص می‌کند.

آیا ممکن است یک درخواست برای همیشه در processing بماند؟

خیر. هر درخواست حداکثر تا expires_at تعیین تکلیف می‌شود؛ یا خروجی سالم تحویل و مبلغ کسر می‌شود، یا failed و هیچ کسری انجام نمی‌شود. اگر با یک درخواست مشکلی داشتید، شناسه‌ی آن را برای پشتیبانی بفرستید.

می‌شود درخواست را لغو کرد؟

فعلاً نه. وقتی درخواست وارد صف شد تا پایان اجرا می‌شود. اگر شکست بخورد، هیچ مبلغی کسر نمی‌شود.

پرامپت فارسی چطور پردازش می‌شود؟

در بیشتر مدل‌ها پیش از رسیدن به مدل به انگلیسی ترجمه می‌شود. در video-wan22 با حالت سینمایی، متن شما همراه با خودِ تصویر به یک دستور کامل سینمایی انگلیسی بازنویسی می‌شود.

مستندات API آلفا

احراز هویت

اولین درخواست

ساخت درخواست

پاسخ — کد ۲۰۲

گرفتن خروجی

تضمین «بدون تحویل، بدون هزینه»

نوار پیشرفت واقعی

نمونه‌ی کامل — نوار پیشرفت برای کاربر شما

کدام مدل‌ها پیشرفت می‌دهند؟

چت‌بات — آیا چت

پاسخ — کد ۲۰۰

استریم — پاسخ کلمه‌به‌کلمه

حافظه‌ی مکالمه چطور کار می‌کند

چت بات با تحلیل تصویر

آلفا TTS — تبدیل متن به صدا

فیلدهای درخواست

لحن و احساس — آکولاد { }

نمونه‌های آزمایش‌شده

قیمت — بر اساس طول متن

گویندگان

نمونه‌ی کامل

فایل‌های ورودی

موجودی

فهرست درخواست‌ها

فهرست مدل‌ها به شکل ماشین‌خوان

فهرست مدل‌ها

نحوه‌ی محاسبه

کدهای خطا

پرسش‌ها

پشتیبانی از کجاست؟

چند درخواست هم‌زمان می‌توانم بفرستم؟

خروجی تا چه زمانی در دسترس است؟

حداکثر زمان ساخت چقدر است؟

آیا ممکن است یک درخواست برای همیشه در processing بماند؟

می‌شود درخواست را لغو کرد؟

پرامپت فارسی چطور پردازش می‌شود؟

لحن و احساس — آکولاد `{ }`