مستندات API

هر سرویس یک نشانی دارد و فقط POST می‌پذیرد. ورودی این سرویس‌ها کد ملی و شمارهٔ کارت است؛ فرستادنش در نشانی یعنی نشستنش در لاگ سرور، تاریخچهٔ مرورگر و هدر Referer، پس GET عمداً پشتیبانی نمی‌شود.

POST https://melliapi.net/api/v1/{slug}/
Content-Type: application/json

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

{
  "ok": true,
  "requestId": "req_1a2b3c…",
  "service": "sana-inquiry",
  "data": { … },
  "source": { "cached": false, "stale": false, "fetchedAt": "2026-09-23T10:00:00.000Z" },
  "billing": { "amountRial": 51000, "balanceRial": 9949000 }
}

• data، پاسخ سرویس مرجع، بدون دست‌کاری.
• source.cached، پاسخ از کش آمد یا از سرویس مرجع. stale یعنی سرویس مرجع در دسترس نبود و آخرین پاسخ معتبر برگردانده شد؛ fetchedAt می‌گوید مال چه زمانی است.
• billing.amountRial، همان مبلغی که همین حالا کسر شد. صفر یعنی رایگان بود.
• requestId، برای پیگیری در پشتیبانی. نگهش دارید.

هر پاسخ ناموفق همین شکل را دارد و error.code ماشین‌خوان است. به کد تکیه کنید و نه به متن پیام؛ متن ممکن است بهتر شود.

{ "ok": false, "requestId": "req_…", "error": { "code": "insufficient_funds", "message": "…" } }

⚠️ not_found با HTTP ۲۰۰ برمی‌گردد و ok:false دارد. «رکوردی نیست» یک پاسخ معتبر است که ما بابتش به سرویس مرجع پول داده‌ایم، پس هزینه دارد، ولی ۴۰۴ نمی‌دهیم چون با «چنین سرویسی نداریم» قاطی می‌شود.

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

curl

curl -X POST 'https://melliapi.net/api/v1/sana-inquiry/' \
  -H 'Authorization: Bearer melli_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"nationalCode":"0013542419","mobile":"09120000000"}'

PHP / وردپرس

$response = wp_remote_post( 'https://melliapi.net/api/v1/sana-inquiry/', array(
    'timeout' => 30,
    'headers' => array(
        'Authorization' => 'Bearer ' . MELLIAPI_API_KEY,
        'Content-Type'  => 'application/json',
    ),
    'body' => wp_json_encode( array(
        'nationalCode' => $national_code,
        'mobile'       => $mobile,
    ) ),
) );

if ( is_wp_error( $response ) ) {
    // شبکه قطع بود، دوباره تلاش کنید.
    return;
}

$body = json_decode( wp_remote_retrieve_body( $response ), true );
if ( ! empty( $body['ok'] ) ) {
    // $body['data'] پاسخ استعلام است.
}

Node.js

const response = await fetch('https://melliapi.net/api/v1/sana-inquiry/', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MELLIAPI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ nationalCode, mobile }),
});

const body = await response.json();
if (body.ok) {
  // body.data
}

Python

import os, requests

response = requests.post(
    "https://melliapi.net/api/v1/sana-inquiry/",
    headers={"Authorization": f"Bearer {os.environ['MELLIAPI_API_KEY']}"},
    json={"nationalCode": national_code, "mobile": mobile},
    timeout=30,
)
body = response.json()
if body.get("ok"):
    data = body["data"]

⚠️ مهلت (timeout) را دست‌کم ۳۰ ثانیه بگذارید. برخی سرویس‌های مرجع کند پاسخ می‌دهند و مهلت کوتاه یعنی شما پاسخ را نمی‌بینید در حالی که صورتحسابش صادر شده.

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

POST https://melliapi.net/api/v1/ai/chat/completions/

{
  "model": "gemini-flash",
  "messages": [
    { "role": "system", "content": "پاسخ‌ها را کوتاه و فارسی بده." },
    { "role": "user", "content": "پایتخت ایران کجاست؟" }
  ],
  "max_tokens": 200,
  "temperature": 0.3
}

پاسخ موفق

{
  "ok": true,
  "requestId": "req_7f3c…",
  "model": "gemini-flash",
  "content": "تهران.",
  "usage": { "promptTokens": 42, "completionTokens": 3 },
  "finishReason": "stop",
  "billing": { "amountRial": 710, "balanceRial": 48912340 }
}

🔴 billing.amountRial مبلغی است که واقعاً کسر شد و نه سقفی که پیش از تماس قفل شده بود. تفاوت این دو همان لحظه به موجودی برمی‌گردد.

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

با فرستادن "stream": true، پاسخ به‌صورت text/event-stream تکه‌تکه می‌آید. هر تکه یک خط data: است.

data: {"requestId":"req_7f3c…","delta":"ته"}

