API de langage naturel

Envoyez un texte et obtenez des informations structurées à son sujet : à quelles catégories thématiques il appartient, à quel point il est positif ou négatif, quelles personnes, entreprises, lieux et produits il mentionne, et s'il aborde des sujets sensibles. Utilisez-la pour étiqueter du contenu à grande échelle, orienter les messages du support, surveiller les mentions de marque ou vérifier des pages avant publication.

L'API utilise le format de requête standard documents:<method> : un corps JSON avec un document, une réponse par appel. Si votre code envoie déjà des requêtes dans ce format, il fonctionne ici après deux modifications : l'URL de base et la clé.

L'API de langage naturel fonctionne sur toutes les clés API OmevAI, sans activation séparée, et est facturée sur le solde habituel de la clé. Pour des volumes ou des questions, contactez support@omev.be.

Méthodes

Méthode	Route	Ce que vous obtenez
Classer un texte	POST /v2/documents:classifyText	jusqu'à 5 catégories thématiques avec leur niveau de confiance, issues de la liste de catégories actuelle
Classer un texte (route v1)	POST /v1/documents:classifyText	la même chose, pour le code écrit pour la route v1 ; envoyez l'option indiquée ci-dessous
Sentiment	POST /v1/documents:analyzeSentiment	la tonalité globale du texte et de chaque phrase
Entités	POST /v1/documents:analyzeEntities	personnes, organisations, lieux, événements, produits et autres entités avec leurs mentions
Sentiment par entité	POST /v1/documents:analyzeEntitySentiment	les entités et la tonalité envers chacune d'elles
Modération	POST /v1/documents:moderateText	un niveau de confiance pour chacune des 16 catégories sensibles
Plusieurs à la fois	POST /v1/documents:annotateText	n'importe quelle combinaison des méthodes ci-dessus en un seul appel

L'analyse syntaxique (analyzeSyntax) n'est pas proposée.

Prix

Méthode	Prix	Compté par	Prix pour 1 M de caractères
classifyText (v1 et v2)	$0.001	1 000 caractères	$1.00
analyzeSentiment	$0.0005	1 000 caractères	$0.50
analyzeEntities	$0.0005	1 000 caractères	$0.50
analyzeEntitySentiment	$0.001	1 000 caractères	$1.00
moderateText	$0.00025	100 caractères	$2.50
annotateText	la somme des fonctions que vous activez	comme ci-dessus

Les caractères sont les caractères Unicode de document.content, arrondis à l'unité supérieure : un texte de 2 300 caractères correspond à trois unités pour la classification et à 23 unités pour la modération. Pour annotateText, extractEntitySentiment est facturé comme sentiment par entité et remplace la facturation de extractEntities. Une requête qui se termine par une erreur n'est pas facturée.

Classer un texte

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 contient jusqu'à 5 chemins de catégorie, du meilleur au moins bon. Sur la route v1, la réponse ne contient que categories, et la requête doit demander la liste de catégories actuelle : "classificationModelOptions": {"v2Model": {"contentCategoriesVersion": "V2"}}. La liste de catégories antérieure (V1) n'est pas proposée ; une requête v1 sans cette option n'est ni traitée ni facturée.

Le document

Chaque méthode accepte le même objet document.

Champ	Requis	Valeurs
document.type	oui	PLAIN_TEXT ou HTML
document.content	oui	le texte lui-même, non vide, jusqu'à 1 000 000 octets en UTF-8
document.languageCode	non	un code de langue tel que en ; détecté automatiquement s'il est omis
encodingType	non	NONE (par défaut), UTF8, UTF16, UTF32 : la façon dont les valeurs beginOffset sont comptées ; non accepté par moderateText

Seul le texte transmis directement dans la requête est accepté ; les liens vers des fichiers stockés sont rejetés avec 400. Les champs inconnus sont rejetés avec 400.

Le sentiment, les entités, la modération et annotateText fonctionnent dans 26 langues : 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. Un texte dans une autre langue renvoie 400.

Sentiment

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 va de -1 (négatif) à 1 (positif). magnitude (0 ou plus) indique la quantité d'émotion que porte le texte au total : un texte mitigé peut avoir un score proche de 0 et une forte intensité.

Entités et sentiment par entité

analyzeEntities et analyzeEntitySentiment acceptent le même corps. Chaque élément de entities comporte :

Champ	Signification
name	l'entité telle qu'elle est écrite dans le texte
type	PERSON, ORGANIZATION, LOCATION, EVENT, WORK_OF_ART, CONSUMER_GOOD, OTHER, ainsi que DATE, NUMBER, PRICE, PHONE_NUMBER
salience	0–1, à quel point l'entité est centrale dans le texte ; la liste est triée selon cette valeur
mentions	chaque endroit où elle apparaît : text (content, beginOffset) et type (PROPER, COMMON, ou TYPE_UNKNOWN pour les dates, nombres, prix et numéros de téléphone)
metadata	données structurées supplémentaires lorsqu'elles sont disponibles
sentiment	score et magnitude envers cette entité (analyzeEntitySentiment uniquement)

Modération

moderateText accepte uniquement document. La réponse liste chaque catégorie avec une confidence de 0 à 1 indiquant que le texte en relève (il en traite, la montre ou l'exprime, que ce soit de manière positive ou négative) :

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

Catégories : Toxic, Insult, Profanity, Derogatory, Violent, Sexual, Death, Harm & Tragedy, Firearms & Weapons, Public Safety, Health, Religion & Belief, Illicit Drugs, War & Conflict, Finance, Politics, Legal. Choisissez votre propre seuil pour chaque catégorie.

Plusieurs analyses en un seul appel

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

features accepte extractEntities, extractEntitySentiment, extractDocumentSentiment, classifyText, moderateText et classificationModelOptions. Au moins une option doit valoir true ; extractSyntax renvoie 400. Lorsque classifyText est activé, ajoutez "classificationModelOptions": {"v2Model": {"contentCategoriesVersion": "V2"}} à features, comme pour la route de classification v1. La réponse contient language ainsi que les champs de chaque analyse activée : entities, documentSentiment, categories, moderationCategories.

Erreurs

Code	Quand
400	document absent ou vide, un type incorrect, un texte de plus de 1 000 000 octets, une langue non prise en charge, un champ ou une fonction inconnus
401	clé API absente ou invalide
403	la clé ne peut pas utiliser ce produit
404	une méthode inconnue, y compris analyzeSyntax
429	trop de requêtes, ou le solde ou le budget de la clé ne couvre pas l'appel ; réessayez après une courte pause ou rechargez votre solde
500	problème temporaire ; réessayez un nombre limité de fois

Consultez Erreurs pour le format commun et les conseils de nouvelle tentative.