پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

API جستجو

API جستجو در نقطه پایانی v1/search دسترسی برنامه‌نویسی به قابلیت‌های موتور جستجوی وب از ارائه‌دهندگان پیشرو را فراهم می‌کند. این یک API جستجوی اختصاصی است که نتایج جستجوی ساختاریافته را برای ادغام در برنامه‌های شما برمی‌گرداند.

مهم

این متفاوت از جستجوی وب در Chat Completions است که به مدل‌های زبانی امکان جستجوی وب را در طول مکالمات می‌دهد. اندپوینت v1/search یک API جستجوی وب مستقل است که نتایج جستجوی خام را برای استفاده برنامه‌نویسی برمی‌گرداند، در حالی که جستجوی وب در chat completions پاسخ‌های هوش مصنوعی را با داده‌های وب بلادرنگ تقویت می‌کند.

اندپوینت

POST https://api.avalai.ir/v1/search
POST https://api.avalai.ir/v1/search/{search_tool_name}

ابزارهای جستجوی پشتیبانی شده

AvalAI دسترسی به 10 ابزار جستجو از 8 ارائه‌دهنده پیشرو را فراهم می‌کند:

ابزار جستجو	ارائه‌دهنده	هزینه به ازای هر کوئری	بهترین برای
`serper-search`	Serper	$0.001	کم‌هزینه‌ترین جستجوی مبتنی بر Google
`dataforseo-search`	DataForSEO	$0.003	هزینه پایین
`parallel_ai-search`	Parallel AI	$0.004	پردازش موازی سریع
`perplexity-search`	Perplexity	$0.005	جستجوی مبتنی بر هوش مصنوعی با نتایج با کیفیت
`tavily-search`	Tavily	$0.008	جستجوی عمومی وب
`firecrawl-search`	Firecrawl	$0.008	جستجو با استخراج محتوا و وب‌اسکرپینگ
`parallel_ai-search-pro`	Parallel AI	$0.009	جستجوی موازی پیشرفته
`tavily-search-advanced`	Tavily	$0.016	جستجوی پیشرفته با فیلترینگ
`exa_ai-search`	Exa AI	$0.025	جستجوی عصبی معنایی

بدنه درخواست

پارامترهای استاندارد

پارامتر	نوع	الزامی	توضیحات
`query`	string or array	بله	کوئری جستجو. می‌تواند یک رشته یا آرایه‌ای از رشته‌ها باشد
`search_tool_name`	string	مشروط	الزامی هنگام استفاده از اندپوینت `v1/search` (نه در URL)
`max_results`	integer	خیر	حداکثر تعداد نتایج (1-20). پیش‌فرض: 10
`search_domain_filter`	array	خیر	لیست دامنه‌ها برای فیلتر نتایج (حداکثر 20 دامنه)
`max_tokens_per_page`	integer	خیر	حداکثر توکن‌ها در هر صفحه برای پردازش. پیش‌فرض: 1024
`country`	string	خیر	فیلتر کشور. فرمت بسته به ارائه‌دهنده متفاوت است (به زیر مراجعه کنید)

پارامترهای اختصاصی ارائه‌دهندگان

هر ارائه‌دهنده جستجو پارامترهای اضافی برای عملکرد پیشرفته پشتیبانی می‌کند:

Tavily (`tavily-search`، `tavily-search-advanced`)

پارامتر	نوع	توضیحات
`country`	string	نام کامل کشور به صورت حروف کوچک (مثلا `"united states"`، `"united kingdom"`). برای لیست کامل به مستندات Tavily مراجعه کنید.

Serper (`serper-search`)

پارامتر	نوع	توضیحات
`gl`	string	کد کشور/موقعیت جغرافیایی برای نتایج محلی‌سازی‌شده (مثلا `"uk"`، `"us"`، `"de"`)
`hl`	string	کد زبان نتایج (مثلا `"en"`، `"de"`، `"fa"`)
`autocorrect`	boolean	فعال یا غیرفعال کردن اصلاح خودکار کوئری. برای غیرفعال کردن مقدار `false` قرار دهید
`tbs`	string	فیلتر جستجوی زمانی: `"qdr:h"` (ساعت گذشته)، `"qdr:d"` (روز گذشته)، `"qdr:w"` (هفته گذشته)، `"qdr:m"` (ماه گذشته)، `"qdr:y"` (سال گذشته)
`page`	integer	شماره صفحه برای نتایج صفحه‌بندی‌شده
`location`	string	موقعیت جغرافیایی برای نتایج محلی (مثلا `"Berlin,Germany"`)
`country`	string	کد کشور برای نتایج هدفمند جغرافیایی (مثلا `"DE"`، `"US"`)

