مقدمه

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

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

اگر تجربه کار با API نداشته باشید، احتمالاً با پرسش‌هایی مانند این روبه‌رو می‌شوید:

• API هوش مصنوعی را از کجا دریافت کنیم؟
• API Key چیست؟
• Model ID را چگونه پیدا کنیم؟
• API Key را کجا قرار دهیم؟
• چگونه اتصال را آزمایش کنیم؟
• آیا API Key را می‌توان در JavaScript سایت نوشت؟
• هزینه API چگونه محاسبه می‌شود؟
• چگونه از افشای کلید جلوگیری کنیم؟
• برای Development و Production باید کلید جدا بسازیم؟
• چگونه مدل‌های متنی، تصویر، صوت و ویدئو را انتخاب کنیم؟

در این راهنما، فرایند دریافت API هوش مصنوعی را مرحله‌به‌مرحله بررسی می‌کنیم و سپس اولین درخواست را با cURL، Python، JavaScript و PHP به API درواره ارسال می‌کنیم.

درواره یک زیرساخت هوش مصنوعی با API سازگار با OpenAI است. توسعه‌دهندگان می‌توانند از طریق یک Base URL، یک API Key و Model IDهای مختلف، نرم‌افزارهای خود را به مدل‌های هوش مصنوعی متصل کنند.

Base URL درواره:

https://api.darvareh.ir/v1

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

برای دریافت API هوش مصنوعی باید در یک پلتفرم ارائه‌دهنده API ثبت‌نام کنید، وارد بخش API Keys شوید، یک کلید جدید بسازید، حساب خود را شارژ کنید و Model ID موردنظر را انتخاب کنید. سپس API Key را در Header درخواست و Base URL پلتفرم را در SDK یا کد Backend قرار دهید.

در درواره، فرایند کلی به این شکل است:

1. ایجاد حساب کاربری
2. ورود به داشبورد
3. شارژ کیف پول
4. ورود به بخش کلیدهای API
5. ساخت API Key اختصاصی
6. مشاهده مدل‌های فعال
7. انتخاب Model ID
8. آزمایش درخواست با cURL یا Playground
9. انتقال کلید به Environment Variable
10. اتصال Backend سایت یا اپلیکیشن

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

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

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

فرایند کلی:

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

از طریق API می‌توانید قابلیت‌های زیر را بسازید:

• چت هوشمند
• تولید و خلاصه‌سازی متن
• ترجمه
• تحلیل اسناد
• تولید تصویر
• تحلیل تصویر
• تولید ویدئو
• تبدیل گفتار به متن
• تبدیل متن به گفتار
• تولید کد
• جست‌وجوی معنایی
• RAG
• Tool Calling
• AI Agent
• سیستم Multi-Agent

برای آشنایی عمیق‌تر با این مفهوم، مقاله «API هوش مصنوعی چیست؟» باید صفحه مرجع اصلی این موضوع در وبلاگ درواره باشد.

API Key چیست؟

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

هنگامی که برنامه شما درخواستی به API می‌فرستد، کلید را در Header قرار می‌دهد:

Authorization: Bearer YOUR_API_KEY

پلتفرم با بررسی این کلید مشخص می‌کند:

• درخواست متعلق به کدام حساب است
• کلید فعال یا غیرفعال است
• کاربر به چه مدل‌هایی دسترسی دارد
• محدودیت درخواست چقدر است
• بودجه باقی‌مانده چقدر است
• مصرف به کدام حساب تعلق دارد
• آیا IP یا دامنه مجاز است
• آیا کلید تعلیق یا ابطال شده است

API Key مانند نام کاربری ساده نیست؛ در بسیاری از سیستم‌ها دارنده کلید می‌تواند از اعتبار حساب استفاده کند. به همین دلیل باید مانند رمز عبور از آن محافظت کنید.

تفاوت API، API Key، Base URL و Model ID

این چهار مفهوم معمولاً با یکدیگر اشتباه گرفته می‌شوند.

در درواره:

Base URL:
https://api.darvareh.ir/v1

Endpoint تولید متن و چت:

POST /chat/completions

آدرس کامل:

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

