جست‌وجوی وب (Keenable)

جست‌وجو در اینترنت و خواندن صفحه‌ها، مستقیم از دل کد شما و با همان کلیدی که برای مدل‌ها به کار می‌برید. دو راه دارد: مثل یک مدل معمولی از راه /v1/chat/completions، یا از راه سرویس‌های جداگانه‌ای که JSON خالص برمی‌گردانند.

هزینه

۰٫۰۰۵ دلار برای هر درخواست — یعنی ۵ دلار برای هزار درخواست.

حساب‌کردن بر پایهٔ فراخوانی است: هر فراخوانی یک درخواست به شمار می‌آید، هر تعداد نتیجه هم که برگردد. پیداکردن ۵۰ منبع همان‌قدر هزینه دارد که پیداکردن یک منبع.

برای درخواست‌های ناموفق چیزی کسر نمی‌شود — نه برای خطای سمت جست‌وجو و نه برای پارامتر نادرست.

چه چیزی	چند درخواست حساب می‌شود
جست‌وجویی که ۱ نتیجه برگرداند	۱ درخواست
جست‌وجویی که ۵۰ نتیجه برگرداند	۱ درخواست
خواندن یک صفحه	۱ درخواست
هر خطایی از هر نوع	۰

راه یکم — به‌صورت مدل

در Cursor، Claude Code، OpenCode و هر کلاینت سازگار با OpenAI بدون هیچ تغییری کار می‌کند: کافی است مدل را انتخاب کنید.

مدل‌ها:

مدل	چه می‌کند
keenable/search	در اینترنت جست‌وجو می‌کند و فهرست منبع‌ها را با گزیده‌هایشان برمی‌گرداند
keenable/read	صفحه را می‌خواند و متن آن را به markdown برمی‌گرداند

جست‌وجو

curl https://nordrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $NORDROUTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "keenable/search",
    "messages": [{"role": "user", "content": "قیمت امروز بیت‌کوین"}]
  }'

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

خواندن صفحه

نخستین واژهٔ پیام، نشانی است. پس از آن می‌توانید بنویسید که در آن صفحه دقیقاً چه چیزی برایتان مهم است.

curl https://nordrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $NORDROUTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "keenable/read",
    "messages": [{"role": "user", "content": "https://fa.wikipedia.org/wiki/توکیو جمعیت"}]
  }'

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

دستور به چه کار می‌آید

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

Python

from openai import OpenAI

client = OpenAI(
    api_key="کلید-شما",
    base_url="https://nordrouter.com/v1",
)

found = client.chat.completions.create(
    model="keenable/search",
    messages=[{"role": "user", "content": "خبرهای هوش مصنوعی این هفته"}],
)
print(found.choices[0].message.content)

راه دوم — سرویس‌های جداگانه

اگر به‌جای متن روان به نتیجه‌ای با فیلد و تاریخ و صافی نیاز دارید، JSON را بگیرید.

POST /v1/search

curl https://nordrouter.com/v1/search \
  -H "Authorization: Bearer $NORDROUTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "خبرهای شبکه‌های عصبی",
    "max_results": 5,
    "published_after": "7d"
  }'

پارامترها:

پارامتر	نوع	پیش‌فرض	چه می‌کند
query	رشته	الزامی	چه چیزی جست‌وجو شود
site	رشته	—	تنها در همین دامنه بگرد، مثلاً zoomit.ir
max_results	عدد	۱۰	چند نتیجه، از ۱ تا ۵۰
snippet_max_chars	عدد	—	درازای گزیده، از ۱۸۰ تا ۱۰۰۰۰ نویسه
published_after	رشته	—	مطالبی که پس از این لحظه منتشر شده‌اند
published_before	رشته	—	آنچه پیش از آن منتشر شده
acquired_after	رشته	—	آنچه دیرتر به نمایه راه یافته
acquired_before	رشته	—	آنچه زودتر به نمایه راه یافته
query_time	رشته	—	جست‌وجو در نمایه، همان‌گونه که در آن لحظه بوده

تاریخ‌ها به سه شکل پذیرفته می‌شوند: 2026-08-01، مهر زمانی کامل ISO 8601، یا به شکل نسبی — 30min، 12h، 7d، 3mo، 1y.