DataForSEO (`dataforseo-search`)

پارامتر	نوع	توضیحات
`country`	string	نام کامل کشور (مثلا `"United States"`، `"Germany"`)
`language_code`	string	کد زبان (مثلا `"en"`، `"de"`)
`depth`	integer	تعداد نتایج برای دریافت (حداکثر 700)
`device`	string	نوع دستگاه: `"desktop"`، `"mobile"`، `"tablet"`
`os`	string	سیستم عامل: `"windows"`، `"macos"`، `"android"`، `"ios"`

Firecrawl (`firecrawl-search`)

پارامتر	نوع	توضیحات
`sources`	array	منابع جستجو: `["web", "news", "images"]`
`categories`	array	فیلترهای دسته‌بندی: `[{"type": "github"}, {"type": "research"}, {"type": "pdf"}]`
`tbs`	string	جستجوی زمان‌بندی شده (مثلا `"qdr:m"` برای ماه گذشته)
`location`	string	موقعیت جغرافیایی (مثلا `"San Francisco,California,United States"`)
`ignoreInvalidURLs`	boolean	حذف URLهای نامعتبر از نتایج
`scrapeOptions`	object	پیکربندی اسکرپینگ (به مستندات Firecrawl مراجعه کنید)

Parallel AI (`parallel_ai-search`، `parallel_ai-search-pro`)

پارامتر	نوع	توضیحات
`processor`	string	نوع پردازشگر: `"base"` یا `"pro"`
`max_chars_per_result`	integer	حداکثر کاراکتر در هر خلاصه نتیجه

برای جزئیات کامل پارامترها، به صفحات مستندات هر ارائه‌دهنده مراجعه کنید.

فرمت پاسخ

تمام درخواست‌های جستجو یک فرمت پاسخ ثابت برمی‌گردانند:

json

{
  "object": "search",
  "results": [
    {
      "title": "عنوان نتیجه",
      "url": "https://example.com/page",

      "snippet": "خلاصه‌ای از محتوای صفحه...",
      "date": "2024-01-15"
    }
  ]
}

فیلدهای پاسخ

فیلد	نوع	توضیحات
`object`	string	همیشه "search" برای پاسخ‌های جستجو
`results`	array	لیست نتایج جستجو
`results[].title`	string	عنوان نتیجه جستجو
`results[].url`	string	URL نتیجه جستجو
`results[].snippet`	string	خلاصه متنی از نتیجه
`results[].date`	string	تاریخ انتشار یا آخرین به‌روزرسانی (اختیاری)

نمونه‌ها

گزینه 1: ابزار جستجو در URL

BashPythonJavaScript

bash

curl https://api.avalai.ir/v1/search/perplexity-search \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest AI developments 2024",
    "max_results": 5,
    "search_domain_filter": ["arxiv.org", "nature.com"],
    "country": "US"
  }'

python

import requests

response = requests.post(
    "https://api.avalai.ir/v1/search/perplexity-search",
    headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
    json={
        "query": "latest AI developments 2024",
        "max_results": 5,
        "search_domain_filter": ["arxiv.org", "nature.com"],
        "country": "US",
    },
)

results = response.json()
for result in results["results"]:
    print(f"{result['title']}: {result['url']}")

javascript

const response = await fetch("https://api.avalai.ir/v1/search/perplexity-search", {
    method: "POST",
    headers: {
        "Authorization": `Bearer ${process.env.AVALAI_API_KEY}`,
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        query: "latest AI developments 2024",
        max_results: 5,
        search_domain_filter: ["arxiv.org", "nature.com"],
        country: "US"
    })
});

const data = await response.json();
data.results.forEach(result => {
    console.log(`${result.title}: ${result.url}`);
});

گزینه 2: ابزار جستجو در بدنه

BashPythonJavaScript

bash

curl https://api.avalai.ir/v1/search \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search_tool_name": "tavily-search",
    "query": "machine learning tutorials",
    "max_results": 10
  }'

python

import requests

response = requests.post(
    "https://api.avalai.ir/v1/search",
    headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
    json={
        "search_tool_name": "tavily-search",
        "query": "machine learning tutorials",
        "max_results": 10,
    },
)

results = response.json()

javascript