Endpoint دریافت مدل‌ها:

GET /models

آدرس کامل:

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

API Key:

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

Model ID:

شناسه دقیق مدل انتخاب‌شده از فهرست مدل‌ها

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

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

برنامه‌نویسان

برای اضافه کردن قابلیت هوش مصنوعی به پروژه‌های:

• Python
• JavaScript
• Node.js
• PHP
• Laravel
• Java
• .NET
• Go
• Ruby
• اپلیکیشن موبایل

استارتاپ‌ها و شرکت‌های نرم‌افزاری

برای ساخت:

• محصول هوش مصنوعی
• دستیار سازمانی
• چت‌بات اختصاصی
• ابزار تولید محتوا
• جست‌وجوی هوشمند
• تحلیل اسناد
• Agent
• RAG
• قابلیت تولید تصویر و ویدئو

فروشگاه‌های اینترنتی

برای:

• تولید توضیحات محصول
• پاسخ‌گویی به مشتری
• پیشنهاد محصول
• دسته‌بندی محصولات
• تحلیل نظر کاربران
• جست‌وجوی معنایی
• تولید تصویر تبلیغاتی

شرکت‌های خدماتی

برای:

• دسته‌بندی پیام‌ها
• خلاصه‌سازی درخواست‌ها
• تولید پاسخ پیشنهادی
• تحلیل Lead
• آماده‌سازی Proposal
• پردازش اسناد
• خودکارسازی فرایندها

سازمان‌ها

برای:

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

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

برای دسترسی به مدل‌ها چند مسیر کلی وجود دارد.

دریافت مستقیم از ارائه‌دهنده مدل

در این روش برای هر شرکت یا Provider حساب جداگانه می‌سازید.

مزایا:

• دسترسی مستقیم
• قابلیت‌های اختصاصی Provider
• مستندات رسمی همان مدل
• امکان استفاده از Endpointهای خاص

محدودیت‌ها:

• حساب و API Key جدا برای هر Provider
• روش پرداخت متفاوت
• APIهای مختلف
• Billing پراکنده
• دشواری مدیریت مصرف
• نیاز به Integrationهای متعدد
• احتمال محدودیت دسترسی جغرافیایی
• پیچیدگی Fallback و مهاجرت

استفاده از API یکپارچه

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

مزایا:

• یک Base URL
• یک API Key
• فرمت استاندارد
• مدیریت مصرف در یک داشبورد
• انتخاب مدل‌های مختلف
• کاهش زمان Integration
• امکان تغییر مدل با تغییر Model ID
• Billing متمرکز
• کاهش وابستگی به یک Provider

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

استفاده از مدل محلی

در این روش مدل روی سیستم یا سرور خودتان اجرا می‌شود.

مزایا:

• کنترل بیشتر بر داده
• امکان استفاده آفلاین
• مدیریت زیرساخت توسط خود سازمان

محدودیت‌ها:

• نیاز به GPU و RAM
• هزینه نگهداری
• محدودیت کیفیت و سرعت
• پیچیدگی Deployment
• نیاز به Monitoring
• مدیریت Scaling
• به‌روزرسانی مدل

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

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

دریافت مستقیم APIهای خارجی ممکن است با مشکلات زیر همراه باشد:

• نیاز به پرداخت ارزی
• محدودیت جغرافیایی
• نیاز به چند حساب
• تغییر شرایط ارائه‌دهنده
• پراکندگی هزینه‌ها
• دشواری صدور صورتحساب داخلی
• نیاز به مدیریت چند API Key
• تفاوت فرمت Endpointها
• پیچیدگی اتصال مدل‌های مختلف
• تغییر مداوم Model IDها

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

• پایداری
• امنیت
• شفافیت قیمت
• کیفیت مستندات
• مدل‌های قابل دسترس
• Rate Limit
• گزارش مصرف
• پشتیبانی
• سازگاری SDK
• Error Handling

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

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

Base URL:

https://api.darvareh.ir/v1

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

قابلیت‌های اصلی این رویکرد:

