مستندات API سرویس AI-Kar

مقدمه

به مستندات API سرویس هوش مصنوعی AI-Kar خوش آمدید. با استفاده از این API می‌توانید از قدرت تمام مدل‌های هوش مصنوعی ما در برنامه‌ها و سرویس‌های خود استفاده کنید. تمام درخواست‌ها از طریق متد POST به نقطه پایانی اصلی ارسال می‌شوند و هزینه آن‌ها از کیف پول شما در وب‌سایت کسر می‌گردد.

احراز هویت (Authentication)

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

ساختار هدر

Authorization: Bearer YOUR_API_KEY

فراموش نکنید که YOUR_API_KEY را با کلید واقعی خود جایگزین کنید.

نقطه پایانی اصلی (Endpoint)

تمام درخواست‌های مربوط به مدل‌های چت، کد، تصویر، ویدئو و... به یک نقطه پایانی واحد ارسال می‌شوند:

POST https://ai-kar.com/v1/chat/completions

ساختار درخواست (Request Body)

بدنه درخواست شما باید با فرمت JSON و شامل پارامترهای زیر باشد:

• model (رشته - الزامی): شناسه مدلی که می‌خواهید استفاده کنید. لیست کامل شناسه‌ها در صفحه تعرفه‌ها موجود است.
• messages (آرایه - الزامی): تاریخچه گفتگو. باید حداقل شامل یک پیام با role: "user" باشد.
• تذکر نام مدل ها را که از صفحه تعرفه ها کپی می کنید حتما فاصله ها را حذف کنید درست مثل مثال های این صفحه نام مدل دقیق و بدون فاصله باشد .
• ... (پارامترهای اختیاری): پارامترهای دیگری مانند temperature, max_tokens و... که در ادامه توضیح داده می‌شوند.

مثال ۱: درخواست متنی ساده

{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "سلام، یک نام خلاقانه برای یک کافی شاپ پیشنهاد بده."
    }
  ]
}

مثال ۲: درخواست تولید تصویر (Text-to-Image)

برای مدل‌های تصویری، محتوای پیام شما همان دستور (prompt) ساخت تصویر است.

{
  "model": "openai/dall-e-3",
  "messages": [
    {
      "role": "user",
      "content": "A futuristic city skyline at sunset, digital art"
    }
  ],
  "size": "1024x1024",
  "quality": "hd"
}

مثال ۳: درخواست تولید ویدئو با گزینه‌های پیشرفته (Text-to-Video)

برای مدل‌های ویدئویی، می‌توانید پارامترهای خاص مانند مدت زمان و حرکت را مشخص کنید.

{
  "model": "runway/gen4_turbo",
  "messages": [
    {
      "role": "user",
      "content": "A cinematic shot of a lone astronaut walking on Mars"
    }
  ],
  "motion": 8,
  "duration": 5
}

پارامترهای مهم و پرکاربرد

شما می‌توانید با ارسال پارامترهای اضافی در بدنه درخواست JSON، خروجی مدل‌ها را کنترل کنید. در اینجا به چند مورد مهم اشاره می‌کنیم:

مثال‌های کد (Code Snippets)

در زیر می‌توانید نمونه کدهای آماده برای استفاده از API ما به زبان‌های مختلف را مشاهده کنید. فراموش نکنید که YOUR_API_KEY را با کلید API واقعی خود جایگزین کنید.

مثال با Python

این کد نحوه ارسال یک درخواست ساده و یک درخواست پیشرفته با کتابخانه requests را نشان می‌دهد.

import requests
import json

API_KEY = "YOUR_API_KEY"
API_URL = "https://ai-kar.com/v1/chat/completions"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# --- مثال ۱: درخواست ساده ---
print("--- درخواست ساده ---")
simple_payload = {
    "model": "google/gemini-2.0-flash",
    "messages": [
        {
            "role": "user",
            "content": "۳ حقیقت جالب درباره کهکشان راه شیری بگو."
        }
    ]
}

try:
    response = requests.post(API_URL, headers=headers, json=simple_payload)
    response.raise_for_status()
    data = response.json()
    print(data['choices'][0]['message']['content'])
except requests.exceptions.RequestException as e:
    print(f"خطا: {e}")


# --- مثال ۲: درخواست پیشرفته با گزینه‌ها ---
print("\n--- درخواست پیشرفته ---")
advanced_payload = {
    "model": "google/gemini-2.0-flash",
    "messages": [
        {
            "role": "system",
            "content": "تو یک دستیار خلاق هستی که در زمینه نام‌گذاری تخصص داری."
        },
        {
            "role": "user",
            "content": "یک نام منحصر به فرد برای یک برند قهوه که حس لوکس بودن می‌دهد، پیشنهاد بده."
        }
    ],
    "temperature": 0.9,
    "top_p": 0.8,
    "max_tokens": 100
}