const response = await fetch("https://api.avalai.ir/v1/search", {
    method: "POST",
    headers: {
        "Authorization": `Bearer ${process.env.AVALAI_API_KEY}`,
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        search_tool_name: "tavily-search",
        query: "machine learning tutorials",
        max_results: 10
    })
});

const data = await response.json();

جستجوی Serper با فیلتر زمانی و هدف‌گیری جغرافیایی

BashPythonJavaScript

bash

curl https://api.avalai.ir/v1/search/serper-search \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "restaurants",
    "max_results": 10,
    "gl": "uk",
    "hl": "en",
    "autocorrect": false,
    "tbs": "qdr:d",
    "page": 1,
    "country": "DE",
    "location": "Berlin,Germany"
  }'

python

import requests

response = requests.post(
    "https://api.avalai.ir/v1/search/serper-search",
    headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
    json={
        "query": "restaurants",
        "max_results": 10,
        # پارامترهای اختصاصی Serper
        "gl": "uk",  # کد کشور/موقعیت جغرافیایی
        "hl": "en",  # کد زبان
        "autocorrect": False,  # غیرفعال کردن اصلاح خودکار
        "tbs": "qdr:d",  # فیلتر زمانی: روز گذشته
        "page": 1,  # شماره صفحه
        # هدف‌گیری جغرافیایی
        "country": "DE",
        "location": "Berlin,Germany",
    },
)

results = response.json()

javascript

const response = await fetch("https://api.avalai.ir/v1/search/serper-search", {
    method: "POST",
    headers: {
        "Authorization": `Bearer ${process.env.AVALAI_API_KEY}`,
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        query: "restaurants",
        max_results: 10,
        // پارامترهای اختصاصی Serper
        gl: "uk",              // کد کشور/موقعیت جغرافیایی
        hl: "en",              // کد زبان
        autocorrect: false,     // غیرفعال کردن اصلاح خودکار
        tbs: "qdr:d",          // فیلتر زمانی: روز گذشته
        page: 1,                // شماره صفحه
        // هدف‌گیری جغرافیایی
        country: "DE",
        location: "Berlin,Germany"
    })
});

const data = await response.json();

کوئری‌های چندگانه

برخی ابزارهای جستجو از جستجو برای چندین کوئری به طور همزمان پشتیبانی می‌کنند:

BashPythonJavaScript

bash

curl https://api.avalai.ir/v1/search/parallel_ai-search-pro \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": ["AI developments", "machine learning trends", "neural networks"],
    "max_results": 5
  }'

python

import requests

response = requests.post(
    "https://api.avalai.ir/v1/search/parallel_ai-search-pro",
    headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
    json={
        "query": ["AI developments", "machine learning trends", "neural networks"],
        "max_results": 5,
    },
)

results = response.json()

javascript

const response = await fetch("https://api.avalai.ir/v1/search/parallel_ai-search-pro", {
    method: "POST",
    headers: {
        "Authorization": `Bearer ${process.env.AVALAI_API_KEY}`,
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        query: ["AI developments", "machine learning trends", "neural networks"],
        max_results: 5
    })
});

const data = await response.json();

جستجوی پیشرفته با فیلتر دامنه

BashPythonJavaScript

bash

curl https://api.avalai.ir/v1/search \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search_tool_name": "exa_ai-search",
    "query": "machine learning research papers",
    "max_results": 10,
    "search_domain_filter": ["arxiv.org", "paperswithcode.com", "scholar.google.com"],
    "country": "US"
  }'

python

import requests

response = requests.post(
    "https://api.avalai.ir/v1/search",
    headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
    json={
        "search_tool_name": "exa_ai-search",
        "query": "machine learning research papers",
        "max_results": 10,
        "search_domain_filter": [
            "arxiv.org",
            "paperswithcode.com",
            "scholar.google.com",
        ],
        "country": "US",
    },
)

results = response.json()

javascript

const response = await fetch("https://api.avalai.ir/v1/search", {
    method: "POST",
    headers: {
        "Authorization": `Bearer ${process.env.AVALAI_API_KEY}`,
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        search_tool_name: "exa_ai-search",
        query: "machine learning research papers",
        max_results: 10,
        search_domain_filter: ["arxiv.org", "paperswithcode.com", "scholar.google.com"],
        country: "US"
    })
});

const data = await response.json();

انتخاب ابزار جستجو

بر اساس هزینه

کمترین هزینه: serper-search ($0.001)
کم‌هزینه: dataforseo-search ($0.003)
مناسب بودجه: parallel_ai-search ($0.004)
متوسط: perplexity-search ($0.005)
ممتاز: exa_ai-search ($0.025)