data: {"requestId":"req_7f3c…","delta":"ران."}

data: {"requestId":"req_7f3c…","done":true,"usage":{"promptTokens":42,"completionTokens":3},"billing":{"amountRial":710}}

data: [DONE]

⚠️ صورتحساب در تکهٔ پایانی می‌آید، نه در ابتدا، چون هزینه تا پایان تولید معلوم نیست. اگر ارتباط را وسط کار قطع کنید، بابت همان مقداری که تولید شده هزینه کسر می‌شود؛ مدل تا آن لحظه کار کرده است.

اگر پیش از شروع جریان خطایی رخ دهد، کلید نامعتبر، موجودی ناکافی، مدل خاموش، پاسخ یک JSON معمولی با کد وضعیت مناسب است و نه جریان. پس همیشه content-type را بررسی کنید.

POST https://melliapi.net/api/v1/ai/chat/completions/

مدل تصویرساز مسیر جدایی ندارد: همان نشانی و همان بدنهٔ گفت‌وگو، و تصویر در کلید images پاسخ برمی‌گردد. توصیفِ تصویر را مثل یک پیام معمولی بفرستید.

{
  "model": "nano-banana",
  "messages": [
    { "role": "user", "content": "یک فنجان قهوه روی میز چوبی، نور طبیعی" }
  ],
  "max_tokens": 4096
}

پاسخ موفق

{
  "ok": true,
  "requestId": "req_9b1d…",
  "model": "nano-banana",
  "content": "",
  "images": ["data:image/png;base64,iVBORw0KGgo…"],
  "usage": { "promptTokens": 18, "completionTokens": 1290 },
  "billing": { "amountRial": 531300, "balanceRial": 48381040 }
}

🔴 content برای مدل تصویرساز معمولاً خالی است و این طبیعی است؛ خروجی در images است. هر عضو یکdata URI است، پس پاسخ می‌تواند چند مگابایت باشد.

⚠️ قیمت این مدل‌ها هم توکنی است و نه ثابت به‌ازای هر تصویر: تصویر خروجی به توکن شمرده می‌شود. مبلغ کسرشده مثل همیشه درbilling نوشته است، و timeout سمت خودتان را دست‌کم ۱۲۰ ثانیه بگذارید.

مدل‌های متنی برای همین کلید images آرایهٔ خالی می‌دهند، پس لازم نیست دو شکل پاسخ را جدا مدیریت کنید.

POST https://melliapi.net/api/v1/ai/videos/

درخواست، کار را ثبت می‌کند و پاسخ 202 با شناسهٔ کار برمی‌گرداند، نه خود ویدیو. فیلدها: model و prompt لازم‌اند؛ duration (ثانیه)، resolution، audio و image (تصویر آغازین، نشانی https یا data URL) اختیاری‌اند و مقدارهای مجاز هر مدل در صفحهٔ همان مدل آمده. مقدار ناشناخته رد می‌شود و به نزدیک‌ترین مقدار گرد نمی‌شود.

{
  "model": "google-veo-3.1-fast",
  "prompt": "A slow cinematic drone shot over the Persian Gulf at sunset",
  "duration": 8,
  "resolution": "720p",
  "audio": true
}

{
  "ok": true,
  "id": "vid_3f2a…",
  "status": "processing",
  "billing": { "reservedRial": 1594000, "amountRial": 0 }
}

GET https://melliapi.net/api/v1/ai/videos/{id}/

وضعیت را هر چند ثانیه بپرسید. status یکی از processing، succeeded یا failed است. در حالت موفق videoUrl و expiresAt می‌آیند؛ دریافت فایل از videoUrl همان هدر Authorization را می‌خواهد.

🔴 پول: قیمت ویدیو (نرخ هر ثانیه × مدت) هنگام ثبت از موجودی قفل می‌شود. اگر ساخت موفق شود همان مبلغ کسر می‌شود؛ اگر ناموفق باشد یا در یک ساعت تمام نشود، کامل برمی‌گردد. فایل ویدیو ۷ روز نزد ما می‌ماند و بعد پاک می‌شود؛ آن را نزد خودتان ذخیره کنید.

کاری که failed شود، error.code دارد: generation_failed (ساخت ناموفق)، timeout (در مهلت تمام نشد)، delivery_failed (فایل دریافت نشد) یا temporarily_unavailable. در همهٔ این حالت‌ها مبلغی کسر نمی‌شود.

هر پاسخ ناموفق همین شکل را دارد و کد وضعیت HTTP هم با آن می‌خواند:

{
  "ok": false,
  "requestId": "req_7f3c…",
  "error": { "code": "insufficient_funds", "message": "…" },
  "billing": { "amountRial": 0, "balanceRial": 120000 }
}

⚠️ 429 هدر Retry-After دارد؛ به‌جای تلاش فوری، همان اندازه صبر کنید.

