۲۵ دلار اعتبار رایگان River AI: راه‌اندازی DeepSeek و Nemotron در ۹روتر و هرمس

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

چرا در ۲۰۲۶ همه دنبال API رایگان هوش مصنوعی هستند

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

این تغییر، معادلهٔ انتخاب مدل را عوض کرده است. تا چند سال پیش معیار «کدام مدل باهوش‌تر است» بود؛ حالا معیار «کدام مدل برای این کار به‌صرفه است» است. تیمی که برای برچسب زدن هزار ردیف داده از گران‌ترین مدل استفاده می‌کند، بودجهٔ کاری را می‌سوزاند که یک مدل کوچک‌تر با کیفیت کافی انجام می‌دهد.

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

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

River AI چیست و چه تفاوتی با OpenRouter دارد

یک درگاه (gateway) مدل است: یک آدرس، یک کلید، و مسیر استاندارد /chat/completions. آدرس پایهٔ آن https://api.river.ai/v1 است و با کتابخانه‌های رسمی OpenAI کار می‌کند؛ یعنی هر ابزاری که «سازگار با OpenAI» را پشتیبانی می‌کند، بدون تغییر کد به آن وصل می‌شود.

سه تفاوت عملی با درگاه‌های عمومی:

• دسترسی به مدل‌ها به‌ازای هر حساب است، نه برای همه. هر کلید فهرست کامل مدل‌ها را نمی‌بیند. اگر مدلی در حساب شما فعال نشده باشد، خطا می‌گیرید حتی اگر اسمش را دقیق نوشته باشید.
• کنسول قیمت‌گذاری شفاف دارد. قیمت هر مدل داخل کنسول و در بخش Billing → Pricing است، نه در یک صفحهٔ بازاریابی. هر مدل قیمت خودش را دارد.
• فقط inference نیست. پلتفرم امکان آموزش مدل را هم می‌دهد: تنظیم دقیق لایه‌های کوچک (LoRA)، آموزش نظارت‌شده (SFT) و یادگیری تقویتی (RL). اگر روزی خواستید مدلی را روی دادهٔ خودتان تنظیم کنید، لازم نیست به سرویس دیگری مهاجرت کنید.

مستندات در docs.river.ai و کنسول در river.ai است.

۲۵ دلار اعتبار رایگان چطور به دست می‌آید و چقدر دوام می‌آورد

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

پاسخ صادقانه به «چقدر دوام می‌آورد» این است: بستگی به مدل و طول درخواست دارد، و هیچ عدد ثابتی برای همه وجود ندارد. برای تخمین، دو چیز را کنار هم بگذارید:

1. میانگین توکن ورودی و خروجی هر درخواست در کار خودتان.
2. قیمت همان مدل در Billing → Pricing.

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

قبل از هر چیز، ماندهٔ اعتبار را در کنسول ببینید و یک هفته مصرف را ثبت کنید. تصمیم بعدی‌تان بر پایهٔ همین عدد است، نه بر پایهٔ حدس.

شش مدلی که با کلید رایگان می‌گیرید

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

دربارهٔ مدل تصویری یک نکتهٔ عملی: وجود VL در نام یعنی ورودی تصویر می‌پذیرد. اگر تصویر نمی‌فرستید، همان مدل متنی ارزان‌تر است.

مقایسهٔ مدل‌ها: کدام برای کدنویسی، کدام برای متن فارسی، کدام برای تصویر

مقایسهٔ مدل‌ها بر پایهٔ جدول امتیاز، به انتخاب بدی می‌رسد چون آن جدول‌ها برای کار شما ساخته نشده‌اند. سه پرسش بپرسید: چه ورودی می‌فرستم، چه خروجی می‌خواهم، و چند بار در روز تکرار می‌شود.

قاعدهٔ ساده: برای هر کار، ارزان‌ترین مدلی را انتخاب کنید که خروجی قابل قبول می‌دهد. مدل گران‌تر روی کاری که مدل سبک انجام می‌دهد، فقط اعتبار می‌سوزاند.