بر اساس مورد استفاده

برنامه‌های پر حجم: serper-search - کم‌هزینه‌ترین جستجوی مبتنی بر Google با محلی‌سازی و فیلترهای زمانی
فیلترینگ حساس به هزینه: dataforseo-search - مقرون به صرفه با گزینه‌های فیلترینگ پیشرفته
جستجوی مبتنی بر هوش مصنوعی: perplexity-search - نتایج با کیفیت بهبود یافته توسط AI
جستجوی معنایی: exa_ai-search - جستجوی معنایی عصبی
جستجوی عمومی وب: tavily-search - قابل اعتماد با فیلتر کشور
جستجو با استخراج محتوا: firecrawl-search - جستجوی چند منبعی با استخراج محتوا
پردازش موازی سریع: parallel_ai-search، parallel_ai-search-pro - کوئری‌های چندگانه به طور همزمان
فیلترینگ پیشرفته: tavily-search-advanced - فیلترینگ بهبود یافته و کیفیت نتایج بالاتر

بهترین شیوه‌ها

ابزار مناسب را انتخاب کنید: یک ابزار جستجو را بر اساس نیازهای خاص خود انتخاب کنید (هزینه، کیفیت، ویژگی‌ها)
از فیلتر دامنه استفاده کنید: نتایج را به دامنه‌های خاص محدود کنید برای جستجوهای مرتبط‌تر
محدودیت‌های مناسب تنظیم کنید: از max_results برای کنترل تعداد نتایج برگشتی استفاده کنید
خطاها را مدیریت کنید: مدیریت خطای مناسب برای درخواست‌های API پیاده‌سازی کنید
محدودیت نرخ: به محدودیت‌های نرخ برای ارائه‌دهنده جستجوی انتخابی خود توجه کنید
نتایج را کش کنید: در نظر بگیرید نتایج جستجو را کش کنید تا هزینه‌ها کاهش یابد و عملکرد بهبود یابد

مدیریت خطا

API جستجو کدهای وضعیت HTTP استاندارد را برمی‌گرداند:

200: جستجوی موفق
400: درخواست نامعتبر (پارامترهای نامعتبر)
401: غیرمجاز (کلید API نامعتبر)
429: محدودیت نرخ از حد فراتر رفته است
500: خطای داخلی سرور

API جستجو ​

اندپوینت ​

ابزارهای جستجوی پشتیبانی شده ​

بدنه درخواست ​

پارامترهای استاندارد ​

پارامترهای اختصاصی ارائه‌دهندگان ​

Tavily (tavily-search، tavily-search-advanced) ​

Serper (serper-search) ​

DataForSEO (dataforseo-search) ​

Firecrawl (firecrawl-search) ​

Parallel AI (parallel_ai-search، parallel_ai-search-pro) ​

فرمت پاسخ ​

فیلدهای پاسخ ​

نمونه‌ها ​

گزینه 1: ابزار جستجو در URL ​

گزینه 2: ابزار جستجو در بدنه ​

جستجوی Serper با فیلتر زمانی و هدف‌گیری جغرافیایی ​

کوئری‌های چندگانه ​

جستجوی پیشرفته با فیلتر دامنه ​

انتخاب ابزار جستجو ​

بر اساس هزینه ​

بر اساس مورد استفاده ​

بهترین شیوه‌ها ​

مدیریت خطا ​

منابع مرتبط ​

API جستجو

اندپوینت

ابزارهای جستجوی پشتیبانی شده

بدنه درخواست

پارامترهای استاندارد

پارامترهای اختصاصی ارائه‌دهندگان

Tavily (`tavily-search`، `tavily-search-advanced`)

Serper (`serper-search`)

DataForSEO (`dataforseo-search`)

Firecrawl (`firecrawl-search`)

Parallel AI (`parallel_ai-search`، `parallel_ai-search-pro`)

فرمت پاسخ

فیلدهای پاسخ

نمونه‌ها

گزینه 1: ابزار جستجو در URL

گزینه 2: ابزار جستجو در بدنه

جستجوی Serper با فیلتر زمانی و هدف‌گیری جغرافیایی

کوئری‌های چندگانه

جستجوی پیشرفته با فیلتر دامنه

انتخاب ابزار جستجو

بر اساس هزینه

بر اساس مورد استفاده

بهترین شیوه‌ها

مدیریت خطا

منابع مرتبط