آموزش و راهنما

API هوش مصنوعی چیست؟ راهنمای کامل انتخاب، دریافت و استفاده از AI API

راهنمای جامع API هوش مصنوعی؛ از تعریف و معماری تا انتخاب مدل، دریافت API Key، محاسبه هزینه، امنیت و اتصال نرم‌افزارها به مدل‌های متن، تصویر، صوت و ویدئو.

Darvareh AI API

API هوش مصنوعی چیست؟

API هوش مصنوعی رابطی برنامه‌نویسی است که به وب‌سایت‌ها، اپلیکیشن‌ها و نرم‌افزارها اجازه می‌دهد قابلیت‌هایی مانند تولید متن، ساخت تصویر، تحلیل داده، تبدیل گفتار، تولید ویدئو و اجرای Agentهای هوشمند را از طریق درخواست‌های استاندارد به مدل‌های هوش مصنوعی اضافه کنند.

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

برای مثال، یک فروشگاه اینترنتی می‌تواند متن سؤال مشتری را به API ارسال کند و پاسخ مناسب دریافت کند. یک نرم‌افزار مدیریت ارتباط با مشتری می‌تواند پیام‌های ورودی را دسته‌بندی کند. یک اپلیکیشن طراحی می‌تواند با ارسال توضیح متنی، تصویر تولید کند. یک سیستم سازمانی نیز می‌تواند اسناد داخلی را تحلیل کند یا Agentهایی بسازد که با ابزارهای مختلف کار می‌کنند.

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

API چیست؟

API مخفف Application Programming Interface و به معنی رابط برنامه‌نویسی کاربردی است. API مجموعه‌ای از قواعد، Endpointها و قالب‌های مشخص است که دو نرم‌افزار از طریق آن با یکدیگر ارتباط برقرار می‌کنند.

فرض کنید اپلیکیشن شما باید وضعیت آب‌وهوا را نمایش دهد. به‌جای ساخت ایستگاه هواشناسی، برنامه یک درخواست به API هواشناسی ارسال می‌کند و پاسخ را دریافت می‌کند.

در API هوش مصنوعی نیز همین مفهوم وجود دارد:

نرم‌افزار شما
→ درخواست API
→ مدل هوش مصنوعی
→ پردازش
→ پاسخ API
→ نرم‌افزار شما

درخواست معمولاً شامل این اطلاعات است:

API Key
شناسه مدل
پیام یا ورودی
تنظیمات تولید
قالب خروجی
ابزارها یا Functionها
محدودیت تعداد Token
گزینه Streaming

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

متن تولیدشده
تصویر یا آدرس فایل
نتیجه تحلیل
Tool Call
میزان Token مصرف‌شده
دلیل پایان پاسخ
شناسه درخواست
اطلاعات هزینه یا Usage
پیام خطا

API هوش مصنوعی چگونه کار می‌کند؟

فرایند کلی استفاده از API مدل‌های هوش مصنوعی شامل چند مرحله است.

۱. دریافت API Key

کاربر در پلتفرم ارائه‌دهنده ثبت‌نام و یک API Key ایجاد می‌کند. این کلید هویت و سطح دسترسی درخواست را مشخص می‌کند.

نمونه Header:

Authorization: Bearer YOUR_API_KEY

API Key مانند رمز عبور فنی نرم‌افزار شماست و نباید در کد Frontend، Repository عمومی یا اپلیکیشن قابل مشاهده قرار گیرد.

۲. انتخاب مدل

هر مدل قابلیت، سرعت، هزینه و Context Window متفاوتی دارد. بعضی مدل‌ها برای متن، برخی برای تصویر، صوت، ویدئو، کدنویسی یا استدلال طراحی شده‌اند.

در درخواست باید Model ID دقیق وارد شود:

{
  "model": "YOUR_MODEL_ID"
}

۳. ساخت درخواست

نرم‌افزار ورودی کاربر را در قالب مورد انتظار API ارسال می‌کند.

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

{
  "model": "YOUR_MODEL_ID",
  "messages": [
    {
      "role": "system",
      "content": "شما یک دستیار فارسی دقیق هستید."
    },
    {
      "role": "user",
      "content": "API هوش مصنوعی را توضیح بده."
    }
  ]
}

۴. پردازش توسط مدل

API درخواست را به مدل مناسب هدایت می‌کند. مدل بر اساس ورودی، Context و تنظیمات، پاسخ را تولید می‌کند.

۵. دریافت پاسخ

نتیجه معمولاً به شکل JSON بازمی‌گردد:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "API هوش مصنوعی رابطی برای اتصال نرم‌افزار به مدل‌های هوش مصنوعی است."
      },
      "finish_reason": "stop"
    }
  ]
}

۶. استفاده در نرم‌افزار

Backend پاسخ را اعتبارسنجی و سپس آن را در رابط کاربری، Workflow یا دیتابیس استفاده می‌کند.