• API سازگار با OpenAI
• استفاده از SDKهای رایج
• دسترسی به مدل‌های مختلف
• مدل‌های متن، تصویر، صوت و ویدئو
• پرداخت ریالی
• کیف پول
• مدیریت API Key
• گزارش مصرف
• محدودیت RPM و TPM
• بودجه روزانه و ماهانه
• Playground
• مستندات فارسی
• امکان استفاده در Frameworkهای مختلف

مرحله اول: ثبت‌نام در درواره

برای شروع وارد وب‌سایت درواره شوید و حساب کاربری بسازید.

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

نکات امنیتی حساب:

• رمز عبور قوی استفاده کنید
• در صورت ارائه، احراز هویت دومرحله‌ای را فعال کنید
• ایمیل و شماره همراه را تأیید کنید
• حساب مشترک میان چند توسعه‌دهنده نسازید
• برای تیم و سازمان از ساختار سازمانی مناسب استفاده کنید

مرحله دوم: شارژ کیف پول

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

در درواره، پرداخت به‌صورت ریالی انجام می‌شود.

پس از شارژ:

• موجودی کیف پول را بررسی کنید
• رسید پرداخت را نگه دارید
• محدودیت بودجه تعیین کنید
• هشدار موجودی را فعال کنید
• برای Production اعتبار کافی در نظر بگیرید

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

مرحله سوم: ساخت API Key

وارد بخش کلیدهای API شوید و گزینه ایجاد کلید جدید را انتخاب کنید.

برای کلید یک نام روشن تعیین کنید.

نمونه‌های مناسب:

local-development
staging-backend
production-api
customer-support-agent
content-service
ci-tests

نام نامناسب:

key1
new-key
test
default

نام کلید باید مشخص کند:

• برای کدام پروژه است
• در کدام محیط استفاده می‌شود
• متعلق به کدام سرویس است

مرحله چهارم: تعیین محدودیت API Key

اگر امکان تنظیم محدودیت وجود دارد، هنگام ساخت کلید از آن استفاده کنید.

محدودیت RPM

RPM یعنی Requests Per Minute یا تعداد درخواست در دقیقه.

برای Development می‌توانید مقدار پایین‌تری تعیین کنید تا یک Loop اشتباه هزینه زیادی ایجاد نکند.

محدودیت TPM

TPM یعنی Tokens Per Minute یا تعداد Token در دقیقه.

این محدودیت از مصرف شدید در مدت کوتاه جلوگیری می‌کند.

بودجه روزانه

حداکثر هزینه قابل مصرف توسط کلید در یک روز.

بودجه ماهانه

حداکثر مصرف کلید در یک ماه.

IP Allowlist

در صورت ثابت بودن IP سرور، می‌توان کلید را به IPهای مشخص محدود کرد.

محدودیت مدل

اگر پلتفرم چنین قابلیتی ارائه می‌کند، فقط مدل‌های موردنیاز پروژه را برای کلید مجاز کنید.

اصل امنیتی مهم:

هر API Key باید کمترین دسترسی و کمترین بودجه لازم برای وظیفه خود را داشته باشد.

مرحله پنجم: ذخیره امن API Key

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

برای توسعه محلی از فایل .env استفاده کنید:

DARVAREH_API_KEY=YOUR_DARVAREH_API_KEY
DARVAREH_BASE_URL=https://api.darvareh.ir/v1
DARVAREH_MODEL_ID=YOUR_MODEL_ID

فایل .gitignore:

.env
.env.local
.env.production

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

گزینه‌های رایج:

• Secret Manager سرویس Cloud
• Docker Secret
• Kubernetes Secret همراه با مدیریت مناسب
• Vault
• Environment امن سرور
• سیستم مدیریت Secret سازمان

مرحله ششم: مشاهده مدل‌های فعال

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

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

پاسخ کلی:

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

مقدار id را عیناً کپی کنید.

این موارد را حدس نزنید:

• حروف بزرگ و کوچک
• خط تیره
• نسخه مدل
• Prefix Provider
• پسوند تاریخ
• نام نمایشی

Model ID نامعتبر معمولاً باعث خطای model_not_found یا 404 می‌شود.

مرحله هفتم: انتخاب مدل مناسب

