مستندات فنی API
به مستندات توسعهدهندگان دارکزد خوش آمدید. این رابط کاربری قدرتمند به شما امکان میدهد تا مدلهای پیشرفته هوش مصنوعی مانند Gemini و GPT-Nano را به سادگی و مستقیم در برنامههای خود ادغام کنید.
احراز هویت Token Bearer
دسترسی به API محدود به کاربران احراز هویت شده است. سیستم جدید احراز هویت ما از توکنهای Bearer برای امنیت بیشتر استفاده میکند. شما باید کلید API کامل خود را در هدر Authorization ارسال کنید.
Authorization: Bearer
کلید API یک رشته ۶۴ کاراکتری است که از پنل کاربری دریافت میکنید.
مدلها و تعرفهها
ما مدلهای متنوعی را متناسب با نیاز شما ارائه میدهیم. هزینهها بر اساس هر ۱۰۰۰ توکن محاسبه میشود.
| شناسه مدل (Model ID) | نام مدل | هزینه ورودی (هر ۱۰۰۰ توکن) | هزینه خروجی (هر ۱۰۰۰ توکن) |
|---|---|---|---|
gemini-2.5-flash |
Gemini Flash | ۶۰۰ تومان | ۶۰۰ تومان |
gpt-5-nano |
GPT Nano | ۶۰۰ تومان | ۶۰۰ تومان |
آدرس فراخوانی (Endpoint)
پارامترهای درخواست
یک آبجکت 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
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)
<?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)
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 | خطا در دریافت پاسخ از سرویسدهنده هوش مصنوعی. |