تفاوت API هوش مصنوعی با ChatGPT چیست؟

ChatGPT یک محصول نهایی برای تعامل مستقیم کاربران با مدل‌های هوش مصنوعی است. کاربر وارد محیط چت می‌شود و سؤال خود را مطرح می‌کند.

API هوش مصنوعی برای برنامه‌نویسان و نرم‌افزارها طراحی شده است. با API می‌توانید قابلیت هوش مصنوعی را داخل محصول خود قرار دهید.

ویژگی	اپلیکیشن چت	API هوش مصنوعی
استفاده مستقیم کاربر	بله	معمولاً از طریق نرم‌افزار
اتصال به سایت	محدود	بله
اتصال به اپلیکیشن	محدود	بله
کنترل System Prompt	محدودتر	گسترده
طراحی رابط اختصاصی	خیر	بله
اتصال به دیتابیس	مستقیم نیست	از طریق Backend
ساخت RAG	محدود	بله
ساخت Agent	محدود	بله
محاسبه مصرف	معمولاً اشتراکی	بر اساس Usage
انتخاب Workflow	محدود	قابل برنامه‌ریزی

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

تفاوت API هوش مصنوعی با مدل هوش مصنوعی

مدل هوش مصنوعی موتور پردازش است. API روش استاندارد دسترسی نرم‌افزار به آن موتور است.

برای مثال:

مدل، متن را تحلیل می‌کند
API، ورودی را به مدل می‌رساند
مدل، پاسخ را تولید می‌کند
API، پاسخ را به برنامه برمی‌گرداند

ممکن است یک مدل از طریق چند Provider و چند API مختلف در دسترس باشد. کیفیت مدل یکسان است، اما موارد زیر میان Providerها تفاوت دارند:

پایداری
Latency
قیمت
Rate Limit
فرمت API
مکان پردازش
قابلیت Fallback
پشتیبانی
گزارش مصرف
روش پرداخت

انواع API هوش مصنوعی

APIهای هوش مصنوعی فقط برای تولید متن نیستند. انواع مختلفی از مدل‌ها از طریق API در دسترس‌اند.

API مدل‌های زبانی و تولید متن

API مدل زبانی یا LLM API برای درک و تولید متن استفاده می‌شود.

کاربردها:

تولید محتوا
پاسخ‌گویی به مشتری
خلاصه‌سازی
ترجمه
تحلیل متن
استخراج اطلاعات
تولید کد
بازنویسی متن
دسته‌بندی پیام‌ها
پاسخ به پرسش
تحلیل احساسات
ساخت Agent

نمونه Endpoint رایج:

POST /v1/chat/completions

API تولید تصویر

API تولید تصویر توضیح متنی را دریافت و تصویر تولید می‌کند.

کاربردها:

طراحی محتوای شبکه اجتماعی
ساخت تصویر محصول
تصویرسازی مقاله
تبلیغات
Concept Art
تولید Mockup
ویرایش تصویر
حذف یا تغییر پس‌زمینه
ساخت Variation
Inpainting و Outpainting

در APIهای تصویری، هزینه ممکن است بر اساس این عوامل محاسبه شود:

تعداد تصاویر
ابعاد
کیفیت
تعداد مراحل تولید
نوع مدل
ورودی و خروجی
Tokenهای تصویری
مدت پردازش

به همین دلیل، هزینه تولید تصویر را نباید همیشه فقط از روی Token متنی پاسخ محاسبه کرد.

API تحلیل تصویر

مدل‌های Vision می‌توانند تصویر را همراه با Prompt دریافت و تحلیل کنند.

کاربردها:

استخراج اطلاعات از تصویر
تشخیص اجزای تصویر
پاسخ به سؤال درباره عکس
بررسی Screenshot
تحلیل نمودار
خواندن سند
تحلیل محصول
بررسی رابط کاربری
کنترل کیفیت بصری

ورودی تصویر می‌تواند به دو شکل ارسال شود:

URL عمومی
داده Base64

URL برای تصویر عمومی معمولاً کارآمدتر است. Base64 برای فایل محلی یا خصوصی استفاده می‌شود.

API تولید ویدئو

API تولید ویدئو می‌تواند از متن، تصویر یا Referenceهای مختلف ویدئو بسازد.

قابلیت‌ها بسته به مدل ممکن است شامل این موارد باشند:

Text-to-Video
Image-to-Video
First Frame
First and Last Frame
Reference-to-Video
تغییر نسبت تصویر
کنترل مدت
کنترل وضوح
تولید صدا
حفظ شخصیت
ویرایش ویدئو

هزینه API ویدئو معمولاً به موارد زیر وابسته است:

مدت ویدئو
Resolution
Frame Rate
مدل
کیفیت
تعداد Generation
Tokenهای ویدئویی
صدا
زمان پردازش

API صوت و گفتار

APIهای صوتی چند گروه مهم دارند.

تبدیل گفتار به متن