مدل را بر اساس کاربرد انتخاب کنید.

مدل متنی سریع

برای:

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

مدل استدلالی

برای:

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

مدل کدنویسی

برای:

• تولید کد
• Code Review
• رفع Bug
• تست
• Refactor
• Coding Agent

مدل تصویری

برای:

• تولید تصویر
• ویرایش تصویر
• تصویر محصول
• محتوای تبلیغاتی
• کاور مقاله

مدل Vision

برای:

• تحلیل تصویر
• Screenshot
• سند تصویری
• نمودار
• ورودی چندرسانه‌ای

مدل صوتی

برای:

• گفتار به متن
• متن به گفتار
• Voice Agent

مدل ویدئویی

برای:

• Text-to-Video
• Image-to-Video
• Reference-to-Video
• محتوای تبلیغاتی

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

مرحله هشتم: آزمایش API Key با cURL

ابتدا اتصال را با cURL بررسی کنید. این کار خطای SDK را از خطای API جدا می‌کند.

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": "فقط عبارت اتصال برقرار است را بنویس."
      }
    ],
    "temperature": 0
  }'

اگر پاسخ صحیح دریافت شد، این موارد درست هستند:

• API Key
• Base URL
• Model ID
• اتصال شبکه
• موجودی حساب
• دسترسی مدل

آزمایش با Postman

در Postman:

1. یک درخواست POST بسازید
2. URL را وارد کنید
3. Header احراز هویت را اضافه کنید
4. Content-Type را روی JSON قرار دهید
5. Body را به حالت Raw JSON ببرید
6. درخواست را ارسال کنید

URL:

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

Headerها:

Authorization: Bearer YOUR_DARVAREH_API_KEY
Content-Type: application/json

Body:

{
  "model": "YOUR_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "API هوش مصنوعی چیست؟"
    }
  ]
}

اتصال با 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"
    ),
    timeout=60,
)

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
)

اتصال Async با Python

برای FastAPI و سرویس‌های پرترافیک از Client غیرهم‌زمان استفاده کنید:

import os
import asyncio

from openai import AsyncOpenAI


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


async def main():
    response = await (
        client.chat.completions.create(
            model="YOUR_MODEL_ID",
            messages=[
                {
                    "role": "user",
                    "content": (
                        "API هوش مصنوعی "
                        "را توضیح بده."
                    ),
                }
            ],
        )
    )

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


asyncio.run(main())

اتصال با 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",
  timeout: 60000,
});

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
);

چرا API Key را در Frontend قرار ندهیم؟

این کد ناامن است:

const client = new OpenAI({
  apiKey: "SECRET_API_KEY",
  dangerouslyAllowBrowser: true,
});

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

• Source Code
• DevTools
• Network Tab
• فایل JavaScript
• Source Map
• Bundle
• Extension مرورگر

معماری صحیح:

Browser
→ Backend شما
→ API درواره
→ Backend
→ Browser

Frontend فقط به Backend خودتان درخواست می‌فرستد.

نمونه Endpoint امن با Express

import express from "express";
import OpenAI from "openai";

const app = express();

app.use(express.json());

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

app.post(
  "/api/ai/chat",
  async (req, res) => {
    const message =
      String(req.body.message || "")
        .trim();

    if (!message) {
      return res.status(400).json({
        error: "message_required",
      });
    }

    if (message.length > 4000) {
      return res.status(400).json({
        error: "message_too_long",
      });
    }

    try {
      const response =
        await client.chat.completions
          .create({
            model: "YOUR_MODEL_ID",
            messages: [
              {
                role: "user",
                content: message,
              },
            ],
          });

      return res.json({
        message:
          response.choices[0]
            .message.content,
      });
    } catch (error) {
      return res.status(503).json({
        error:
          "ai_service_unavailable",
      });
    }
  }
);

app.listen(3000);

در Production باید این موارد را اضافه کنید:

• Authentication
• Rate Limit
• Budget
• Input Validation
• Logging
• Timeout
• Retry
• Output Validation
• Moderation
• Abuse Prevention

اتصال با 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 request failed.'
    );
}

$data = json_decode(
    $response,
    true
);

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

