مستندات MyAIHub API

۱. مقدمه · هوش مصنوعی و API یعنی چی؟

خیلی ساده: شما یک متن (Prompt) برای سرور ما می‌فرستید، سرور آن را به یکی از مدل‌های هوش مصنوعی (DeepSeek، Qwen، Llama، GPT و ...) می‌دهد، مدل پاسخ می‌سازد و نتیجه را به شکل JSON برمی‌گرداند.

۲. شروع سریع در ۳ قدم

1. یکی از پلن‌های BASIC، PRO یا VIP را از صفحه پلن‌ها خریداری کن.
2. بعد از خرید، در بخش My Account → License Keys یک Master API Key می‌بینی. این همان کلیدی است که باید در تمام پروژه‌ها و پلی‌گراند استفاده کنی.
3. با استفاده از مثال‌های این صفحه (JS / Python / PHP / cURL) یک درخواست POST به API بفرست.

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

۳. Endpoint و متد

۴. بدنه درخواست (Request Body)

در ساده‌ترین حالت، درخواست تو این فیلدها را دارد:

نمونه درخواست ساده (متنی)

{
  "api_key": "YOUR_MASTER_API_KEY",
  "model":   "qwen/qwen-2.5-7b-instruct",
  "prompt":  "در دو جمله توضیح بده هوش مصنوعی چیست."
}

امنیت: API Key را در Frontend قرار نده. درخواست را از Backend خودت ارسال کن.

۵. پلن‌ها، Add-onها و مدل‌های قابل دسترسی

هر Master API Key به یک پلن متصل است. پلن‌ها مشخص می‌کنند به چه مدل‌هایی دسترسی داری و سقف استفاده ماهانه‌ات چقدر است. در MyAIHub سقف‌ها به صورت تفکیک‌شده مدیریت می‌شوند: OpenRouter جدا و OpenAI/GPT جدا.

۵.۱. Add-on ها (افزایش سقف درخواست)

۵.۱.۱. Add-on های OpenRouter

• +50 درخواست (Product ID: 404)
• +250 درخواست (Product ID: 405)
• +1000 درخواست (Product ID: 406)

۵.۱.۲. Add-on های GPT / OpenAI (فقط برای VIP)

• +50 درخواست GPT (Product ID: 516)
• +250 درخواست GPT (Product ID: 517)
• +1000 درخواست GPT (Product ID: 518)

۵.۲. نحوه محاسبه مصرف

• هر درخواست موفق به endpoint = یک درخواست از سقف همان Provider کم می‌کند.
• اگر مدل OpenAI باشد، از سقف GPT/OpenAI کم می‌شود. اگر OpenRouter باشد، از سقف OpenRouter کم می‌شود.
• محدودیت‌ها ماهانه و بر اساس ماه میلادی ریست می‌شوند.
• اگر در چند پروژه از یک API Key استفاده کنی، مصرف همه روی همان Key جمع می‌شود.

مقدار دقیق و لحظه‌ای در پاسخ API داخل usage و usage_breakdown برمی‌گردد.

۶. ساختار پاسخ (Response)

در حالت موفقیت، پاسخ سرور MyAIHub به‌صورت JSON شبیه مثال زیر است:

{
  "error": false,
  "reply": "متن پاسخ مدل اینجاست...",
  "model": "openai/gpt-5.2",
  "source": "openai",
  "plan": "vip",
  "usage": {
    "plan": "vip",
    "period": "2025-12",
    "used": 12,
    "limit": 830,
    "remaining": 818
  },
  "usage_breakdown": {
    "openrouter": { "used": 10, "limit": 750, "remaining": 740 },
    "openai":     { "used": 2,  "limit": 80,  "remaining": 78 }
  }
}

توضیح فیلدها:

• error: اگر false باشد یعنی درخواست موفق بوده.
• reply: جواب متنی مدل.
• model: مدلی که استفاده شده (مثلاً deepseek/deepseek-chat یا openai/gpt-5.2).
• source: Provider (مثلاً openrouter یا openai).
• usage: یک خلاصه ساده از مصرف (برای UI ساده/پلی‌گراند).
• usage_breakdown: مصرف تفکیک‌شده OpenRouter و GPT/OpenAI (برای UI حرفه‌ای).

در usage.limit سقف کل نشان داده می‌شود (OpenRouter + OpenAI) تا UI ساده هم بدون پیچیدگی بتواند نمایش دهد. اما سقف واقعی هر Provider را از usage_breakdown بخوان.

۷. ارسال تصویر (Vision)