Speech-to-Text صدای ورودی را به متن تبدیل می‌کند.

کاربردها:

پیاده‌سازی جلسه
زیرنویس
مرکز تماس
جست‌وجوی صوت
تبدیل مصاحبه به متن
فرمان صوتی

تبدیل متن به گفتار

Text-to-Speech متن را به صدای مصنوعی تبدیل می‌کند.

کاربردها:

دستیار صوتی
کتاب صوتی
آموزش
خواندن مقاله
پاسخ صوتی
تولید محتوای چندرسانه‌ای

Voice Agent

Voice Agent صدا را دریافت می‌کند، آن را تحلیل می‌کند، از ابزارها استفاده می‌کند و پاسخ صوتی می‌دهد.

API Embedding

Embedding متن، تصویر یا داده را به برداری عددی تبدیل می‌کند که معنای آن را نمایش می‌دهد.

کاربردها:

جست‌وجوی معنایی
RAG
تشخیص شباهت
پیشنهاد محتوا
خوشه‌بندی
حذف موارد تکراری
طبقه‌بندی
بازیابی اسناد مرتبط

نمونه جریان RAG:

سند
→ Chunking
→ Embedding
→ Vector Database

سؤال کاربر
→ Embedding
→ جست‌وجوی برداری
→ اسناد مرتبط
→ مدل زبانی
→ پاسخ

API کدنویسی

مدل‌های Coding می‌توانند در تولید، تحلیل و اصلاح کد استفاده شوند.

کاربردها:

تکمیل کد
تولید تابع
رفع Bug
ساخت Unit Test
توضیح Repository
Code Review
Refactor
تولید مستندات
مهاجرت Framework
Coding Agent

API استدلال

مدل‌های Reasoning برای وظایفی طراحی شده‌اند که به تحلیل چندمرحله‌ای نیاز دارند.

کاربردها:

حل مسئله پیچیده
تحلیل معماری
برنامه‌ریزی
Debug چندلایه
تحلیل داده
تصمیم‌سازی
Agentهای چندمرحله‌ای
بررسی سناریوها

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

API هوش مصنوعی برای Agentها

Agent از مدل برای تصمیم‌گیری و از Toolها برای اقدام استفاده می‌کند.

یک Agent ممکن است:

پیام کاربر را تحلیل کند
ابزار مناسب را انتخاب کند
API داخلی را فراخوانی کند
نتیجه را بررسی کند
ابزار دیگری را اجرا کند
پاسخ نهایی بسازد

نمونه ابزارها:

دریافت وضعیت سفارش
جست‌وجو در CRM
ساخت Ticket
خواندن دیتابیس
ارسال ایمیل
جست‌وجوی پایگاه دانش
اجرای کد
تحلیل فایل
دریافت اطلاعات مالی

Agent نباید برای عملیات حساس کاملاً خودمختار باشد. ابزارهای مالی، حذف، ارسال پیام یا تغییر داده بهتر است نیازمند تأیید انسانی باشند.

API هوش مصنوعی چه کاربردهایی دارد؟

اتصال هوش مصنوعی به سایت

می‌توان قابلیت‌های زیر را به وب‌سایت اضافه کرد:

دستیار پاسخ‌گویی
جست‌وجوی هوشمند
پیشنهاد محصول
خلاصه‌سازی محتوا
تولید توضیحات محصول
پاسخ بر اساس مستندات
تحلیل فرم‌ها
دسته‌بندی درخواست‌ها
تولید تصویر
ترجمه محتوا

معماری صحیح:

Browser
→ Backend سایت
→ API هوش مصنوعی
→ Backend
→ Browser

API Key نباید مستقیماً در مرورگر قرار گیرد.

اتصال هوش مصنوعی به اپلیکیشن موبایل

در اپلیکیشن موبایل نیز درخواست باید از طریق Backend امن ارسال شود:

Mobile App
→ Application Backend
→ AI API

قرار دادن API Key در APK یا کد اپلیکیشن باعث افشای آن می‌شود.

ساخت چت‌بات اختصاصی

API هوش مصنوعی به شما اجازه می‌دهد:

رابط کاربری اختصاصی بسازید
System Prompt تعیین کنید
مدل انتخاب کنید
تاریخچه مکالمه نگه دارید
RAG اضافه کنید
Tool Calling پیاده‌سازی کنید
محدودیت مصرف اعمال کنید
پاسخ را با داده سازمان ترکیب کنید

هوشمندسازی CRM

کاربردها:

خلاصه‌سازی گفتگو
دسته‌بندی Lead
پیشنهاد پاسخ
استخراج نیاز مشتری
اولویت‌بندی فرصت
تحلیل احساسات
تولید Follow-up
تکمیل اطلاعات ساختاریافته

Agent نباید بدون تأیید، پیام خارجی ارسال یا تعهد تجاری ایجاد کند.

پشتیبانی مشتری

