Przejdź do głównej zawartości

API języka naturalnego

Wyślij fragment tekstu, a otrzymasz o nim ustrukturyzowane informacje: do jakich kategorii tematycznych należy, jak bardzo jest pozytywny lub negatywny, jakie osoby, firmy, miejsca i produkty wymienia oraz czy porusza drażliwe tematy. Używaj go do tagowania treści na dużą skalę, kierowania wiadomości do działu wsparcia, śledzenia wzmianek o marce lub sprawdzania stron przed publikacją.

API używa standardowego formatu żądań documents:<method>: jedna treść JSON z document, jedna odpowiedź na wywołanie. Jeśli Twój kod już wysyła żądania w tym formacie, zadziała tutaj po dwóch zmianach: bazowego adresu URL i klucza.

API języka naturalnego działa na każdym kluczu API OmevAI, bez osobnego włączania, i jest rozliczane ze zwykłego salda klucza. W sprawie wolumenów lub pytań skontaktuj się z support@omev.be.

Metody​

MetodaŚcieżkaCo otrzymujesz
Klasyfikacja tekstuPOST /v2/documents:classifyTextdo 5 kategorii tematycznych z poziomem pewności, z aktualnej listy kategorii
Klasyfikacja tekstu (ścieżka v1)POST /v1/documents:classifyTextto samo, dla kodu napisanego pod ścieżkę v1; wyślij opcję pokazaną niżej
WydźwiękPOST /v1/documents:analyzeSentimentogólny wydźwięk tekstu i każdego zdania
EncjePOST /v1/documents:analyzeEntitiesosoby, organizacje, miejsca, wydarzenia, produkty i inne encje wraz z ich wzmiankami
Wydźwięk wobec encjiPOST /v1/documents:analyzeEntitySentimentencje oraz wydźwięk wobec każdej z nich
ModeracjaPOST /v1/documents:moderateTextpoziom pewności dla każdej z 16 drażliwych kategorii
Kilka narazPOST /v1/documents:annotateTextdowolne połączenie powyższych w jednym wywołaniu

Analiza składniowa (analyzeSyntax) nie jest dostępna.

Cena​

MetodaCenaLiczone zaCena za 1 mln znaków
classifyText (v1 i v2)$0.0011 000 znaków$1.00
analyzeSentiment$0.00051 000 znaków$0.50
analyzeEntities$0.00051 000 znaków$0.50
analyzeEntitySentiment$0.0011 000 znaków$1.00
moderateText$0.00025100 znaków$2.50
annotateTextsuma włączonych funkcjijak wyżej

Znaki to znaki Unicode w document.content, zaokrąglane w górę do pełnych jednostek: tekst o długości 2 300 znaków to trzy jednostki przy klasyfikacji i 23 jednostki przy moderacji. W annotateText funkcja extractEntitySentiment jest rozliczana jako wydźwięk wobec encji i zastępuje opłatę za extractEntities. Żądanie zakończone błędem nie jest płatne.

Klasyfikacja tekstu​

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 zawiera do 5 ścieżek kategorii, od najlepszej. Na ścieżce v1 odpowiedź zawiera tylko categories, a żądanie musi poprosić o aktualną listę kategorii: "classificationModelOptions": {"v2Model": {"contentCategoriesVersion": "V2"}}. Wcześniejsza (V1) lista kategorii nie jest oferowana; żądanie v1 bez tej opcji nie jest obsługiwane i nie jest rozliczane.

Dokument​

Każda metoda przyjmuje ten sam obiekt document.

PoleWymaganeWartości
document.typetakPLAIN_TEXT lub HTML
document.contenttaksam tekst, niepusty, do 1 000 000 bajtów w UTF-8
document.languageCodeniekod języka, np. en; wykrywany automatycznie, jeśli go pominiesz
encodingTypenieNONE (domyślnie), UTF8, UTF16, UTF32: jak liczone są wartości beginOffset; nieakceptowany przez moderateText

Akceptowany jest tylko tekst przekazany bezpośrednio w żądaniu; linki do zapisanych plików są odrzucane z kodem 400. Nieznane pola są odrzucane z kodem 400.

Wydźwięk, encje, moderacja i annotateText działają w 26 językach: 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. Tekst w innym języku zwraca 400.

Wydźwięk​

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 przyjmuje wartości od -1 (negatywny) do 1 (pozytywny). magnitude (od 0 w górę) określa, ile emocji tekst niesie łącznie: tekst mieszany może mieć wynik bliski 0 i wysoką intensywność.

Encje i wydźwięk wobec encji​

analyzeEntities i analyzeEntitySentiment przyjmują tę samą treść. Każdy element entities ma:

PoleZnaczenie
nameencja w takiej postaci, w jakiej zapisano ją w tekście
typePERSON, ORGANIZATION, LOCATION, EVENT, WORK_OF_ART, CONSUMER_GOOD, OTHER, a także DATE, NUMBER, PRICE, PHONE_NUMBER
salience0–1, jak centralna jest encja dla tekstu; lista jest według tego posortowana
mentionskażde miejsce, w którym występuje: text (content, beginOffset) i type (PROPER, COMMON lub TYPE_UNKNOWN dla dat, liczb, cen i numerów telefonów)
metadatadodatkowe dane strukturalne, jeśli są dostępne
sentimentscore i magnitude wobec tej encji (tylko analyzeEntitySentiment)

Moderacja​

moderateText przyjmuje tylko document. Odpowiedź wymienia każdą kategorię z confidence od 0 do 1, że tekst do niej należy (omawia, pokazuje lub wyraża ją, pozytywnie bądź negatywnie):

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

Kategorie: Toxic, Insult, Profanity, Derogatory, Violent, Sexual, Death, Harm & Tragedy, Firearms & Weapons, Public Safety, Health, Religion & Belief, Illicit Drugs, War & Conflict, Finance, Politics, Legal. Wybierz własny próg dla każdej kategorii.

Kilka analiz w jednym wywołaniu​

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

features przyjmuje extractEntities, extractEntitySentiment, extractDocumentSentiment, classifyText, moderateText i classificationModelOptions. Co najmniej jedna musi mieć wartość true; extractSyntax zwraca 400. Gdy classifyText jest włączone, dodaj do features "classificationModelOptions": {"v2Model": {"contentCategoriesVersion": "V2"}}, tak jak dla ścieżki klasyfikacji v1. Odpowiedź zawiera language oraz pola każdej włączonej analizy: entities, documentSentiment, categories, moderationCategories.

Błędy​

KodKiedy
400brak lub pusty document, nieprawidłowy type, tekst powyżej 1 000 000 bajtów, nieobsługiwany język, nieznane pole lub funkcja
401brak klucza API lub klucz nieprawidłowy
403klucz nie może używać tego produktu
404nieznana metoda, w tym analyzeSyntax
429zbyt wiele żądań albo saldo lub budżet klucza nie pokrywa wywołania; spróbuj ponownie po krótkiej przerwie lub doładuj saldo
500chwilowy problem; ponów próbę ograniczoną liczbę razy

Wspólny format i wskazówki dotyczące ponawiania prób znajdziesz w Błędy.