مستندات فنی API

به مستندات توسعه‌دهندگان دارک‌زد خوش آمدید. این رابط کاربری قدرتمند به شما امکان می‌دهد تا مدل‌های پیشرفته هوش مصنوعی مانند Gemini و GPT-Nano را به سادگی و مستقیم در برنامه‌های خود ادغام کنید.

نکته: تمامی درخواست‌ها باید برای امنیت بیشتر از طریق پروتکل HTTPS ارسال شوند.

احراز هویت Token Bearer

دسترسی به API محدود به کاربران احراز هویت شده است. سیستم جدید احراز هویت ما از توکن‌های Bearer برای امنیت بیشتر استفاده می‌کند. شما باید کلید API کامل خود را در هدر Authorization ارسال کنید.

فرمت جدید: دیگر نیازی به ارسال نام کاربری نیست. کلید API شما شامل تمام اطلاعات شناسایی لازم است.
Authorization: Bearer 

کلید API یک رشته ۶۴ کاراکتری است که از پنل کاربری دریافت می‌کنید.

مدل‌ها و تعرفه‌ها

ما مدل‌های متنوعی را متناسب با نیاز شما ارائه می‌دهیم. هزینه‌ها بر اساس هر ۱۰۰۰ توکن محاسبه می‌شود.

شناسه مدل (Model ID) نام مدل هزینه ورودی (هر ۱۰۰۰ توکن) هزینه خروجی (هر ۱۰۰۰ توکن)
gemini-2.5-flash Gemini Flash ۶۰۰ تومان ۶۰۰ تومان
gpt-5-nano GPT Nano ۶۰۰ تومان ۶۰۰ تومان

آدرس فراخوانی (Endpoint)

POST https://ai.darkzed.ir/gateway.php

پارامترهای درخواست

یک آبجکت JSON را در بدنه (Body) درخواست POST خود ارسال کنید.

پارامتر نوع الزامی توضیحات
prompt رشته (String) بله متن سوال یا دستورالعمل شما برای هوش مصنوعی.
model رشته (String) خیر شناسه مدل مورد نظر. پیش‌فرض: gemini-2.5-flash.

ساختار پاسخ

در صورت موفقیت، پاسخ به صورت JSON با ساختار زیر برگردانده می‌شود:

{
  "reply": "متن پاسخ تولید شده توسط هوش مصنوعی...",
  "metadata": {
    "cost": 12.5,          // هزینه کل کسر شده (تومان)
    "input_cost": 5.0,     // هزینه پردازش متن ورودی
    "output_cost": 7.5     // هزینه تولید متن خروجی
  }
}

این اطلاعات به شما کمک می‌کند تا به کاربران خود نمایش دهید هزینه هر درخواست دقیقاً چقدر بوده است.

نمونه کدها

cURL

Terminal / Bash
curl -X POST "https://ai.darkzed.ir/gateway.php" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY_HERE" \
     -d '{
           "prompt": "سلام، کمی در مورد برنامه نویسی توضیح بده.",
           "model": "gemini-2.5-flash"
         }'

PHP (cURL)

example.php
<?php

$apiKey = 'YOUR_API_KEY_HERE'; // کلید ۶۴ کاراکتری
$url = 'https://ai.darkzed.ir/gateway.php';

$data = [
    'prompt' => 'Write a short poem about coding.',
    'model' => 'gpt-5-nano'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey
]);

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

echo $response;
?>

JavaScript (Fetch)

app.js
const generateAI = async () => {
    const apiKey = "YOUR_API_KEY_HERE";
    const url = "https://ai.darkzed.ir/gateway.php";

    const response = await fetch(url, {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "Authorization": `Bearer ${apiKey}`
        },
        body: JSON.stringify({
            prompt: "کوانتوم را به زبان ساده توضیح بده.",
            model: "gemini-2.5-flash"
        })
    });

    const result = await response.json();
    console.log(result);
};

generateAI();

مدیریت خطاها

این API خطاها را با کدهای وضعیت استاندارد HTTP برمی‌گرداند.

کد معنی توضیحات
200 OK درخواست با موفقیت پردازش شد.
400 Bad Request پارامترهای الزامی ارسال نشده‌اند (مثلاً prompt).
401 Unauthorized کلید API نامعتبر است یا با فرمت Bearer ارسال نشده است.
402 Payment Required موجودی حساب کافی نیست.
500 Server Error خطای داخلی سیستم.
502 Bad Gateway خطا در دریافت پاسخ از سرویس‌دهنده هوش مصنوعی.