API de lenguaje natural

Envía un fragmento de texto y recibe datos estructurados sobre él: a qué categorías temáticas pertenece, cuán positivo o negativo es, qué personas, empresas, lugares y productos menciona y si toca temas sensibles. Úsalo para etiquetar contenido a escala, dirigir mensajes de soporte, vigilar menciones de marca o revisar páginas antes de publicarlas.

La API usa el formato de petición estándar documents:<method>: un cuerpo JSON con un document y una respuesta por llamada. Si tu código ya envía peticiones en este formato, funciona aquí con dos cambios: la URL base y la clave.

La API de lenguaje natural funciona con cualquier clave de API de OmevAI, sin activación aparte, y se cobra del saldo habitual de la clave. Para volúmenes o preguntas, contacta con support@omev.be.

Métodos

Método	Ruta	Qué recibes
Clasificar texto	`POST /v2/documents:classifyText`	hasta 5 categorías temáticas con su confianza, de la lista de categorías actual
Clasificar texto (ruta v1)	`POST /v1/documents:classifyText`	lo mismo, para código escrito para la ruta v1; envía la opción que se muestra más abajo
Sentimiento	`POST /v1/documents:analyzeSentiment`	el tono general del texto y de cada frase
Entidades	`POST /v1/documents:analyzeEntities`	personas, organizaciones, lugares, eventos, productos y otras entidades con sus menciones
Sentimiento por entidad	`POST /v1/documents:analyzeEntitySentiment`	las entidades y el tono hacia cada una de ellas
Moderación	`POST /v1/documents:moderateText`	una confianza para cada una de las 16 categorías sensibles
Varios a la vez	`POST /v1/documents:annotateText`	cualquier combinación de los anteriores en una sola llamada

El análisis sintáctico (analyzeSyntax) no está disponible.

Precio

Método	Precio	Se cuenta por	Precio por 1 millón de caracteres
`classifyText` (v1 y v2)	$0.001	1000 caracteres	$1.00
`analyzeSentiment`	$0.0005	1000 caracteres	$0.50
`analyzeEntities`	$0.0005	1000 caracteres	$0.50
`analyzeEntitySentiment`	$0.001	1000 caracteres	$1.00
`moderateText`	$0.00025	100 caracteres	$2.50
`annotateText`	la suma de las funciones que activas	como arriba

Los caracteres son caracteres Unicode de document.content, redondeados al alza a unidades completas: un texto de 2300 caracteres son tres unidades para la clasificación y 23 unidades para la moderación. En annotateText, extractEntitySentiment se cobra como sentimiento por entidad y sustituye el cobro de extractEntities. Una petición que termina con error no se cobra.

Clasificar un texto

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 contiene hasta 5 rutas de categoría, de la mejor a la peor. En la ruta v1, la respuesta contiene solo categories, y la petición debe pedir la lista de categorías actual: "classificationModelOptions": {"v2Model": {"contentCategoriesVersion": "V2"}}. La lista de categorías anterior (V1) no está disponible; una petición v1 sin esta opción no se atiende y no se cobra.

El documento

Todos los métodos aceptan el mismo objeto document.

Campo	Requerido	Valores
`document.type`	sí	`PLAIN_TEXT` o `HTML`
`document.content`	sí	el propio texto, no vacío, de hasta 1 000 000 bytes en UTF-8
`document.languageCode`	no	un código de idioma como `en`; se detecta automáticamente si se omite
`encodingType`	no	`NONE` (por defecto), `UTF8`, `UTF16`, `UTF32`: cómo se cuentan los valores de `beginOffset`; `moderateText` no lo acepta

Solo se acepta texto incluido en la petición; los enlaces a archivos almacenados se rechazan con 400. Los campos desconocidos se rechazan con 400.

Sentimiento, entidades, moderación y annotateText funcionan en 26 idiomas: 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 texto en otro idioma responde 400.

Sentimiento

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 (negativo) a 1 (positivo). magnitude (0 o más) indica cuánta emoción transmite el texto en total: un texto mixto puede tener una puntuación cercana a 0 y una magnitud alta.

Entidades y sentimiento por entidad

analyzeEntities y analyzeEntitySentiment aceptan el mismo cuerpo. Cada elemento de entities tiene:

Campo	Significado
`name`	la entidad tal como aparece escrita en el texto
`type`	`PERSON`, `ORGANIZATION`, `LOCATION`, `EVENT`, `WORK_OF_ART`, `CONSUMER_GOOD`, `OTHER`, además de `DATE`, `NUMBER`, `PRICE`, `PHONE_NUMBER`
`salience`	0–1, cuán central es la entidad en el texto; la lista se ordena por este valor
`mentions`	cada lugar en el que aparece: `text` (`content`, `beginOffset`) y `type` (`PROPER`, `COMMON` o `TYPE_UNKNOWN` para fechas, números, precios y números de teléfono)
`metadata`	datos estructurados adicionales cuando están disponibles
`sentiment`	`score` y `magnitude` hacia esta entidad (solo `analyzeEntitySentiment`)

Moderación

moderateText acepta solo document. La respuesta enumera cada categoría con una confidence de 0 a 1 de que el texto pertenece a ella (la trata, la muestra o la expresa, ya sea de forma positiva o negativa):

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

Categorías: Toxic, Insult, Profanity, Derogatory, Violent, Sexual, Death, Harm & Tragedy, Firearms & Weapons, Public Safety, Health, Religion & Belief, Illicit Drugs, War & Conflict, Finance, Politics, Legal. Elige tu propio umbral para cada categoría.

Varios análisis en una llamada

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

features acepta extractEntities, extractEntitySentiment, extractDocumentSentiment, classifyText, moderateText y classificationModelOptions. Al menos uno debe ser true; extractSyntax responde 400. Con classifyText activado, añade "classificationModelOptions": {"v2Model": {"contentCategoriesVersion": "V2"}} a features, igual que en la ruta v1 de clasificación. La respuesta contiene language y los campos de cada análisis activado: entities, documentSentiment, categories, moderationCategories.

Errores

Código	Cuándo
`400`	`document` ausente o vacío, un `type` incorrecto, texto de más de 1 000 000 bytes, un idioma no admitido, un campo o una función desconocidos
`401`	clave de API ausente o no válida
`403`	la clave no puede usar este producto
`404`	un método desconocido, incluido `analyzeSyntax`
`429`	demasiadas peticiones, o el saldo o el presupuesto de la clave no cubre la llamada; vuelve a intentarlo tras una breve pausa o recarga saldo
`500`	problema temporal; reintenta un número limitado de veces

Consulta Errores para ver el formato común y los consejos sobre reintentos.

Métodos​

Precio​

Clasificar un texto​

El documento​

Sentimiento​

Entidades y sentimiento por entidad​

Moderación​

Varios análisis en una llamada​

Errores​