گرفتن کلید API و اولین درخواست با curl

در کنسول، بخش کلیدها، یک کلید بسازید و همان لحظه کپی کنید؛ بعداً کامل نمایش داده نمی‌شود. سه مقدار را کنار هم بگذارید:

• Base URL: https://api.river.ai/v1
• API Key: کلیدی که ساختی، با پیشوند sk-
• Model: یکی از شش شناسهٔ جدول بالا، دقیقاً همان‌طور نوشته‌شده

کلید را در متغیر محیطی بگذارید، نه داخل دستور:

export RIVER_API_KEY="sk-..."   # کلید خودتان را جایگزین کنید

curl -s "https://api.river.ai/v1/chat/completions" 
  -H "Authorization: Bearer $RIVER_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "model": "zai-org/GLM-5.3-Flash",
    "messages": [{"role": "user", "content": "یک پاراگراف کوتاه دربارهٔ کش لبه بنویس"}],
    "max_tokens": 200
  }'

دستور بالا همان چیزی است که در ابزارهای دیگر هم استفاده می‌شود؛ تفاوت فقط در محیط اجرا نیست، در آدرس و نام مدل است.

در همان روز، ۲۶ اکتبر ۲۰۲۶، دو درخواست نادرست به همین آدرس زدیم تا شکل خطا را ببینیم. این عین پاسخ سرور است:

# بدون هدر احراز هویت:
$ curl -i https://api.river.ai/v1/models
HTTP/1.1 401 Unauthorized
{"error":{"message":"Missing or invalid Authorization header. Expected: Bearer <api-key>",
"type":"invalid_request_error","code":null}}

# با کلید نامعتبر روی مسیر گفت‌وگو:
$ curl -i -X POST https://api.river.ai/v1/chat/completions 
    -H "Authorization: Bearer sk-not-a-real-key" ...
HTTP/1.1 401 Unauthorized
{"error":{"message":"Invalid API key","type":"invalid_request_error","code":null}}

دو چیز از این خروجی مهم است. اول، آدرس زنده است و ساختار خطایش استاندارد OpenAI را رعایت می‌کند، پس کتابخانه‌های موجود بدون تغییر کار می‌کنند. دوم، دو خطای مختلف داریم: «هدر نیست» و «کلید نامعتبر». تفکیک این دو، نیمی از عیب‌یابی است.

اگر با پایتون کار می‌کنید، همان درخواست با کتابخانهٔ رسمی OpenAI نوشته می‌شود و فقط دو مقدار عوض می‌شود:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.river.ai/v1",
    api_key="sk-...",  # از متغیر محیطی بخوانید، نه از متن کد
)

r = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4.1-Flash-1017",
    messages=[{"role": "user", "content": "این خطا را توضیح بده: 401"}],
    max_tokens=200,
)
print(r.choices[0].message.content)

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

افزودن River AI به 9Router به‌عنوان provider سازگار با OpenAI

روترها یک کار می‌کنند: یک آدرس محلی به شما می‌دهند و پشتش چند ارائه‌دهنده وصل می‌کنند. برای وصل کردن این سرویس، یک ارائه‌دهندهٔ سفارشی بسازید.

1. در بخش ارائه‌دهنده‌ها، گزینهٔ ارائه‌دهندهٔ سازگار با OpenAI را انتخاب کنید.
2. Provider را یک نام خوانا بگذارید؛ همان نام بعداً در فهرست مدل‌ها دیده می‌شود.
3. Base URL را https://api.river.ai/v1 بگذارید. اگر روتر خودش /chat/completions را اضافه می‌کند، همین آدرس کافی است؛ اگر خطای ۴۰۴ گرفتید، یکی از دو حالت را امتحان کنید.
4. API Key را وارد کنید و ذخیره کنید.
5. در بخش مدل‌ها، شناسه‌ها را دستی اضافه کنید. فهرست خودکار ممکن است کامل نباشد، چون دسترسی هر حساب فرق دارد.
6. یک درخواست آزمایشی بزنید و ببینید پاسخ می‌آید.

