API природної мови

Надішліть фрагмент тексту й отримайте структуровані факти про нього: до яких тематичних категорій він належить, наскільки він позитивний чи негативний, яких людей, компанії, місця та продукти в ньому згадано і чи торкається він чутливих тем. Використовуйте це, щоб масово розмічати контент, маршрутизувати звернення до підтримки, відстежувати згадки бренду або перевіряти сторінки перед публікацією.

API використовує стандартний формат запитів documents:<method>: одне тіло JSON з document, одна відповідь на виклик. Якщо ваш код уже надсилає запити в цьому форматі, він працюватиме тут після двох змін: базової URL-адреси та ключа.

API природної мови працює на кожному ключі API OmevAI без окремого ввімкнення і списується зі звичайного балансу ключа. Щодо обсягів або запитань звертайтеся на support@omev.be.

Методи

Метод	Маршрут	Що ви отримуєте
Класифікація тексту	`POST /v2/documents:classifyText`	до 5 тематичних категорій із впевненістю, з актуального списку категорій
Класифікація тексту (маршрут v1)	`POST /v1/documents:classifyText`	те саме, для коду, написаного під маршрут v1; надсилайте параметр, наведений нижче
Тональність	`POST /v1/documents:analyzeSentiment`	загальна тональність тексту та кожного речення
Сутності	`POST /v1/documents:analyzeEntities`	люди, організації, місця, події, продукти та інші сутності з їхніми згадками
Тональність щодо сутностей	`POST /v1/documents:analyzeEntitySentiment`	сутності та ставлення до кожної з них
Модерація	`POST /v1/documents:moderateText`	впевненість для кожної з 16 чутливих категорій
Кілька аналізів одразу	`POST /v1/documents:annotateText`	будь-яке поєднання наведеного вище в одному виклику

Синтаксичний аналіз (analyzeSyntax) не надається.

Ціна

Метод	Ціна	За одиницю	Ціна за 1M символів
`classifyText` (v1 і v2)	$0.001	1 000 символів	$1.00
`analyzeSentiment`	$0.0005	1 000 символів	$0.50
`analyzeEntities`	$0.0005	1 000 символів	$0.50
`analyzeEntitySentiment`	$0.001	1 000 символів	$1.00
`moderateText`	$0.00025	100 символів	$2.50
`annotateText`	сума увімкнених функцій	як вище

Символи — це символи Unicode в document.content, округлені вгору до цілих одиниць: текст на 2 300 символів — це три одиниці для класифікації та 23 одиниці для модерації. Для annotateText функція extractEntitySentiment оплачується як тональність щодо сутностей і замінює оплату за extractEntities. Запит, що завершився помилкою, не оплачується.

Класифікація тексту

curl -sS "https://llmapi.omev.be/v2/documents:classifyText" \
  -H "Authorization: Bearer $OMEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document": {
      "type": "PLAIN_TEXT",
      "content": "Slow-cooked beef ragù: brown the meat, add tomatoes and red wine, then simmer for three hours and serve over fresh pappardelle."
    }
  }'

{
  "categories": [
    {"name": "/Food & Drink/Cooking & Recipes", "confidence": 0.93}
  ],
  "languageCode": "en",
  "languageSupported": true
}

categories містить до 5 шляхів категорій, починаючи з найкращої. На маршруті v1 відповідь містить лише categories, а запит має запитувати актуальний список категорій: "classificationModelOptions": {"v2Model": {"contentCategoriesVersion": "V2"}}. Попередній (V1) список категорій не надається; запит v1 без цього параметра не обслуговується й не оплачується.

Документ

Кожен метод приймає той самий об'єкт document.

Поле	Обов'язкове	Значення
`document.type`	так	`PLAIN_TEXT` або `HTML`
`document.content`	так	сам текст, не порожній, до 1 000 000 байтів у UTF-8
`document.languageCode`	ні	код мови, наприклад `en`; якщо не вказано, визначається автоматично
`encodingType`	ні	`NONE` (за замовчуванням), `UTF8`, `UTF16`, `UTF32`: як рахуються значення `beginOffset`; не приймається `moderateText`

Приймається лише текст, переданий безпосередньо в запиті; посилання на збережені файли відхиляються з 400. Невідомі поля відхиляються з 400.