اتصال با Laravel

API Key را در .env قرار دهید:

DARVAREH_API_KEY=YOUR_API_KEY
DARVAREH_BASE_URL=https://api.darvareh.ir/v1
DARVAREH_MODEL_ID=YOUR_MODEL_ID

فایل config/services.php:

'darvareh' => [
    'api_key' =>
        env('DARVAREH_API_KEY'),
    'base_url' =>
        env(
            'DARVAREH_BASE_URL',
            'https://api.darvareh.ir/v1'
        ),
    'model' =>
        env('DARVAREH_MODEL_ID'),
],

درخواست:

use Illuminate\Support\Facades\Http;

$response = Http::withToken(
    config('services.darvareh.api_key')
)
    ->timeout(60)
    ->post(
        config(
            'services.darvareh.base_url'
        ) . '/chat/completions',
        [
            'model' =>
                config(
                    'services.darvareh.model'
                ),
            'messages' => [
                [
                    'role' => 'system',
                    'content' =>
                        'شما یک دستیار فارسی دقیق هستید.',
                ],
                [
                    'role' => 'user',
                    'content' =>
                        'API هوش مصنوعی را توضیح بده.',
                ],
            ],
            'temperature' => 0.2,
        ]
    );

if ($response->failed()) {
    throw new RuntimeException(
        'AI API request failed.'
    );
}

$content = $response->json(
    'choices.0.message.content'
);

ساخت کلیدهای جدا برای محیط‌ها

ساختار پیشنهادی:

مزایا:

• ابطال مستقل
• تحلیل مصرف
• کنترل بودجه
• تشخیص نشت
• Rate Limit جدا
• عدم اختلال میان محیط‌ها

API Key برای هر مشتری

اگر محصول SaaS دارید، معمولاً نباید API Key اصلی خود را به مشتری بدهید.

معماری مناسب:

مشتری
→ API محصول شما
→ احراز هویت و محدودیت
→ API Key سرور شما
→ درواره

در Backend باید مصرف هر مشتری را ثبت کنید:

• User ID
• Organization ID
• Model
• Token
• هزینه
• زمان
• Endpoint
• Request ID

نگهداری کلید در GitHub Actions

کلید را در Repository ننویسید. آن را در Secrets پروژه قرار دهید.

استفاده در Workflow:

env:
  DARVAREH_API_KEY:
    ${{ secrets.DARVAREH_API_KEY }}

هرگز این کار را انجام ندهید:

env:
  DARVAREH_API_KEY: "REAL_SECRET_KEY"

Logهای CI را نیز بررسی کنید تا کلید چاپ نشود.

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

نشانه‌ها:

• افزایش غیرعادی مصرف
• درخواست از IP ناشناس
• استفاده از مدل غیرمنتظره
• رشد ناگهانی RPM
• تمام شدن بودجه
• درخواست در زمان غیرعادی
• User Agent ناشناخته

اقدامات فوری:

1. کلید را ابطال کنید
2. کلید جدید بسازید
3. Logها را بررسی کنید
4. محل افشا را پیدا کنید
5. History Git را بررسی کنید
6. بودجه و محدودیت‌ها را اصلاح کنید
7. Credentialهای مرتبط را Rotate کنید

فقط حذف کلید از فایل کافی نیست. اگر کلید در Git Commit شده باشد، باید آن را ابطال کنید.

Rotation چیست؟

Rotation یعنی جایگزین کردن دوره‌ای یا اضطراری کلید.

فرایند بدون اختلال:

1. کلید جدید بسازید
2. آن را در Secret Manager قرار دهید
3. سرویس‌ها را به کلید جدید منتقل کنید
4. اتصال را آزمایش کنید
5. کلید قدیمی را غیرفعال کنید
6. مصرف کلید قدیمی را بررسی کنید
7. کلید قدیمی را حذف کنید

تعیین بودجه API Key

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

برای Development:

• بودجه پایین
• RPM پایین
• مدل‌های محدود

برای Production:

• بودجه متناسب با Traffic
• Alert نزدیک سقف
• Fallback کنترل‌شده
• Monitoring

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