دو نکته که وقت زیادی می‌گیرد اگر ندانید. اول، اگر روتر را روی مدل پیش‌فرض خودش رها کنید و مدل River را انتخاب نکنید، درخواست شما به ارائه‌دهندهٔ دیگری می‌رود و رفتار عجیب می‌بینید. دوم، اگر Context Window را کمتر از واقعیت تنظیم کنید، روتر پرامپت را کوتاه می‌کند و پاسخ بی‌ربط می‌شود؛ این خطا شبیه خرابی مدل به نظر می‌رسد، ولی نیست.

استفاده از مدل‌های River در Hermes Agent

هر ابزاری که ارائه‌دهندهٔ سفارشی می‌پذیرد، یک بلوک تنظیمات می‌خواهد: آدرس، کلید، و شناسهٔ مدل. برای هرمس همان سه مقدار را در بخش ارائه‌دهنده تعریف کنید و مدل را به شکل نام‌ارائه‌دهنده/شناسهٔ-مدل صدا بزنید.

providers:
  river:
    base_url: "https://api.river.ai/v1"
    api_key: "${RIVER_API_KEY}"
    models:
      - "deepseek-ai/DeepSeek-V4.1-Flash-1017"
      - "zai-org/GLM-5.3-Flash"

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

نکتهٔ کاربردی: برای کارهای روزمره، مدل پیش‌فرض را Flash بگذارید و برای کارهای حساس، مدل را دستی عوض کنید. اگر همه‌چیز را روی گران‌ترین مدل بگذارید، اعتبار در چند روز تمام می‌شود و مجبور می‌شوید همه‌چیز را دوباره تنظیم کنید.

استفاده در Cline و OpenCode و Continue

هر سه ابزار یک الگو دارند: ارائه‌دهندهٔ سازگار با OpenAI را انتخاب کن، آدرس پایه بده، کلید بده، شناسهٔ مدل را بنویس.

Cline: در تنظیمات، Provider را روی گزینهٔ سازگار با OpenAI بگذارید، سپس Base URL را https://api.river.ai/v1 و API Key را وارد کنید. در فیلد Model شناسهٔ کامل را بنویسید؛ فهرست کشویی ممکن است خالی باشد و این طبیعی است.

OpenCode: در فایل تنظیمات، یک ارائه‌دهندهٔ سفارشی با نوع سازگار با OpenAI بسازید و baseURL را همان آدرس بگذارید. مدل را با شناسهٔ کامل صدا بزنید.

{
  "provider": {
    "river": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "https://api.river.ai/v1", "apiKey": "{env:RIVER_API_KEY}" },
      "models": { "deepseek-ai/DeepSeek-V4.1-Flash-1017": {} }
    }
  }
}

Continue: در فایل مدل‌ها، یک ورودی با provider: openai و apiBase برابر آدرس پایه بسازید و مدل را ذکر کنید.

در هر سه ابزار، اولین خطا معمولاً «مدل پیدا نشد» است. دلیلش تقریباً همیشه یکی است: شناسهٔ مدل با حروف بزرگ و کوچک اشتباه تایپ شده، یا آن مدل در حساب شما فعال نیست.

بعد از تنظیم، با یک درخواست کوتاه تست کنید، نه با یک وظیفهٔ سنگین. اگر پاسخ آمد، سراغ کار واقعی بروید. اگر نیامد، API Key را دوباره بررسی کنید و ببینید ابزار آن را از متغیر محیطی می‌خواند یا از فیلد ذخیره‌شده.

چطور اعتبار ۲۵ دلاری را نسوزانیم

اعتبار رایگان با یک عادت بد در یک روز تمام می‌شود: فرستادن کل پروژه در هر درخواست. پنج قاعدهٔ ساده جلوی این را می‌گیرد.

