ডেভেলপার এপিআই

কুরআন AI অনুসন্ধান API

পবিত্র কুরআনের জন্য একটি বিনামূল্যে AI-চালিত অনুসন্ধান API। একটি থিম, গল্প বা প্রশ্ন সাধারণ ভাষায় বর্ণনা করুন এবং JSON হিসাবে সংক্ষিপ্ত AI ব্যাখ্যা সহ প্রাসঙ্গিক সূরা এবং আয়াত রেফারেন্স পান।

POST

/api/ai-search

JSON প্রতিক্রিয়া

বিনামূল্যে ব্যবহারযোগ্য

সংক্ষিপ্ত বিবরণ

AI অনুসন্ধান API সিমান্টিক AI ব্যবহার করে কুরআনের সূরা এবং আয়াতের সাথে প্রাকৃতিক-ভাষা প্রশ্নগুলিকে মেলায়। এটি এমন ইন্টিগ্রেটরদের জন্য ডিজাইন করা হয়েছে যারা তাদের নিজস্ব অনুসন্ধান সূচক বা LLM পাইপলাইন তৈরি না করেই থিম-ভিত্তিক আবিষ্কার চান।

একটি একক JSON প্রতিক্রিয়া ফেরত দেয় যা আপনি যেকোনো HTTP ক্লায়েন্ট দিয়ে পার্স করতে পারেন।
প্রতিটি ফলাফলের প্রাসঙ্গিকতার সংক্ষিপ্ত বিবরণ আপনি যে ভাষা দেন তাতে লেখে, অথবা আপনি যখন এটি বাদ দেন তখন ক্যোয়ারি ভাষা (detectedLanguage) স্বয়ংক্রিয়ভাবে সনাক্ত করে।
আপনার অ্যাপ লিঙ্ক করতে পারে এমন কাঠামোগত সূরা এবং আয়াত নম্বর ফেরত দেয়।

অনুগ্রহ করে লিঙ্ক করুন

এই API বিনামূল্যে ব্যবহার করা যাবে। আপনি যদি এটি দিয়ে কিছু তৈরি করেন, তাহলে আমরা কৃতজ্ঞ থাকব যদি আপনি OpenQuran.app-এর সাথে একটি লিঙ্ক যুক্ত করেন — উদাহরণস্বরূপ, যেখানে অনুসন্ধানের ফলাফল প্রদর্শিত হয়, অথবা আপনার ক্রেডিট বা অ্যাবাউট পৃষ্ঠায়।

আপনি যে লিঙ্কটি ব্যবহার করতে পারেন তার একটি উদাহরণ:

HTML

<a href="https://openquran.app" rel="noopener">OpenQuran.app দ্বারা কুরআন অনুসন্ধান</a>

আমরা কুরআনের খাতিরে এই কাজটি বিনামূল্যে ভাগ করে নিচ্ছি। একটি ছোট ব্যাকলিঙ্ক অন্যদের পাঠক আবিষ্কার করতে সাহায্য করে এবং আমাদের কাছে এর অনেক মূল্য।

এন্ডপয়েন্ট

ব্যবহারকারীর অনুসন্ধান বাক্য সহ একটি JSON বডি পাঠান। API মিলে যাওয়া রেফারেন্স সম্বলিত একটি একক JSON অবজেক্ট দিয়ে প্রতিক্রিয়া জানায়।

URL

POST https://openquran.app/api/ai-search

হেডার্স

হেডার	মান	নোটস
`Content-Type`	`application/json`	আবশ্যক

অনুরোধ

অনুরোধের বডি একটি একক JSON অবজেক্ট:

JSON বডি

{
  "query": "patience in hardship",
  "language": "en"
}

সীমাবদ্ধতা

ট্রিম করার পর কোয়েরি 2–300 অক্ষরের হতে হবে।
ভাষা ঐচ্ছিক: প্রাসঙ্গিকতার ব্যাখ্যার জন্য একটি ISO 639-1 কোড (যেমন en, ar, fr)। যখন বাদ দেওয়া হয় বা অবৈধ হয়, তখন ক্যোয়ারি থেকে ভাষা স্বয়ংক্রিয়ভাবে সনাক্ত করা হয়।
প্রতিটি কোয়েরির জন্য সর্বোচ্চ 12 ফলাফল।
অগ্রণী এবং অনুগামী হোয়াইটস্পেস বাদ দেওয়া হয়।

প্রতিক্রিয়া

সফল অনুরোধগুলি একটি JSON অবজেক্ট সহ HTTP 200 প্রদান করে।

কন্টেন্ট-টাইপ: application/json

উদাহরণ প্রতিক্রিয়া

{
  "ok": true,
  "results": [
    {
      "type": "surah",
      "surah": 2,
      "relevance": "Covers patience through trials."
    },
    {
      "type": "verse",
      "surah": 2,
      "ayah": 255,
      "relevance": "Ayat al-Kursi speaks of steadfastness in faith."
    }
  ],
  "detectedLanguage": "en"
}

ফলাফলের প্রতিটি আইটেমে একটি প্রাসঙ্গিকতা ক্ষেত্র অন্তর্ভুক্ত থাকে। সেই লেখাটি আপনার অনুরোধ করা ভাষায়, অথবা যখন কোনো ভাষা প্রদান করা হয়নি তখন সনাক্ত করা ক্যোয়ারি ভাষায় (detectedLanguage) লেখা হয় — উদাহরণস্বরূপ, একটি আরবি ক্যোয়ারি আরবি প্রাসঙ্গিকতার সংক্ষিপ্ত বিবরণ দেয়।

