به مستندات API سرویس هوش مصنوعی AI-Kar خوش آمدید. با استفاده از این API می‌توانید از قدرت تمام مدل‌های هوش مصنوعی ما در برنامه‌ها و سرویس‌های خود استفاده کنید. تمام درخواست‌ها از طریق متد POST به نقطه پایانی اصلی ارسال می‌شوند و هزینه آن‌ها از کیف پول شما در وب‌سایت کسر می‌گردد.
تمام درخواست‌ها به API باید احراز هویت شوند. برای این کار، باید کلید API خود را که از داشبورد دریافت کرده‌اید، در هدر Authorization قرار دهید.
Authorization: Bearer YOUR_API_KEYفراموش نکنید که YOUR_API_KEY را با کلید واقعی خود جایگزین کنید.
برای محافظت در برابر خطاهای شبکه (مانند تایم‌اوت) و جلوگیری از اجرای یا شارژ تکراری یک درخواست، API ما از مکانیزم **کلید تکرارپذیری** استفاده می‌کند. با ارسال یک کلید منحصر به فرد در هدر هر درخواست POST، شما تضمین می‌کنید که حتی اگر درخواست خود را چندین بار ارسال کنید، عملیات تنها **یک بار** اجرا و هزینه آن محاسبه می‌شود.
مهم: ارسال هدر Idempotency-Key برای تمام درخواست‌های POST **اجباری** است.
فرض کنید درخواستی برای تولید متن ارسال می‌کنید، اما قبل از دریافت پاسخ، ارتباط اینترنت شما قطع می‌شود. در این حالت شما نمی‌دانید آیا درخواست به سرور ما رسیده و هزینه کسر شده است یا نه. با استفاده از کلید تکرارپذیری، می‌توانید با اطمینان کامل همان درخواست را دوباره ارسال کنید. سرور ما درخواست تکراری را تشخیص داده و پاسخی را که از اجرای اول ذخیره کرده بود، بدون کسر هزینه جدید، به شما برمی‌گرداند.
Idempotency-Key قرار دهید.تمام درخواست‌های مربوط به مدل‌های چت، کد، تصویر، ویدئو و... به یک نقطه پایانی واحد ارسال می‌شوند:
POST https://ai-kar.com/v1/chat/completionsبدنه درخواست شما باید با فرمت JSON و شامل پارامترهای زیر باشد:
model (رشته - الزامی): شناسه مدلی که می‌خواهید استفاده کنید. لیست کامل شناسه‌ها در صفحه تعرفه‌ها موجود است.messages (آرایه - الزامی): تاریخچه گفتگو. باید حداقل شامل یک پیام با role: "user" باشد.تذکر نام مدل ها را که از صفحه تعرفه ها کپی می کنید حتما فاصله ها را حذف کنید درست مثل مثال های این صفحه نام مدل دقیق و بدون فاصله باشد .temperature, max_tokens و... که در ادامه توضیح داده می‌شوند.{
"model": "openai/gpt-4o",
"messages": [
{
"role": "user",
"content": "سلام، یک نام خلاقانه برای یک کافی شاپ پیشنهاد بده."
}
]
}برای مدل‌های تصویری، محتوای پیام شما همان دستور (prompt) ساخت تصویر است.
{
"model": "openai/dall-e-3",
"messages": [
{
"role": "user",
"content": "A futuristic city skyline at sunset, digital art"
}
],
"size": "1024x1024",
"quality": "hd"
}شما می‌توانید با ارسال پارامترهای اضافی در بدنه درخواست JSON، خروجی مدل‌ها را کنترل کنید. در اینجا به چند مورد مهم اشاره می‌کنیم:
temperature (دما): یک عدد بین ۰ تا ۲. مقادیر بالاتر (مثلا ۱.۲) پاسخ‌های خلاقانه‌تر و تصادفی‌تری تولید می‌کنند، در حالی که مقادیر پایین‌تر (مثلا ۰.۳) پاسخ‌ها را دقیق‌تر و قابل پیش‌بینی‌تر می‌کنند.
max_tokens (حداکثر توکن): یک عدد صحیح که حداکثر طول پاسخ را مشخص می‌کند. این پارامتر برای کنترل هزینه‌ها و جلوگیری از پاسخ‌های بیش از حد طولانی بسیار مفید است.
response_format (فرمت پاسخ): اگر مقدار آن را { "type": "json_object" } قرار دهید، مدل را مجبور می‌کند تا خروجی خود را در فرمت یک JSON معتبر ارائه دهد.
web_search (جستجو در وب): برای مدل‌هایی که از این قابلیت پشتیبانی می‌کنند، با قرار دادن مقدار true، به مدل اجازه می‌دهید از اطلاعات زنده و به‌روز وب برای پاسخ دادن استفاده کند.
در زیر می‌توانید نمونه کدهای آماده برای استفاده از API ما به زبان‌های مختلف را مشاهده کنید. فراموش نکنید که YOUR_API_KEY را با کلید API واقعی خود و هدر Idempotency-Key را در تمام درخواست‌های POST جایگزین کنید.
این کد نحوه ارسال یک درخواست با هدر تکرارپذیری و منطق ساده تلاش مجدد را نشان میدهد.
import requests
import uuid
API_URL = "https://ai-kar.com/v1/chat/completions"
API_KEY = "YOUR_API_KEY"
# کلید تکرارپذیری برای این عملیات منطقی
idempotency_key = str(uuid.uuid4())
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
"Idempotency-Key": idempotency_key
}
payload = {
"model": "google/gemini-2.0-flash",
"messages": [{"role": "user", "content": "۳ حقیقت جالب درباره کهکشان راه شیری بگو."}]
}
try:
response = requests.post(API_URL, headers=headers, json=payload, timeout=30)
response.raise_for_status()
print("پاسخ موفقیت‌آمیز:", response.json())
except requests.exceptions.RequestException as e:
print(f"خطا رخ داد: {e}")
print("تلاش مجدد با همان کلید...")
# در یک اپلیکیشن واقعی، می‌توانید با کمی تاخیر دوباره تلاش کنید
try:
# مهم: از همان headers (و همان idempotency_key) استفاده می‌کنیم
response = requests.post(API_URL, headers=headers, json=payload, timeout=30)
response.raise_for_status()
print("پاسخ در تلاش مجدد دریافت شد:", response.json())
except requests.exceptions.RequestException as retry_e:
print(f"تلاش مجدد نیز ناموفق بود: {retry_e}")
این کد نحوه استفاده از API در یک پروژه فرانت‌اند را نشان میدهد.
// تابعی برای ساخت UUID در جاوا اسکریپت
function generateUUID() {
return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
var r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8);
return v.toString(16);
});
}
const apiKey = "YOUR_API_KEY";
const apiUrl = "https://ai-kar.com/v1/chat/completions";
const payload = {
model: "google/gemini-2.0-flash",
messages: [{ role: "user", content: "چگونه می‌توانم انگیزه خود را برای ورزش افزایش دهم؟" }]
};
async function getAiResponse() {
// یک کلید جدید برای این عملیات بسازید
const idempotencyKey = generateUUID();
const headers = new Headers({
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json',
'Idempotency-Key': idempotencyKey
});
try {
const response = await fetch(apiUrl, {
method: 'POST',
headers: headers,
body: JSON.stringify(payload)
});
if (!response.ok) {
const errorData = await response.json();
throw new Error(errorData.error || `HTTP error! status: ${response.status}`);
}
const data = await response.json();
console.log('پاسخ موفقیت‌آمیز:', data.choices[0].message.content);
} catch (error) {
console.error("خطا در دریافت پاسخ:", error);
// در یک اپلیکیشن واقعی، اینجا منطق تلاش مجدد (retry) را با همان هدرها پیاده‌سازی کنید.
}
}
getAiResponse();
این کد نحوه ارسال درخواست API با هدر تکرارپذیری در PHP را نشان میدهد.
<?php
// تابعی برای ساخت UUID v4 در PHP
function guidv4($data = null) {
$data = $data ?? random_bytes(16);
assert(strlen($data) == 16);
$data[6] = chr(ord($data[6]) & 0x0f | 0x40);
$data[8] = chr(ord($data[8]) & 0x3f | 0x80);
return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($data), 4));
}
$apiKey = "YOUR_API_KEY";
$apiUrl = "https://ai-kar.com/v1/chat/completions";
// 1. یک کلید تکرارپذیری برای این درخواست بسازید
$idempotencyKey = guidv4();
// 2. آماده‌سازی هدرها
$headers = [
'Content-Type: application/json',
'Authorization: Bearer ' . $apiKey,
'Idempotency-Key: ' . $idempotencyKey
];
// 3. آماده‌سازی پیلود
$payload = [
"model" => "google/gemini-2.0-flash",
"messages" => [
["role" => "user", "content" => "بزرگترین اقیانوس جهان کدام است؟"]
]
];
$postData = json_encode($payload);
// 4. راه‌اندازی و اجرای cURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_TIMEOUT, 90);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if (curl_errno($ch)) {
echo 'خطای cURL: ' . curl_error($ch);
} elseif ($httpCode >= 400) {
echo "خطای HTTP: " . $httpCode . "\n";
echo "پاسخ سرور: " . $response;
} else {
$result = json_decode($response, true);
if ($result && !empty($result['choices'][0]['message']['content'])) {
echo $result['choices'][0]['message']['content'];
}
}
curl_close($ch);
?>