The custom question answering prebuilt API provides you the capability to answer questions based on a passage of text without having to create projects, maintain question and answer pairs, or incurring costs for underutilized infrastructure. This functionality is provided as an API and can be used to meet question and answering needs without having to learn the details about custom question answering.
Given a user query and a block of text/passage the API will return an answer and precise answer (if available).
Example API usage
Imagine that you have one or more blocks of text from which you would like to get answers for a given question. Normally you would have had to create as many sources as the number of blocks of text. However, now with the prebuilt API you can query the blocks of text without having to define content sources in a project.
Some other scenarios where this API can be used are:
You are developing an ebook reader app for end users, which allows them to highlight text, enter a question and find answers over a highlighted passage of text.
A browser extension that allows users to ask a question over the content being currently displayed on the browser page.
A health bot that takes queries from users and provides answers based on the medical content that the bot identifies as most relevant to the user query.
Below is an example of a sample request:
Sample request
POST https://{Unique-to-your-endpoint}.api.cognitive.microsoft.com/language/:query-text
Sample query over a single block of text
Request Body
{
"parameters": {
"Endpoint": "{Endpoint}",
"Ocp-Apim-Subscription-Key": "{API key}",
"Content-Type": "application/json",
"api-version": "2021-10-01",
"stringIndexType": "TextElements_v8",
"textQueryOptions": {
"question": "how long it takes to charge surface?",
"records": [
{
"id": "1",
"text": "Power and charging. It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. It can take longer if you’re using your Surface for power-intensive activities like gaming or video streaming while you’re charging it."
},
{
"id": "2",
"text": "You can use the USB port on your Surface Pro 4 power supply to charge other devices, like a phone, while your Surface charges. The USB port on the power supply is only for charging, not for data transfer. If you want to use a USB device, plug it into the USB port on your Surface."
}
],
"language": "en"
}
}
}
Sample response
In the above request body, we query over a single block of text. A sample response received for the above query is shown below,
{
"responses": {
"200": {
"headers": {},
"body": {
"answers": [
{
"answer": "Power and charging. It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. It can take longer if you’re using your Surface for power-intensive activities like gaming or video streaming while you’re charging it.",
"confidenceScore": 0.93,
"id": "1",
"answerSpan": {
"text": "two to four hours",
"confidenceScore": 0,
"offset": 28,
"length": 45
},
"offset": 0,
"length": 224
},
{
"answer": "It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. It can take longer if you’re using your Surface for power-intensive activities like gaming or video streaming while you’re charging it.",
"confidenceScore": 0.92,
"id": "1",
"answerSpan": {
"text": "two to four hours",
"confidenceScore": 0,
"offset": 8,
"length": 25
},
"offset": 20,
"length": 224
},
{
"answer": "It can take longer if you’re using your Surface for power-intensive activities like gaming or video streaming while you’re charging it.",
"confidenceScore": 0.05,
"id": "1",
"answerSpan": null,
"offset": 110,
"length": 244
}
]
}
}
}
We see that multiple answers are received as part of the API response. Each answer has a specific confidence score that helps understand the overall relevance of the answer. Answer span represents whether a potential short answer was also detected. Users can make use of this confidence score to determine which answers to provide in response to the query.
Prebuilt API limits
API call limits
If you need to use larger documents than the limit allows, you can break the text into smaller chunks of text before sending them to the API. In this context, a document is a defined single string of text characters.
These numbers represent the per individual API call limits:
Number of documents: 5.
Maximum size of a single document: 5,120 characters.
Maximum three responses per document.
Language codes supported
The following language codes are supported by Prebuilt API. These language codes are in accordance to the ISO 639-1 codes standard.
Language code
Language
af
Afrikaans
am
Amharic
ar
Arabic
as
Assamese
az
Azerbaijani
ba
Bashkir
be
Belarusian
bg
Bulgarian
bn
Bengali
ca
Catalan, Valencian
ckb
Central Kurdish
cs
Czech
cy
Welsh
da
Danish
de
German
el
Greek, Modern (1453–)
en
English
eo
Esperanto
es
Spanish, Castilian
et
Estonian
eu
Basque
fa
Persian
fi
Finnish
fr
French
ga
Irish
gl
Galician
gu
Gujarati
he
Hebrew
hi
Hindi
hr
Croatian
hu
Hungarian
hy
Armenian
id
Indonesian
is
Icelandic
it
Italian
ja
Japanese
ka
Georgian
kk
Kazakh
km
Central Khmer
kn
Kannada
ko
Korean
ky
Kirghiz, Kyrgyz
la
Latin
lo
Lao
lt
Lithuanian
lv
Latvian
mk
Macedonian
ml
Malayalam
mn
Mongolian
mr
Marathi
ms
Malay
mt
Maltese
my
Burmese
ne
Nepali
nl
Dutch, Flemish
nn
Norwegian Nynorsk
no
Norwegian
or
Odia
pa
Punjabi, Panjabi
pl
Polish
ps
Pashto, Pushto
pt
Portuguese
ro
Romanian
ru
Russian
sa
Sanskrit
sd
Sindhi
si
Sinhala, Sinhalese
sk
Slovak
sl
Slovenian
sq
Albanian
sr
Serbian
sv
Swedish
sw
Swahili
ta
Tamil
te
Telugu
tg
Tajik
th
Thai
tl
Tagalog
tr
Turkish
tt
Tatar
ug
Uighur, Uyghur
uk
Ukrainian
ur
Urdu
uz
Uzbek
vi
Vietnamese
yi
Yiddish
zh
Chinese
Prebuilt API reference
Visit the full prebuilt API samples documentation to understand the input and output parameters required for calling the API.