اگر مدل Vision فعال باشد (مثلاً Llama Vision روی OpenRouter)، می‌توانی علاوه بر متن، تصویر هم بفرستی. تصویر باید به‌صورت data URL (base64) در فیلد image_url ارسال شود.

{
  "api_key":   "YOUR_MASTER_API_KEY",
  "model":     "meta-llama/llama-3.2-11b-vision-instruct",
  "prompt":    "در مورد این تصویر یک توضیح کوتاه بنویس.",
  "image_url": "data:image/png;base64,AAAFBfj42Pj4..."
}

در پلی‌گراند MyAIHub می‌توانی تصویر را انتخاب کنی و خودش به data URL تبدیل می‌شود.

۸. خطاهای متداول

۸.۱. لایسنس نامعتبر یا غیرفعال

{
  "error": true,
  "message": "License key نامعتبر است یا فعال نیست.",
  "details": "License key is not active or does not exist."
}

۸.۲. مدل مجاز در پلن شما نیست

{
  "error": true,
  "message": "در پلن PRO مدل‌های مستقیم OpenAI در دسترس نیست. برای OpenAI باید پلن VIP داشته باشید.",
  "plan": "pro"
}

۸.۳. سقف OpenRouter تمام شده

{
  "error": true,
  "message": "سقف ماهانه OpenRouter شما تمام شده است.",
  "plan": "pro",
  "usage": { "used": 750, "limit": 750, "remaining": 0, "plan": "pro", "period": "2025-12" }
}

۸.۴. سقف GPT/OpenAI تمام شده (VIP)

{
  "error": true,
  "message": "سقف ماهانه GPT/OpenAI شما تمام شده است.",
  "plan": "vip",
  "usage_breakdown": {
    "openai": { "used": 80, "limit": 80, "remaining": 0 }
  }
}

۸.۵. فیلدهای الزامی خالی هستند

{
  "error": true,
  "message": "api_key یا model یا prompt خالی است."
}

اگر ارور دیگری دیدی، معمولاً در فیلد message توضیح کوتاهی نمایش داده می‌شود. همان را در لاگ چاپ کن.

۹. مثال‌های عملی

۹.۱. JavaScript (Fetch – Node.js / Backend)

fetch("https://myaihub.ir/api/chat_v3.php", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: "YOUR_MASTER_API_KEY",
    model:   "deepseek/deepseek-chat",
    prompt:  "سلام، یک متن خوش‌آمدگویی کوتاه بنویس."
  })
})
  .then(res => res.json())
  .then(data => {
    if (data.error) console.error("API Error:", data.message);
    else console.log("Reply:", data.reply);
  })
  .catch(err => console.error("Network Error:", err));

۹.۲. Python (requests)

import requests

url = "https://myaihub.ir/api/chat_v3.php"
payload = {
    "api_key": "YOUR_MASTER_API_KEY",
    "model":   "qwen/qwen-2.5-7b-instruct",
    "prompt":  "در سه bullet point توضیح بده MyAIHub به چه درد برنامه‌نویس‌ها می‌خورد."
}

r = requests.post(url, json=payload, timeout=30)
data = r.json()

if data.get("error"):
    print("API Error:", data.get("message"))
else:
    print("Reply:", data.get("reply"))
    print("Usage:", data.get("usage"))

۹.۳. PHP (cURL)

<?php
$payload = [
  "api_key" => "YOUR_MASTER_API_KEY",
  "model"   => "openai/gpt-5.2",
  "prompt"  => "یک متن انگیزشی کوتاه به زبان فارسی بنویس."
];

$ch = curl_init("https://myaihub.ir/api/chat_v3.php");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response, true));

۹.۴. cURL (خط فرمان)

curl -X POST "https://myaihub.ir/api/chat_v3.php" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_MASTER_API_KEY",
    "model":   "deepseek/deepseek-chat",
    "prompt":  "در دو جمله MyAIHub را معرفی کن."
  }'

۱۰. نکات حرفه‌ای (Best Practices)

• ۱. API Key را در فرانت‌اند قرار نده: درخواست‌ها را از Backend بفرست.
• ۲. مصرف را تفکیکی مانیتور کن: از usage_breakdown استفاده کن تا بفهمی GPT یا OpenRouter چقدر مصرف شده.
• ۳. Prompt واضح بنویس: دقیق بگو چی می‌خوای؛ نتیجه بهتر می‌شود.
• ۴. مدل مناسب انتخاب کن: کار سبک: مدل کوچک‌تر / کار سنگین: DeepSeek یا GPT.
• ۵. Timeout منطقی بگذار: ۳۰ تا ۶۰ ثانیه معمولاً کافی است.

۱۱. سوالات متداول (FAQ)