سیستم پشتیبانی می‌تواند:

پاسخ را از پایگاه دانش پیدا کند
Ticket را دسته‌بندی کند
اولویت تعیین کند
پیام را خلاصه کند
اطلاعات سفارش را دریافت کند
پاسخ پیشنهادی بسازد
موضوع حساس را به اپراتور ارجاع دهد

تحلیل اسناد

API هوش مصنوعی در پردازش اسناد کاربرد دارد:

خلاصه‌سازی
استخراج نام، تاریخ و مبلغ
مقایسه قراردادها
تشخیص بندهای مهم
پرسش‌وپاسخ
طبقه‌بندی
تولید گزارش
بررسی تفاوت نسخه‌ها

برای اطلاعات حساس باید سیاست نگهداری داده، سطح دسترسی و Logها را کنترل کنید.

تولید محتوا

کاربردها:

مقاله
توضیحات محصول
کپشن
ایمیل
عنوان
متن تبلیغاتی
بازنویسی
ویرایش
ترجمه
خلاصه‌سازی

محتوای تولیدشده باید از نظر صحت، لحن، حق نشر و اطلاعات ساختگی بررسی شود.

OpenAI-compatible API چیست؟

API سازگار با OpenAI یا OpenAI-compatible API از ساختار رایج API و SDKهای OpenAI پیروی می‌کند.

مزیت اصلی آن این است که برنامه‌نویس می‌تواند با تغییر موارد محدودی مانند Base URL، API Key و Model ID، از یک زیرساخت یا Provider دیگر استفاده کند.

نمونه Python:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_DARVAREH_API_KEY",
    base_url="https://api.darvareh.ir/v1",
)

مزایا:

استفاده از SDKهای آشنا
مهاجرت ساده‌تر
کاهش Vendor Lock-in
اتصال ابزارهای مختلف
امکان تغییر مدل
نگهداری ساده‌تر کد
استفاده از Frameworkهای سازگار

OpenAI-compatible بودن لزوماً به معنی پشتیبانی از تمام قابلیت‌های اختصاصی هر Provider نیست. قابلیت‌هایی مانند Responses API، Hosted Tools، Realtime یا بعضی پارامترهای اختصاصی باید جداگانه بررسی شوند.

API هوش مصنوعی درواره

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

Base URL:

https://api.darvareh.ir/v1

در معماری درواره، توسعه‌دهنده به‌جای پیاده‌سازی اتصال جداگانه برای هر Provider، از یک نقطه اتصال واحد استفاده می‌کند.

مزایا:

API سازگار با OpenAI
دسترسی به مدل‌های مختلف
استفاده از یک API Key
پرداخت ریالی
مشاهده مصرف
مدیریت کلیدها
استفاده در Python، JavaScript و PHP
اتصال به Frameworkهای هوش مصنوعی
کاهش پیچیدگی Integration
امکان استفاده از مدل متناسب با هر کاربرد

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

چگونه API Key هوش مصنوعی دریافت کنیم؟

فرایند معمول:

در پلتفرم ثبت‌نام کنید
وارد داشبورد توسعه‌دهندگان شوید
بخش API Key را باز کنید
یک کلید جدید ایجاد کنید
نام و محدودیت مناسب تعیین کنید
کلید را فقط یک‌بار در محل امن ذخیره کنید
اعتبار کیف پول یا Billing را بررسی کنید
اولین درخواست را آزمایش کنید

بهتر است برای هر محیط کلید جدا داشته باشید:

Development
Staging
Production
CI/CD
دستگاه توسعه‌دهنده
شریک تجاری

استفاده از یک کلید مشترک برای همه محیط‌ها، ابطال و تحلیل مصرف را دشوار می‌کند.

مشاهده مدل‌های فعال

curl https://api.darvareh.ir/v1/models \
  -H "Authorization: Bearer $DARVAREH_API_KEY"

پاسخ معمولاً شامل Model IDهاست:

{
  "object": "list",
  "data": [
    {
      "id": "MODEL_ID",
      "object": "model"
    }
  ]
}

Model ID را عیناً در درخواست استفاده کنید.

اولین درخواست با cURL

curl https://api.darvareh.ir/v1/chat/completions \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {
        "role": "system",
        "content": "شما یک دستیار فارسی دقیق هستید."
      },
      {
        "role": "user",
        "content": "API هوش مصنوعی چیست؟"
      }
    ],
    "temperature": 0.2
  }'

استفاده با Python

نصب SDK:

pip install openai

کد:

import os

from openai import OpenAI


client = OpenAI(
    api_key=os.environ[
        "DARVAREH_API_KEY"
    ],
    base_url=(
        "https://api.darvareh.ir/v1"
    ),
)