1. سقف خروجی بگذارید. پارامتر max_tokens را همیشه تنظیم کنید. بدون سقف، مدل تا جایی که می‌تواند می‌نویسد.
2. مدل را با کار تطبیق دهید. دسته‌بندی هزار ردیف با مدل بزرگ، گران‌ترین راه انجام ارزان‌ترین کار است.
3. زمینه را کوتاه کنید. فقط بخش مرتبط فایل را بفرستید، نه همهٔ آن. این تنها تغییری است که هم هزینه و هم کیفیت را بهتر می‌کند.
4. تست را روی نمونهٔ کوچک بزنید. یک اسکریپت را روی سه ردیف امتحان کنید، بعد روی سه هزار ردیف.
5. مصرف را روزانه ببینید. ماندهٔ اعتبار در کنسول است؛ هفته‌ای یک بار نگاه کردن، معمولاً دیر است.

یک قاعدهٔ اضافه: هر درخواست آزمایشی را با max_tokens کوچک بزنید. بیشترین اعتباری که تازه‌کارها می‌سوزانند، صرف پاسخ‌های بلندی می‌شود که فقط برای دیدن «کار می‌کند یا نه» فرستاده شده‌اند.

خطاهای رایج: 401، 404 مدل، 429 و timeout

۴۰۱ — احراز هویت. در تست ما دو شکل مختلف داشت. اگر هدر نبود، پیام «Missing or invalid Authorization header» آمد. اگر کلید بود ولی نامعتبر، پیام «Invalid API key» آمد. اولی یعنی هدر را نگذاشته‌اید یا ابزار آن را نمی‌فرستد؛ دومی یعنی کلید اشتباه یا حذف‌شده است. اگر از متغیر محیطی استفاده می‌کنید، مطمئن شوید ابزار آن را می‌خواند، نه اینکه در فایل دیگری تعریف شده باشد. اگر همین خطا را در سایت خودتان می‌بینید، خطای 401 دسترسی ممنوع و روش رفع آن مسیر بررسی سمت سرور را نشان می‌دهد.

۴۰۴ — مدل پیدا نشد. دو علت دارد: شناسه اشتباه تایپ شده، یا مدل در حساب شما فعال نیست. یادتان باشد دسترسی به مدل‌ها به‌ازای هر حساب است؛ کپی کردن شناسه از یک آموزش، تضمین دسترسی نیست. فهرست مدل‌های حساب خودتان را در کنسول ببینید.

۴۲۹ — درخواست زیاد. در بازهٔ کوتاه بیش از حد فرستاده‌اید. جواب درست، صبر کردن است نه تلاش دوبارهٔ فوری. بین تلاش‌ها فاصله بگذارید و تعداد درخواست‌های هم‌زمان را کم کنید. اگر اسکریپت موازی می‌فرستد، موازی‌سازی را کم کنید؛ معمولاً دو یا سه درخواست هم‌زمان کافی است.

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

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

وقتی اعتبار تمام شد: جایگزین‌های رایگان

اعتبار رایگان تاریخ انقضا دارد، پس نقشهٔ بعدی را از قبل داشته باشید. این گزینه‌ها همه سهمیهٔ رایگان دارند، اما شرایطشان یکی نیست.

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

یک نکتهٔ مهاجرت: تنظیمات را طوری بنویسید که آدرس و کلید از متغیر محیطی خوانده شوند، نه از کد. آن‌وقت عوض کردن ارائه‌دهنده یک خط تغییر است، نه بازنویسی پروژه. همین یک عادت، تفاوت بین یک روز کار و یک ساعت کار است.

سوالات متداول دربارهٔ API رایگان River AI

اگر بعد از این راهنما سراغ موضوع‌های دیگر رفتید، فهرست مقالات و آموزش‌های سئوپلاس نقطهٔ شروع خوبی است.