• پیش از تماس با مدل، سقف هزینه از موجودی قفل می‌شود. پس از پاسخ، مبلغ واقعی کسر و باقی همان لحظه آزاد می‌شود.
• سقف خروجی را با max_tokens خودتان تعیین می‌کنید. اگر نفرستید، سقف پیش‌فرض همان مدل اعمال می‌شود.
• ورودی نامعتبر، در دسترس نبودن مدل و عبور از سقف نرخ هزینه‌ای ندارند.
• اگر ارائه‌دهنده شمار توکن را گزارش نکند، فراخوان رایگان حساب می‌شود. ضررش با ماست، نه شما.

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

فهرست مدل‌ها همین حالا در دسترس نیست. برای دریافت فهرست با ما تماس بگیرید.

curl

curl -X POST 'https://melliapi.net/api/v1/ai/chat/completions/' \
  -H 'Authorization: Bearer melli_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"model":"gemini-flash","messages":[{"role":"user","content":"سلام"}],"max_tokens":200}'

Node.js

const response = await fetch('https://melliapi.net/api/v1/ai/chat/completions/', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MELLIAPI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gemini-flash',
    messages: [{ role: 'user', content: prompt }],
    max_tokens: 200,
  }),
});

const body = await response.json();
if (body.ok) {
  console.log(body.content, body.billing.amountRial);
}

Python

import os, requests

response = requests.post(
    "https://melliapi.net/api/v1/ai/chat/completions/",
    headers={"Authorization": f"Bearer {os.environ['MELLIAPI_API_KEY']}"},
    json={
        "model": "gemini-flash",
        "messages": [{"role": "user", "content": prompt}],
        "max_tokens": 200,
    },
    timeout=120,
)
body = response.json()
if body.get("ok"):
    print(body["content"], body["billing"]["amountRial"])

PHP / وردپرس

$response = wp_remote_post( 'https://melliapi.net/api/v1/ai/chat/completions/', array(
    'timeout' => 120,
    'headers' => array(
        'Authorization' => 'Bearer ' . MELLIAPI_API_KEY,
        'Content-Type'  => 'application/json',
    ),
    'body' => wp_json_encode( array(
        'model'      => 'gemini-flash',
        'messages'   => array( array( 'role' => 'user', 'content' => $prompt ) ),
        'max_tokens' => 200,
    ) ),
) );

if ( is_wp_error( $response ) ) {
    return; // شبکه قطع بود، دوباره تلاش کنید.
}

$body = json_decode( wp_remote_retrieve_body( $response ), true );
if ( ! empty( $body['ok'] ) ) {
    // $body['content'] پاسخ مدل است.
}

⚠️ مهلت (timeout) را دست‌کم ۱۲۰ ثانیه بگذارید. پاسخ‌های بلند زمان می‌برند و مهلت کوتاه یعنی شما پاسخ را نمی‌بینید در حالی که صورتحسابش صادر شده.

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

یک درخواست POST /api/v1/sms/otp/ با کلید API در هدر Authorization: Bearer (یا X-API-Key).

• mobile: شمارهٔ موبایل ایران، با ارقام فارسی یا لاتین. لازم.
• code: اختیاری. اگر بفرستید همان کد می‌رود؛ فقط رقم، ۴ تا ۱۰ رقم.
• length: طول کد ساخته‌شده، ۴ تا ۸ رقم، پیش‌فرض ۵. کد ساخته‌شده در پاسخ برنمی‌گردد.
• ttlSeconds: اعتبار کد، ۶۰ تا ۹۰۰ ثانیه، پیش‌فرض ۱۲۰.

curl -X POST https://melliapi.net/api/v1/sms/otp/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mobile": "09121234567", "length": 5, "ttlSeconds": 120}'

پاسخ موفق (مبلغ واقعی در billing.amountRial):

{
  "ok": true,
  "requestId": "req_7f3c…",
  "otpId": "otp_1a9e…",
  "status": "sent",
  "expiresAt": "2026-11-03T10:02:00.000Z",
  "billing": { "amountRial": … }
}

کدی که کاربر وارد کرده را با POST /api/v1/sms/otp/verify/ بسنجید. آخرین کد ارسال‌شده به همان شماره، از همان حساب، سنجیده می‌شود. هر کد ۵ بار قابل سنجش است و کد درست فقط یک بار پذیرفته می‌شود. سنجش رایگان است.

curl -X POST https://melliapi.net/api/v1/sms/otp/verify/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mobile": "09121234567", "code": "48213"}'

{ "ok": true, "requestId": "req_…", "valid": true }

{ "ok": true, "requestId": "req_…", "valid": false,
  "reason": "invalid_code", "remainingAttempts": 3 }

مقدارهای reason: invalid_code (کد نادرست)، expired (مهلت گذشته)، already_used (قبلاً پذیرفته شده)، too_many_attempts (قفل شده) و not_found (کدی برای این شماره فرستاده نشده).