Тональність, сутності, модерація та annotateText працюють 26 мовами: en, ru, uk, de, fr, es, it, pt, nl, pl, cs, sk, sl, hr, sr, sv, da, no, fi, hu, ro, bg, el, lt, lv, et. На текст іншою мовою повертається 400.

Тональність

curl -sS "https://llmapi.omev.be/v1/documents:analyzeSentiment" \
  -H "Authorization: Bearer $OMEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document": {"type": "PLAIN_TEXT", "content": "The parcel arrived two days late. Support fixed it in minutes, though."},
    "encodingType": "UTF8"
  }'

{
  "documentSentiment": {"magnitude": 1.4, "score": 0.1},
  "sentences": [
    {"text": {"content": "The parcel arrived two days late.", "beginOffset": 0},
     "sentiment": {"magnitude": 0.6, "score": -0.6}},
    {"text": {"content": "Support fixed it in minutes, though.", "beginOffset": 34},
     "sentiment": {"magnitude": 0.8, "score": 0.8}}
  ],
  "language": "en"
}

score змінюється від -1 (негативна) до 1 (позитивна). magnitude (від 0 і більше) показує, скільки емоцій загалом несе текст: змішаний текст може мати оцінку, близьку до 0, і високу інтенсивність.

Сутності та тональність щодо сутностей

analyzeEntities і analyzeEntitySentiment приймають те саме тіло. Кожен елемент entities містить:

Поле	Значення
`name`	сутність так, як її написано в тексті
`type`	`PERSON`, `ORGANIZATION`, `LOCATION`, `EVENT`, `WORK_OF_ART`, `CONSUMER_GOOD`, `OTHER`, а також `DATE`, `NUMBER`, `PRICE`, `PHONE_NUMBER`
`salience`	0–1, наскільки сутність центральна для тексту; список відсортовано за цим значенням
`mentions`	кожне місце, де вона трапляється: `text` (`content`, `beginOffset`) і `type` (`PROPER`, `COMMON` або `TYPE_UNKNOWN` для дат, чисел, цін і телефонних номерів)
`metadata`	додаткові структуровані дані, якщо вони є
`sentiment`	`score` і `magnitude` щодо цієї сутності (лише `analyzeEntitySentiment`)

Модерація

moderateText приймає лише document. Відповідь перелічує кожну категорію з confidence від 0 до 1, тобто впевненістю, що текст належить до неї (обговорює, показує чи виражає її, позитивно чи негативно):

{
  "moderationCategories": [
    {"name": "Toxic", "confidence": 0.04},
    {"name": "Health", "confidence": 0.81}
  ]
}

Категорії: Toxic, Insult, Profanity, Derogatory, Violent, Sexual, Death, Harm & Tragedy, Firearms & Weapons, Public Safety, Health, Religion & Belief, Illicit Drugs, War & Conflict, Finance, Politics, Legal. Обирайте власний поріг для кожної категорії.

Кілька аналізів в одному виклику

{
  "document": {"type": "PLAIN_TEXT", "content": "…"},
  "features": {
    "extractEntities": true,
    "extractDocumentSentiment": true,
    "classifyText": true,
    "moderateText": true
  }
}

features приймає extractEntities, extractEntitySentiment, extractDocumentSentiment, classifyText, moderateText і classificationModelOptions. Щонайменше одна функція має бути true; на extractSyntax повертається 400. Якщо ввімкнено classifyText, додайте до features "classificationModelOptions": {"v2Model": {"contentCategoriesVersion": "V2"}}, як і для маршруту класифікації v1. Відповідь містить language, а також поля кожного увімкненого аналізу: entities, documentSentiment, categories, moderationCategories.

Помилки

Код	Коли
`400`	`document` відсутній або порожній, неправильний `type`, текст понад 1 000 000 байтів, непідтримувана мова, невідоме поле чи функція
`401`	ключ API відсутній або недійсний
`403`	ключ не може використовувати цей продукт
`404`	невідомий метод, зокрема `analyzeSyntax`
`429`	забагато запитів або баланс чи бюджет ключа не покриває виклик; повторіть спробу після короткої паузи або поповніть баланс
`500`	тимчасова проблема; повторіть спробу обмежену кількість разів

Загальний формат і поради щодо повторних спроб див. у розділі Помилки.

Методи​

Ціна​

Класифікація тексту​

Документ​

Тональність​

Сутності та тональність щодо сутностей​

Модерація​

Кілька аналізів в одному виклику​

Помилки​