فرض کنید می‌خواهید در یک افزونه‌ی وردپرس یا پروژه‌ی لاراول، چند مدل هوش مصنوعی را امتحان کنید: یکی از OpenAI، یکی از Anthropic، یک مدل متن‌باز. معمولاً یعنی سه حساب، سه کلید، سه صورت‌حساب و سه کتابخانه‌ی متفاوت. OpenRouter این را به یک حساب و یک کلید تبدیل می‌کند، و چند مدل رایگان هم دارد که برای یادگیری و نمونه‌سازی کافی است.

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

OpenRouter دقیقاً چه کار می‌کند#

OpenRouter یک درگاه است: درخواست شما را می‌گیرد، به ارائه‌دهنده‌ی مدلی که انتخاب کرده‌اید می‌فرستد و جواب را برمی‌گرداند. سه ویژگی آن را کاربردی می‌کند:

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

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

گام‌به‌گام: از ثبت‌نام تا اولین جواب#

  1. به سایت OpenRouter بروید و با ایمیل یا یکی از حساب‌های رایج ثبت‌نام کنید.
  2. پیش از کد، بخش گفتگوی خود سایت را امتحان کنید: یک مدل رایگان انتخاب کنید و چند سؤال بپرسید تا با رفتار مدل آشنا شوید.
  3. به صفحه‌ی مدل‌ها بروید و فهرست را بر اساس قیمت فیلتر کنید تا مدل‌های رایگان بیایند. شناسه‌ی مدل (مثل provider/model-name:free) را کپی کنید؛ پسوند :free نشان نسخه‌ی رایگان است.
  4. از بخش کلیدها یک کلید API بسازید. اسم روشنی بدهید (مثلاً اسم پروژه) و اگر گزینه‌ی سقف اعتبار هست، برای کلید سقف بگذارید.
  5. کلید را در فایل .env یا متغیر محیطی سرور نگه دارید، نه در کد.
  6. اولین درخواست را بفرستید (پایین‌تر).
  7. در داشبورد، گزارش مصرف را نگاه کنید تا ببینید هر درخواست به کدام مدل و ارائه‌دهنده رفته است.

اولین درخواست با curl#

آدرس API سازگار با OpenAI است. شناسه‌ی مدل را با مدلی که در گام ۳ برداشتید عوض کنید:

Bash
curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider/model-name:free",
    "messages": [
      {"role": "user", "content": "Explain what a REST API is in two sentences."}
    ]
  }'

جواب همان ساختار آشنای choices[0].message.content را دارد.

همان درخواست با PHP#

این تابع ساده با cURL خود PHP کار می‌کند و به هیچ کتابخانه‌ای نیاز ندارد:

PHP
<?php
function openrouter_chat(string $prompt, string $model): ?string
{
    $key = getenv('OPENROUTER_API_KEY');
    if (!$key) {
        return null;
    }

    $payload = json_encode([
        'model'    => $model,
        'messages' => [
            ['role' => 'user', 'content' => $prompt],
        ],
    ], JSON_UNESCAPED_UNICODE);

    $ch = curl_init('https://openrouter.ai/api/v1/chat/completions');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 60,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . $key,
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS     => $payload,
    ]);

    $body   = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($body === false || $status !== 200) {
        error_log('OpenRouter error: HTTP ' . $status . ' ' . (string) $body);
        return null;
    }

    $data = json_decode($body, true);
    return $data['choices'][0]['message']['content'] ?? null;
}

echo htmlspecialchars(
    openrouter_chat('یک جمله درباره‌ی وردپرس بنویس.', 'provider/model-name:free') ?? 'خطا',
    ENT_QUOTES,
    'UTF-8'
);

اگر از کتابخانه‌ی رسمی OpenAI یا ابزاری استفاده می‌کنید که «آدرس پایه‌ی سفارشی» می‌پذیرد، کافی است آدرس پایه را https://openrouter.ai/api/v1 بگذارید و کلید OpenRouter را بدهید. ابزارهای کدنویسی مثل Cline هم معمولاً OpenRouter را به‌عنوان ارائه‌دهنده می‌شناسند.