response = (
    client.chat.completions.create(
        model="YOUR_MODEL_ID",
        messages=[
            {
                "role": "system",
                "content": (
                    "شما یک دستیار "
                    "فارسی دقیق هستید."
                ),
            },
            {
                "role": "user",
                "content": (
                    "سه کاربرد API "
                    "هوش مصنوعی را بگو."
                ),
            },
        ],
        temperature=0.2,
    )
)

print(
    response.choices[0]
    .message.content
)

API Key را در Environment قرار دهید:

export DARVAREH_API_KEY="YOUR_API_KEY"

استفاده با JavaScript و Node.js

نصب:

npm install openai

کد:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DARVAREH_API_KEY,
  baseURL: "https://api.darvareh.ir/v1",
});

const response =
  await client.chat.completions.create({
    model: "YOUR_MODEL_ID",
    messages: [
      {
        role: "system",
        content:
          "شما یک دستیار فارسی دقیق هستید.",
      },
      {
        role: "user",
        content:
          "API هوش مصنوعی را توضیح بده.",
      },
    ],
    temperature: 0.2,
  });

console.log(
  response.choices[0].message.content
);

استفاده با Fetch

const response = await fetch(
  "https://api.darvareh.ir/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization:
        `Bearer ${process.env.DARVAREH_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "YOUR_MODEL_ID",
      messages: [
        {
          role: "user",
          content:
            "API هوش مصنوعی چیست؟",
        },
      ],
    }),
  }
);

if (!response.ok) {
  throw new Error(
    `API request failed: ${response.status}`
  );
}

const data = await response.json();

console.log(
  data.choices[0].message.content
);

این کد باید در Backend اجرا شود، نه JavaScript مرورگر.

استفاده با PHP

<?php

$apiKey = getenv(
    'DARVAREH_API_KEY'
);

$payload = [
    'model' => 'YOUR_MODEL_ID',
    'messages' => [
        [
            'role' => 'system',
            'content' =>
                'شما یک دستیار فارسی دقیق هستید.',
        ],
        [
            'role' => 'user',
            'content' =>
                'API هوش مصنوعی چیست؟',
        ],
    ],
    'temperature' => 0.2,
];

$ch = curl_init(
    'https://api.darvareh.ir/v1/chat/completions'
);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS =>
        json_encode(
            $payload,
            JSON_UNESCAPED_UNICODE
        ),
    CURLOPT_TIMEOUT => 60,
]);

$response = curl_exec($ch);
$statusCode = curl_getinfo(
    $ch,
    CURLINFO_HTTP_CODE
);

if ($response === false) {
    throw new Exception(
        curl_error($ch)
    );
}

curl_close($ch);

if ($statusCode >= 400) {
    throw new Exception(
        'API error: ' . $response
    );
}

$data = json_decode(
    $response,
    true
);

echo $data['choices'][0]
    ['message']['content'];

نقش پیام‌ها در API

در Chat Completions معمولاً سه Role اصلی وجود دارد.

System

رفتار کلی مدل را تعیین می‌کند:

{
  "role": "system",
  "content": "پاسخ‌ها را کوتاه و فارسی ارائه کن."
}

User

پیام کاربر:

{
  "role": "user",
  "content": "این متن را خلاصه کن."
}

Assistant

پاسخ‌های قبلی مدل برای حفظ تاریخچه:

{
  "role": "assistant",
  "content": "خلاصه قبلی..."
}

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

Token چیست؟

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

مصرف کلی معمولاً شامل:

Input Tokens
Output Tokens
Cached Tokens
Reasoning Tokens، بسته به مدل

هزینه تقریبی:

هزینه ورودی =
تعداد Token ورودی
÷ ۱٬۰۰۰٬۰۰۰
× قیمت ورودی مدل

هزینه خروجی =
تعداد Token خروجی
÷ ۱٬۰۰۰٬۰۰۰
× قیمت خروجی مدل

در مدل‌های تصویر، صوت و ویدئو ممکن است روش محاسبه متفاوت باشد.

Context Window چیست؟

Context Window حداکثر اطلاعاتی است که مدل در یک درخواست یا مکالمه می‌تواند پردازش کند.

Context شامل:

System Prompt
پیام کاربر
تاریخچه گفتگو
اسناد RAG
Tool Schema
نتیجه ابزارها
خروجی مدل

Context بزرگ‌تر همیشه بهتر نیست. اطلاعات نامرتبط می‌تواند هزینه را افزایش و دقت را کاهش دهد.

Temperature چیست؟

Temperature میزان تنوع احتمالی خروجی را کنترل می‌کند.

مقادیر پایین برای:

استخراج اطلاعات
تحلیل
کدنویسی
پاسخ دقیق
طبقه‌بندی

مقادیر بالاتر برای:

ایده‌پردازی
داستان
متن تبلیغاتی
تنوع خروجی

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

{
  "temperature": 0.1
}

همه مدل‌ها تمام پارامترهای Sampling را یکسان پشتیبانی نمی‌کنند.

Streaming چیست؟

در حالت معمول، برنامه تا تکمیل پاسخ منتظر می‌ماند. در Streaming، پاسخ به‌تدریج ارسال می‌شود.

مزایا:

نمایش سریع اولین بخش پاسخ
تجربه کاربری بهتر
مناسب برای پاسخ‌های طولانی
کاهش زمان انتظار ادراکی

Streaming هزینه Token را لزوماً کاهش نمی‌دهد؛ فقط نحوه دریافت پاسخ را تغییر می‌دهد.

Structured Outputs

Structured Output به مدل اجازه می‌دهد خروجی مطابق Schema مشخص تولید کند.

مثال:

{
  "category": "billing",
  "priority": "high",
  "requires_human": true,
  "summary": "کاربر درباره کسر هزینه گزارش داده است."
}

کاربردها:

دسته‌بندی Ticket
استخراج اطلاعات
اتصال به دیتابیس
ساخت Workflow
تحلیل فرم
تولید داده Type-safe

خروجی مدل حتی اگر JSON معتبر باشد، باید از نظر قواعد کسب‌وکار اعتبارسنجی شود.

Tool Calling

Tool Calling به مدل اجازه می‌دهد درخواست اجرای یک Function را تولید کند.

مثال:

{
  "name": "get_order_status",
  "arguments": {
    "order_id": "ORD-1001"
  }
}

Backend ابزار را اجرا و نتیجه را به مدل برمی‌گرداند.

مدل ابزار را مستقیماً اجرا نمی‌کند؛ Runtime برنامه مسئول اجرای آن است.

Tool Calling برای این موارد استفاده می‌شود:

API خارجی
دیتابیس
CRM
وضعیت سفارش
جست‌وجوی دانش
محاسبه
ساخت Ticket
Agentها

Authorization باید داخل ابزار انجام شود، نه فقط در Prompt.

هزینه API هوش مصنوعی چگونه محاسبه می‌شود؟

هزینه به نوع مدل و Modalities بستگی دارد.

مدل‌های متنی

معمولاً بر اساس:

Token ورودی
Token خروجی
Token کش‌شده
Reasoning Token

مدل‌های تصویری

ممکن است بر اساس:

تعداد تصویر
Resolution
کیفیت
Token تصویری
نوع عملیات

مدل‌های صوتی

ممکن است بر اساس:

مدت صوت
تعداد کاراکتر
Token صوتی
نوع صدا

مدل‌های ویدئویی

ممکن است بر اساس:

مدت
عرض و ارتفاع
Frame Rate
کیفیت
مدل

Agentها

هزینه Agent مجموع چند فراخوانی است:

هزینه Agent =
فراخوانی‌های مدل
+ Tool Loop
+ RAG
+ Retry
+ Context
+ مدل‌های کمکی

چگونه هزینه API را کاهش دهیم؟

مدل مناسب Task را انتخاب کنید
Context غیرضروری را حذف کنید
خروجی را محدود کنید
تاریخچه گفتگو را خلاصه کنید
RAG هدفمند بسازید
Prompt تکراری را Cache کنید
Loop Agent را محدود کنید
برای Task ساده مدل سریع استفاده کنید
Token و هزینه را پایش کنید
Streaming را با مدیریت Usage اجرا کنید
Retry را محدود کنید
پاسخ‌های قابل Cache را ذخیره کنید
Tool Resultهای حجیم را خلاصه کنید

امنیت API Key

API Key را هرگز در این مکان‌ها قرار ندهید:

کد Frontend
Repository عمومی
اپلیکیشن موبایل
Screenshot
Log
Ticket پشتیبانی
فایل قابل دانلود
پیام عمومی

روش مناسب:

import os

api_key = os.environ[
    "DARVAREH_API_KEY"
]

در Production از Secret Manager استفاده کنید.

محدود کردن API Key

اگر پلتفرم امکانات لازم را ارائه می‌کند:

بودجه روزانه تعیین کنید
بودجه ماهانه تعیین کنید
RPM و TPM محدود کنید
IP Allowlist تنظیم کنید
کلید محیط‌ها را جدا کنید
کلیدهای قدیمی را ابطال کنید
مصرف غیرعادی را پایش کنید
کلید افشاشده را Rotate کنید

Rate Limit چیست؟

Rate Limit تعداد درخواست یا Token مجاز در یک بازه زمانی را محدود می‌کند.

اصطلاح‌های رایج:

RPM: درخواست در دقیقه
TPM: Token در دقیقه
RPD: درخواست در روز

در صورت عبور از محدودیت ممکن است خطای 429 دریافت شود.

مدیریت خطای 401

علت‌ها:

API Key اشتباه
کلید ابطال‌شده
Header ناقص
فاصله اضافی
استفاده از کلید محیط اشتباه

Header صحیح:

Authorization: Bearer YOUR_API_KEY

مدیریت خطای 403

کلید معتبر است اما اجازه دسترسی ندارد:

مدل مجاز نیست
Scope محدود است
حساب غیرفعال است
Policy سازمان مانع شده است

مدیریت خطای 404

علت‌های رایج:

Base URL اشتباه
Endpoint اشتباه
Model ID نامعتبر

Base URL صحیح:

https://api.darvareh.ir/v1

مدیریت خطای 429

اقدامات:

Retry با Backoff
کاهش هم‌زمانی
محدود کردن Loop
بررسی سهمیه
کاهش Context
استفاده از Queue
افزایش فاصله درخواست‌ها

Timeout

برای هر درخواست Timeout تعریف کنید:

client = OpenAI(
    api_key=os.environ[
        "DARVAREH_API_KEY"
    ],
    base_url=(
        "https://api.darvareh.ir/v1"
    ),
    timeout=60,
)

Timeout نامحدود باعث اشغال Connection و Worker می‌شود.

Retry

فقط خطاهای موقت را Retry کنید:

Timeout
خطای شبکه
۵xx
429

این خطاها معمولاً نباید مستقیم Retry شوند:

401
403
Validation Error
Model not found
موجودی ناکافی

از Exponential Backoff و Jitter استفاده کنید.

Fallback

Fallback یعنی در صورت شکست مدل یا Provider اصلی، مدل جایگزین استفاده شود.

مثال:

مدل اصلی
→ Timeout
→ مدل جایگزین

Fallback باید:

قابلیت مشابه داشته باشد
Policy امنیتی یکسان را رعایت کند
در Log ثبت شود
هزینه آن مشخص باشد
با Tool Calling سازگار باشد

انتخاب API هوش مصنوعی مناسب

این معیارها را بررسی کنید:

مدل‌های قابل دسترس
Modalities
سازگاری API
کیفیت مستندات
قیمت
روش پرداخت
Latency
پایداری
Rate Limit
Streaming
Tool Calling
Structured Output
امنیت
گزارش مصرف
Fallback
پشتیبانی
امکان تغییر مدل

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

API هوش مصنوعی رایگان

بعضی پلتفرم‌ها اعتبار اولیه یا مدل رایگان ارائه می‌کنند، اما معمولاً محدودیت‌هایی وجود دارد:

Rate Limit پایین
مدل محدود
Context کمتر
صف طولانی
عدم تضمین پایداری
استفاده آزمایشی
محدودیت تجاری

API رایگان برای یادگیری و Prototype مناسب است. برای Production باید پایداری، SLA، هزینه و دسترسی بررسی شوند.

API هوش مصنوعی ایرانی چه مزیتی دارد؟

برای توسعه‌دهندگان ایرانی، یک زیرساخت داخلی می‌تواند این مزایا را داشته باشد:

پرداخت ریالی
صدور صورتحساب داخلی
دسترسی ساده‌تر
پشتیبانی فارسی
کاهش پیچیدگی خرید ارزی
یک API Key برای مدل‌های مختلف
مستندات متناسب با کاربران ایرانی
مدیریت متمرکز مصرف

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

معماری پروداکشن

معماری پیشنهادی:

Client
→ Backend
→ Authentication
→ Rate Limit
→ Input Validation
→ AI Service Layer
→ API درواره
→ Output Validation
→ Logging and Usage
→ Client

لایه AI Service باید موارد زیر را مدیریت کند:

Model Selection
Prompt Versioning
Timeout
Retry
Fallback
Token
Cost
Error Mapping
Redaction
Observability

منطق AI را در Route یا Controller پراکنده نکنید.

Observability

برای هر درخواست ثبت کنید:

Request ID
Model ID
Latency
Input Token
Output Token
Status
Error Code
Retry
Fallback
Estimated Cost
User یا Organization Hash
Prompt Version

از ثبت Prompt و پاسخ حساس بدون Redaction خودداری کنید.

آیا باید یک مدل یا چند مدل استفاده کنیم؟

استفاده از چند مدل معمولاً منطقی‌تر است:

Task	نوع مدل
طبقه‌بندی	سریع و اقتصادی
خلاصه‌سازی	مدل استاندارد
استدلال پیچیده	مدل قوی
کدنویسی	مدل Coding
تصویر	مدل تصویری
ویدئو	مدل ویدئویی
صوت	مدل صوتی

این معماری Model Routing نام دارد.

جلوگیری از وابستگی به یک فروشنده

از API استاندارد استفاده کنید
Base URL را در Environment نگه دارید
Model ID را از Business Logic جدا کنید
Adapter بسازید
Contract Test داشته باشید
قابلیت‌های اختصاصی را ایزوله کنید
Fallback تعریف کنید
Prompt و Schema را Versioning کنید

پرسش‌های متداول

API هوش مصنوعی چیست؟

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

API هوش مصنوعی چه کاربردی دارد؟

تولید متن، تصویر، صوت و ویدئو، تحلیل داده، RAG، Agent، چت‌بات، ترجمه، خلاصه‌سازی و کدنویسی.

چگونه API هوش مصنوعی دریافت کنیم؟

در پلتفرم ارائه‌دهنده ثبت‌نام کنید، API Key بسازید، مدل را انتخاب و اولین درخواست را ارسال کنید.

آیا API هوش مصنوعی رایگان است؟

بعضی سرویس‌ها اعتبار یا مدل آزمایشی دارند، اما برای محیط عملیاتی معمولاً هزینه مصرف دارد.

قیمت API هوش مصنوعی چگونه محاسبه می‌شود؟

در مدل متنی معمولاً بر اساس توکن و در مدل‌های تصویر، صوت و ویدئو بر اساس واحدهایی مانند تعداد، کیفیت، مدت یا Resolution.

API Key چیست؟

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

آیا می‌توان API Key را در JavaScript سایت قرار داد؟

خیر. درخواست باید از Backend امن ارسال شود.

OpenAI-compatible API چیست؟

APIای که از ساختار رایج OpenAI پیروی می‌کند و امکان استفاده از SDKهای سازگار را فراهم می‌سازد.

Base URL درواره چیست؟

https://api.darvareh.ir/v1

فهرست مدل‌ها را چگونه دریافت کنیم؟

GET https://api.darvareh.ir/v1/models

آیا می‌توان با API درواره Agent ساخت؟

بله. می‌توانید Tool Calling، RAG، حافظه و Frameworkهایی مانند LangGraph را به API متصل کنید.

آیا API هوش مصنوعی برای Laravel مناسب است؟

بله. با HTTP Client یا OpenAI-compatible SDK می‌توان درخواست را از Backend Laravel ارسال کرد.

تفاوت RAG و API هوش مصنوعی چیست؟

API دسترسی به مدل را فراهم می‌کند. RAG معماری بازیابی اطلاعات و افزودن آن‌ها به Context مدل است.

آیا API هوش مصنوعی اطلاعات ساختگی تولید می‌کند؟

مدل ممکن است Hallucination داشته باشد. از RAG، Tool Calling، Structured Output، Validation و Review استفاده کنید.

بهترین API هوش مصنوعی کدام است؟

به مدل، هزینه، پایداری، سازگاری، روش پرداخت و نیاز پروژه بستگی دارد. یک پاسخ واحد برای تمام کاربردها وجود ندارد.

آیا Streaming هزینه را کاهش می‌دهد؟

معمولاً خیر. Streaming نحوه دریافت پاسخ را تغییر می‌دهد، نه لزوماً Token مصرفی را.

آیا می‌توان مدل را بعداً تغییر داد؟

اگر معماری استاندارد و Model ID قابل تنظیم داشته باشید، تغییر مدل ساده‌تر خواهد بود.

جمع‌بندی

API هوش مصنوعی رابطی است که نرم‌افزارها را به مدل‌های هوش مصنوعی متصل می‌کند. با استفاده از آن می‌توان قابلیت‌هایی مانند تولید متن، تصویر، صوت، ویدئو، تحلیل اسناد، جست‌وجوی معنایی، RAG، Tool Calling و Agent را به محصولات دیجیتال اضافه کرد.

برای استفاده حرفه‌ای از AI API فقط ارسال یک درخواست کافی نیست. باید این موارد را نیز مدیریت کنید:

انتخاب مدل
API Key
Token و هزینه
Context Window
Streaming
Timeout
Retry
Fallback
Rate Limit
امنیت
Structured Output
Observability
اعتبارسنجی پاسخ

درواره به‌عنوان زیرساخت استفاده از هوش مصنوعی در ایران، یک API سازگار با OpenAI ارائه می‌کند:

https://api.darvareh.ir/v1

با این API می‌توانید از SDKهای سازگار با OpenAI استفاده کنید و نرم‌افزار خود را از طریق یک اتصال واحد به مدل‌های مختلف هوش مصنوعی متصل کنید.

بهترین مسیر شروع این است:

API Key اختصاصی بسازید
مدل‌های فعال را از /v1/models دریافت کنید
اتصال را با cURL آزمایش کنید
درخواست را به Backend منتقل کنید
Timeout و Error Handling اضافه کنید
Token و هزینه را پایش کنید
سپس قابلیت‌هایی مانند Streaming، RAG و Agent را توسعه دهید

برای اضافه کردن هوش مصنوعی به سایت، اپلیکیشن یا نرم‌افزار خود، در درواره ثبت‌نام کنید و یک API Key اختصاصی بسازید.

فهرست مدل‌های فعال را از Endpoint زیر دریافت کنید:

https://api.darvareh.ir/v1/models

سپس نخستین درخواست خود را از طریق API سازگار با OpenAI درواره ارسال کنید:

https://api.darvareh.ir/v1/chat/completions

با یک اتصال می‌توانید زیرساخت نرم‌افزار خود را به اکوسیستم مدل‌های هوش مصنوعی متصل کنید.