محاسبه تقریبی هزینه

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

هزینه ورودی =
Input Tokens
÷ ۱٬۰۰۰٬۰۰۰
× قیمت ورودی مدل

هزینه خروجی =
Output Tokens
÷ ۱٬۰۰۰٬۰۰۰
× قیمت خروجی مدل

هزینه کل:

Total Cost =
Input Cost
+ Output Cost
+ سایر هزینه‌های مدل

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

مشاهده Usage

پاسخ متنی ممکن است اطلاعات مصرف داشته باشد:

{
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 80,
    "total_tokens": 200
  }
}

در برنامه ثبت کنید:

usage = response.usage

print(
    usage.prompt_tokens,
    usage.completion_tokens,
    usage.total_tokens,
)

تمام مدل‌ها Usage را دقیقاً با یک ساختار یا جزئیات یکسان ارائه نمی‌کنند.

خطای 401 Unauthorized

علت‌های احتمالی:

• کلید اشتباه
• کلید ناقص
• فاصله اضافی
• کلید ابطال‌شده
• Header اشتباه
• استفاده از کلید پلتفرم دیگر

Header صحیح:

Authorization: Bearer YOUR_API_KEY

خطای 403 Forbidden

کلید شناخته شده، اما عملیات مجاز نیست:

• مدل مجاز نیست
• حساب محدود شده
• IP مجاز نیست
• Scope کافی نیست
• کلید تعلیق شده است

خطای 404

علت‌ها:

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

Base URL صحیح:

https://api.darvareh.ir/v1

Base URL را به این شکل وارد نکنید:

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

SDK مسیر Endpoint را خودش اضافه می‌کند.

خطای 429

به محدودیت نرخ یا سهمیه مربوط است.

راهکار:

• کاهش هم‌زمانی
• Exponential Backoff
• Queue
• بررسی بودجه
• محدود کردن Loop
• کاهش درخواست‌های تکراری
• Cache

خطای موجودی ناکافی

اگر کیف پول اعتبار کافی نداشته باشد:

• موجودی را بررسی کنید
• حساب را شارژ کنید
• هزینه درخواست را کاهش دهید
• مدل اقتصادی‌تر انتخاب کنید
• سقف خروجی را محدود کنید
• Loop Agent را متوقف کنید

Timeout

Timeout مناسب تعیین کنید:

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

برای تولید تصویر یا ویدئو ممکن است الگوی Async Job لازم باشد و Timeout درخواست متنی مناسب آن نباشد.

Retry حرفه‌ای

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

import random
import time


def retry_delay(
    attempt: int
) -> float:
    return min(
        2 ** attempt
        + random.uniform(0, 0.5),
        30,
    )

سقف Retry تعیین کنید. Retry نامحدود هزینه و بار را افزایش می‌دهد.

چک‌لیست آماده‌سازی Production

حساب و کلید

• کلید Production جداست
• کلید در Secret Manager است
• بودجه تعریف شده است
• RPM و TPM تنظیم شده‌اند
• Rotation Plan وجود دارد

Backend

• کلید در Frontend نیست
• Authentication فعال است
• Rate Limit وجود دارد
• ورودی اعتبارسنجی می‌شود
• Timeout تعریف شده است
• Retry محدود است
• Error Mapping انجام می‌شود

هزینه

• Token ثبت می‌شود
• مدل ثبت می‌شود
• هزینه هر کاربر ثبت می‌شود
• Alert بودجه وجود دارد
• مصرف غیرعادی شناسایی می‌شود

امنیت

• Tenant Isolation رعایت شده است
• Prompt و Logهای حساس Redact می‌شوند
• API Key چاپ نمی‌شود
• Tool Calling مجوز Backend دارد
• عملیات حساس تأیید انسانی دارد

پایداری

• Fallback تعریف شده است
• Health Check وجود دارد
• Queue برای Taskهای طولانی وجود دارد
• Request ID ثبت می‌شود
• Circuit Breaker بررسی شده است

اشتباهات رایج

نوشتن API Key در Frontend

کلید در مرورگر قابل استخراج است.

استفاده از یک کلید برای همه پروژه‌ها

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