শীর্ষ-স্তরের ক্ষেত্রসমূহ

ক্ষেত্র	প্রকার	নোটস
`ok`	`true`	সফল হলে সর্বদা সত্য।
`results`	array	সূরা বা আয়াত রেফারেন্সের ক্রমিক তালিকা (ফলাফলের প্রকার দেখুন)।
`detectedLanguage`	string \| null	ক্যোয়ারি থেকে সনাক্ত করা ভাষার জন্য ISO 639-1 কোড। প্রাসঙ্গিকতার স্ট্রিংগুলি আপনার অনুরোধ থেকে দেওয়া ভাষা ব্যবহার করে, অন্যথায় এই সনাক্ত করা ভাষা ব্যবহার করে।

ফলাফলের প্রকার

প্রতিটি ফলাফল একটি ট্যাগ করা বস্তু — হয় একটি সম্পূর্ণ সূরা অথবা একটি একক আয়াত:

SemanticSearchResult

// Whole surah reference
{ "type": "surah", "surah": 2, "relevance": "One sentence explaining the match." }

// Single verse reference
{ "type": "verse", "surah": 2, "ayah": 255, "relevance": "One sentence explaining the match." }

surah — সূরা নম্বর, ১–১১৪।
ayah — সূরার মধ্যে ১-ভিত্তিক আয়াত নম্বর (শুধুমাত্র আয়াত ফলাফলের জন্য)।
relevance — কেন রেফারেন্স মিলেছে তার এক-বাক্যের ব্যাখ্যা, অনুরোধ করা ভাষা বা সনাক্ত করা ক্যোয়ারি ভাষায় লেখা। দ্রুত-রেফারেন্স অনুসন্ধানের জন্য Null।

দ্রুত রেফারেন্স

শুধুমাত্র সূরা নম্বর এবং আয়াত রেফারেন্সগুলি AI মডেলকে এড়িয়ে যায় এবং তাৎক্ষণিকভাবে সমাধান করে:

2 — সূরা ২-এ যান
2:255 — সূরা ২ এর ২৫৫ নং আয়াতে যান

দ্রুত-রেফারেন্স প্রশ্নগুলি প্রতিটি ফলাফলে প্রাসঙ্গিকতা null সেট করে তাৎক্ষণিকভাবে ফেরত আসে।

রেট সীমা

পরিষেবাটি বিনামূল্যে এবং উপলব্ধ রাখতে, প্রতিটি ক্লায়েন্ট আইপি প্রতি 60 সেকেন্ডে 10 অনুরোধে সীমাবদ্ধ।

স্ট্যান্ডার্ড প্রক্সি হেডার (`X-Forwarded-For`, `X-Real-IP`) ব্যবহার করে প্রতিটি আইপি ঠিকানার জন্য সীমা ট্র্যাক করা হয়।
যখন সীমা অতিক্রম করা হয়, API একটি `Retry-After` হেডার (পুনরায় চেষ্টা করার আগে সেকেন্ড) সহ HTTP 429 প্রদান করে।
স্বয়ংক্রিয় স্ক্র্যাপিং, বাল্ক কোয়েরি, বা সীমা অতিক্রম করার প্রচেষ্টা ব্লক করার কারণ হতে পারে।

429 Too Many Requests

{
  "ok": false,
  "error": "Too many requests. Please slow down."
}

ত্রুটি প্রতিক্রিয়া

ব্যর্থ অনুরোধগুলি একটি JSON বডি ফেরত দেয় যেখানে 'ok' মিথ্যা সেট করা থাকে এবং একটি সংক্ষিপ্ত ত্রুটি বার্তা থাকে।

অবস্থা	অর্থ
`400`	অবৈধ JSON, খালি ক্যোয়ারী, অথবা ন্যূনতম দৈর্ঘ্যের চেয়ে ছোট ক্যোয়ারী।
`429`	রেট সীমা অতিক্রম করা হয়েছে। 'Retry-After' হেডার (সেকেন্ড) পরীক্ষা করুন।
`502`	অনুসন্ধান পরিষেবা অপ্রত্যাশিতভাবে ব্যর্থ হয়েছে।
`503`	এই স্থাপনায় AI অনুসন্ধান কনফিগার করা হয়নি।

সমস্ত ত্রুটি প্রতিক্রিয়া এই কাঠামো ব্যবহার করে: 'ok': false, 'error': "message"।

কোড উদাহরণ

cURL

curl

curl -X POST 'https://openquran.app/api/ai-search' \
  -H 'Content-Type: application/json' \
  -d '{"query":"patience in hardship"}'

জাভাস্ক্রিপ্ট

JavaScript (fetch)

const response = await fetch('https://openquran.app/api/ai-search', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: 'patience in hardship' }),
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(error.error ?? response.statusText);
}

const data = await response.json();
console.log(data.results);

দাবিত্যাগ

ফলাফলগুলি একটি AI মডেল দ্বারা তৈরি করা হয় এবং অসম্পূর্ণ বা ত্রুটিপূর্ণ হতে পারে। এগুলি মানুষকে কুরআন অন্বেষণ করতে সাহায্য করার জন্য নির্দেশিকা — ধর্মীয় রায় বা প্রামাণিক ব্যাখ্যা নয়। সর্বদা আয়াতগুলি তাদের সম্পূর্ণ প্রেক্ষাপটে পড়ুন।

এই API ব্যবহার করে আপনি আমাদের পরিষেবার শর্তাবলী এবং গোপনীয়তা নীতিতে সম্মত হন।