انتشار و نمایه‌شدن یکی نیستند

published_* بر پایهٔ تاریخ خودِ مطلب صافی می‌کند و acquired_* بر پایهٔ تاریخی که صفحه به نمایه راه یافته است. این تفاوت مهم است: می‌شود صفحه‌ای را بازنویسی کرد بی‌آنکه تاریخ انتشارش دست بخورد. پس اگر می‌خواهید بدانید «در یک شبانه‌روز چه چیزی در وب پیدا شده»، acquired_after را بردارید.

پاسخ:

{
  "query": "خبرهای شبکه‌های عصبی",
  "count": 5,
  "results": [
    {
      "title": "عنوان مقاله",
      "url": "https://example.com/article",
      "description": "توضیح کوتاه",
      "snippet": "گزیده‌ای از متن صفحه…",
      "published_at": "2026-08-25T10:30:00Z",
      "acquired_at": "2026-08-25T11:02:00Z"
    }
  ]
}

GET /v1/fetch

curl -G https://nordrouter.com/v1/fetch \
  -H "Authorization: Bearer $NORDROUTER_KEY" \
  --data-urlencode "url=https://example.com/article" \
  --data-urlencode "prompt=جدول قیمت‌ها را بیرون بکش"

پارامترها:

پارامتر	نوع	پیش‌فرض	چه می‌کند
url	رشته	الزامی	نشانی صفحه
max_chars	عدد	۵۰۰۰۰	چند نویسه برگردانده شود
prompt	رشته	—	دقیقاً چه چیزی بیرون کشیده شود، تا ۲۰۰۰ نویسه
live	true / false	false	به‌جای نمایه، یک‌راست از خود سایت بگیر

پاسخ:

{
  "url": "https://example.com/article",
  "title": "عنوان",
  "description": "توضیح",
  "author": "نویسنده",
  "content": "# متن صفحه به markdown…",
  "published_at": 1787777084
}

live کِی لازم می‌شود

صفحه از نمایه سریع‌تر می‌رسد، اما همه چیز در نمایه نیست. اگر صفحه تازه است یا در برابر خزنده‌ها بسته شده، live=true بگذارید تا یک‌راست از سایت خوانده شود. بها همان است.

محدودیت‌ها

سرعت	۲ درخواست در ثانیه برای هر کلید
درازای گزیده	از ۱۸۰ تا ۱۰۰۰۰ نویسه
نتیجه در هر فراخوانی	تا ۵۰
درازای دستورِ خواندن	تا ۲۰۰۰ نویسه

اگر از سرعت فراتر بروید، 429 همراه با سرایند Retry-After برمی‌گردد — یک ثانیه بعد دوباره بفرستید.

خطاها

کد	معنی	چه باید کرد
400	query یا url نیست، یا نشانی http:// ندارد	درخواست را درست کنید
401	کلید پذیرفته نشد	Authorization را بررسی کنید
402	موجودی تمام شد	از پنل کاربری شارژ کنید
429	بیش از اندازه پی‌درپی	یک ثانیه بعد دوباره بفرستید
502	جست‌وجو پاسخ نداد	دوباره بفرستید؛ چیزی کسر نشد
503	جست‌وجو موقتاً در دسترس نیست	در حال رسیدگی‌ایم؛ چیزی کسر نشد

پرسش‌های پرتکرار

آیا برای نتیجهٔ خالی هم پول کسر می‌شود؟ بله، اگر جست‌وجو انجام شده و صادقانه پاسخ داده «چیزی پیدا نشد» — کار انجام شده است. تنها خطاها رایگان‌اند.

آیا می‌شود جریانی (streaming) گرفت؟ نه، و لازم هم نیست: نتیجه‌ها یک‌جا و در کسری از ثانیه می‌رسند.

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

تفاوتش با مدل‌های search/… چیست؟ آن‌ها نخست جست‌وجو می‌کنند و سپس یافته‌ها را با یک مدل زبانی به پاسخ تبدیل می‌کنند — یعنی بهای دو کار را می‌پردازید. اینجا نتیجهٔ خام را می‌گیرید و خودتان تصمیم می‌گیرید با آن چه کنید.