Commit کردن .env

کلید وارد History Git می‌شود.

نداشتن بودجه

یک Bug یا Loop می‌تواند مصرف زیادی ایجاد کند.

Hard-code کردن Model ID

تغییر مدل را دشوار می‌کند.

نداشتن Timeout

Workerها ممکن است طولانی اشغال شوند.

Retry همه خطاها

خطاهای احراز هویت یا Validation با Retry حل نمی‌شوند.

ثبت Prompt حساس

Log می‌تواند منبع نشت اطلاعات شود.

اعتماد به خروجی مدل

خروجی باید اعتبارسنجی شود، به‌خصوص در Structured Output و Tool Calling.

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

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

در پلتفرم ارائه‌دهنده ثبت‌نام کنید، حساب را شارژ کنید، وارد بخش API Keys شوید، کلید جدید بسازید و Model ID فعال را انتخاب کنید.

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

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

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

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

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

پرداخت ریالی، پشتیبانی فارسی، دسترسی متمرکز و کاهش پیچیدگی اتصال به Providerهای مختلف.

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

https://api.darvareh.ir/v1

Model ID را از کجا دریافت کنیم؟

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

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

فقط در Backend. قرار دادن آن در JavaScript مرورگر ناامن است.

آیا می‌توان یک API Key را در چند پروژه استفاده کرد؟

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

اگر API Key افشا شد چه کنیم؟

فوراً کلید را ابطال کنید، کلید جدید بسازید، محل افشا و Log مصرف را بررسی و Secretها را Rotate کنید.

آیا حذف کلید از Git کافی است؟

خیر. کلید ممکن است در History باقی مانده باشد. باید کلید را ابطال کنید.

تفاوت API Key و Model ID چیست؟

API Key هویت و مجوز درخواست را مشخص می‌کند. Model ID مشخص می‌کند کدام مدل باید استفاده شود.

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

بودجه روزانه و ماهانه، RPM، TPM، سقف خروجی و Monitoring تعریف کنید.

آیا API درواره با OpenAI SDK سازگار است؟

بله. Base URL را روی آدرس درواره و API Key را روی کلید درواره تنظیم کنید.

آیا می‌توان از API درواره در Laravel استفاده کرد؟

بله. از Laravel HTTP Client یا SDK سازگار با OpenAI استفاده کنید.

آیا می‌توان Agent ساخت؟

بله. می‌توانید از Tool Calling و Frameworkهایی مانند OpenAI Agents SDK، LangChain و LangGraph استفاده کنید.

جمع‌بندی

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

در درواره، تنظیمات اصلی عبارت‌اند از:

Base URL:
https://api.darvareh.ir/v1

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

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

فرایند پیشنهادی:

1. ثبت‌نام در درواره
2. تکمیل و تأیید حساب
3. شارژ کیف پول
4. ساخت API Key اختصاصی
5. تعیین بودجه و محدودیت
6. دریافت Model ID از /models
7. آزمایش با cURL یا Postman
8. قرار دادن کلید در Environment
9. اتصال Backend
10. فعال کردن Monitoring و Alert

API Key را مانند رمز عبور نگهداری کنید. آن را در Frontend، Repository، اپلیکیشن موبایل یا Log قرار ندهید. برای Development، Staging و Production کلیدهای جدا بسازید و هر کلید را به کمترین بودجه و دسترسی لازم محدود کنید.

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

مقالات مرتبط پیشنهادی

• API هوش مصنوعی چیست؟ راهنمای کامل AI API
• OpenAI-compatible API چیست؟
• آموزش استفاده از API درواره با cURL
• آموزش اتصال API درواره به Postman
• آموزش API هوش مصنوعی با Python
• آموزش اتصال API درواره به PHP و Laravel
• Token در API هوش مصنوعی چیست؟
• Streaming در API هوش مصنوعی چیست؟
• چگونه هزینه API هوش مصنوعی را کاهش دهیم؟
• Fallback و Retry در API هوش مصنوعی

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

پس از ساخت کلید، مدل‌های قابل دسترس را از Endpoint زیر مشاهده کنید:

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

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

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

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