try:
    response = requests.post(API_URL, headers=headers, json=advanced_payload)
    response.raise_for_status()
    data = response.json()
    print(data['choices'][0]['message']['content'])
except requests.exceptions.RequestException as e:
    print(f"خطا: {e}")

مثال با JavaScript (در مرورگر)

این کد نحوه استفاده از API در یک پروژه فرانت‌اند با استفاده از fetch را نشان می‌دهد.

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: "چگونه می‌توانم انگیزه خود را برای ورزش افزایش دهم؟"
    }
  ],
  temperature: 0.7,
  max_tokens: 300
};

async function getAiResponse() {
  try {
    const response = await fetch(apiUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
      },
      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);
    // document.getElementById('result').innerText = data.choices[0].message.content;

  } catch (error) {
    console.error("خطا در دریافت پاسخ:", error);
  }
}

getAiResponse();

مثال با Node.js

برای استفاده در بک‌اند با Node.js، می‌توانید از کتابخانه‌ای مانند axios یا node-fetch استفاده کنید.

// ابتدا axios را نصب کنید: npm install axios
const axios = require('axios');

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() {
  try {
    const response = await axios.post(apiUrl, payload, {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      }
    });
    
    console.log(response.data.choices[0].message.content);

  } catch (error) {
    if (error.response) {
      // سرور با یک کد وضعیت خطا پاسخ داده است
      console.error("خطا از سرور API:", error.response.status, error.response.data);
    } else if (error.request) {
      // درخواست ارسال شده اما پاسخی دریافت نشده
      console.error("پاسخی از سرور دریافت نشد:", error.request);
    } else {
      // خطایی در تنظیم درخواست رخ داده
      console.error("خطا در تنظیم درخواست:", error.message);
    }
  }
}

getAiResponse();

مثال با PHP (cURL)

این کد نحوه ارسال درخواست API با استفاده از cURL در PHP را نشان می‌دهد که روی اکثر سرورهای وب در دسترس است.

<?php

$apiKey = "YOUR_API_KEY";
$apiUrl = "https://ai-kar.com/v1/chat/completions";

// تابع کمکی برای ارسال درخواست به API
function callAiKarApi($url, $key, $payload) {
    // 1. آماده‌سازی هدرها
    $headers = [
        'Content-Type: application/json',
        'Authorization: Bearer ' . $key
    ];

    // 2. تبدیل آرایه پیلود به رشته JSON
    $postData = json_encode($payload);

    // 3. راه‌اندازی cURL
    $ch = curl_init();

    // 4. تنظیم گزینه‌های cURL
    curl_setopt($ch, CURLOPT_URL, $url);
    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); // 90 ثانیه زمان انتظار

    // 5. اجرای درخواست
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    // 6. بررسی خطاها
    if (curl_errno($ch)) {
        echo 'خطای cURL: ' . curl_error($ch);
        return null;
    }

    if ($httpCode >= 400) {
        echo "خطای HTTP: " . $httpCode . "\n";
        echo "پاسخ سرور: " . $response;
        return null;
    }
    
    // 7. بستن cURL و بازگرداندن نتیجه
    curl_close($ch);
    return json_decode($response, true);
}

// --- مثال ۱: درخواست ساده ---
echo "--- درخواست ساده ---\n";
$simplePayload = [
    "model" => "google/gemini-2.0-flash",
    "messages" => [
        ["role" => "user", "content" => "بزرگترین اقیانوس جهان کدام است؟"]
    ]
];

$resultSimple = callAiKarApi($apiUrl, $apiKey, $simplePayload);
if ($resultSimple && !empty($resultSimple['choices'][0]['message']['content'])) {
    echo $resultSimple['choices'][0]['message']['content'];
}

echo "\n\n";

// --- مثال ۲: درخواست پیشرفته ---
echo "--- درخواست پیشرفته ---\n";
$advancedPayload = [
    "model" => "openai/gpt-4o",
    "messages" => [
        ["role" => "user", "content" => "یک شعار تبلیغاتی برای یک ماشین برقی بنویس."]
    ],
    "temperature" => 0.9,
    "max_tokens" => 50
];

$resultAdvanced = callAiKarApi($apiUrl, $apiKey, $advancedPayload);
if ($resultAdvanced && !empty($resultAdvanced['choices'][0]['message']['content'])) {
    echo $resultAdvanced['choices'][0]['message']['content'];
}

?>