محدودیت‌های مدل‌های رایگان#

  • سقف درخواست: مدل‌های رایگان محدودیت در دقیقه و در روز دارند. معمولاً حسابی که مقداری اعتبار خریده، سقف روزانه‌ی بالاتری برای مدل‌های رایگان هم می‌گیرد؛ قاعده و عدد دقیق را از صفحه‌ی رسمی ببینید.
  • پایداری کمتر: نسخه‌ی رایگان ممکن است شلوغ باشد، کند جواب بدهد یا خطای محدودیت (کد 429) برگرداند. در کد، خطا را بگیرید و پیام مناسب نشان دهید.
  • فهرست متغیر: مدلی که امروز رایگان است ممکن است فردا نباشد. شناسه‌ی مدل را در تنظیمات نگه دارید، نه وسط کد.
  • حریم خصوصی: بعضی ارائه‌دهنده‌های رایگان ممکن است درخواست‌ها را نگه دارند. تنظیمات حریم خصوصی حساب را ببینید و داده‌ی حساس نفرستید.

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

چند ترفند کاربردی#

  • مقایسه‌ی سریع مدل‌ها: یک پرامپت ثابت روی چند مدل بفرستید و فقط شناسه را عوض کنید. برای متن فارسی، کیفیت مدل‌ها تفاوت زیادی دارد و این مقایسه ارزشش را دارد.
  • مدل ارزان برای کار ساده: دسته‌بندی، استخراج داده و خلاصه‌ی کوتاه را به مدل ارزان یا رایگان بدهید و فقط کار سخت را به مدل قوی. روش محاسبه را در محاسبه و کاهش هزینه‌ی API هوش مصنوعی آورده‌ایم.
  • یک کلید برای هر پروژه: اگر کلیدی لو رفت، فقط همان را باطل می‌کنید و مصرف هر پروژه هم جدا دیده می‌شود.
  • ابزار و خروجی ساختاریافته: بسیاری از مدل‌ها در OpenRouter فراخوانی ابزار را پشتیبانی می‌کنند؛ مفهومش را در فراخوانی ابزار در API هوش مصنوعی ببینید. پشتیبانی هر مدل را در صفحه‌ی خودش بررسی کنید.

امنیت کلید#

کلید OpenRouter به همه‌ی مدل‌های پولی دسترسی دارد، پس لو رفتنش گران تمام می‌شود. کلید را هرگز در جاوااسکریپت سمت کاربر، اپ موبایل یا مخزن عمومی نگذارید؛ درخواست را همیشه از سرور خودتان بفرستید. فهرست کامل را در چه چیزهایی را هرگز به هوش مصنوعی ندهیم ببینید.

دسترسی به برخی سرویس‌ها از داخل ایران محدود است و این وضعیت تغییر می‌کند؛ اگر برنامه روی هاست داخلی است، ممکن است به API دسترسی نداشته باشد.

جایگزین‌ها#

  • Ollama و LM Studio: اجرای مدل متن‌باز روی کامپیوتر خودتان، بدون ارسال داده؛ پیش‌زمینه را در مدل‌های متن‌باز هوش مصنوعی بخوانید.
  • Hugging Face: دسترسی به مدل‌های باز و اجرای آن‌ها از طریق ارائه‌دهنده‌های متصل.
  • API مستقیم ChatGPT یا Claude: اگر فقط مدل‌های یک شرکت را لازم دارید، واسطه‌ی کمتری دارد.

خلاصه#

  • OpenRouter یک حساب و یک کلید برای مدل‌های شرکت‌های مختلف می‌دهد.
  • مدل‌های رایگان را با فیلتر قیمت و پسوند :free پیدا کنید.
  • API سازگار با OpenAI است؛ فقط آدرس پایه، کلید و نام مدل عوض می‌شود.
  • مدل رایگان سقف درخواست و پایداری کمتری دارد؛ برای آزمایش مناسب است.
  • کلید را فقط سمت سرور نگه دارید و برای هر پروژه کلید جدا بسازید.