Skip to main content

Comprehend-it API

The Comprehend-it API provides a zero-shot text classification service using a natural language inference (NLI) model. It processes input text and classifies it into specified labels, returning a probability score for each label.


Endpoint​

POST https://api.platform.knowledgator.com/inference/comprehend/


Headers​

NameTypeRequiredDescription
KnowledgatorAPI-KeyStringYesYour API key
Content-TypeStringYesapplication/json
KnowledgatorAPI-Model-IDStringNoFine-tuned LoRA adapter ID. When provided, uses your custom-trained model instead of the default model. Obtain this ID from a completed training job.

Request Body​

{
"labels": ["label1", "label2", "label3"],
"text": "Your input text here.",
"threshold": 0.5
}

Parameters​

  • labels (required): List of categories for classification.
  • text (required): The text to classify.
  • threshold (optional): Minimum score threshold for label inclusion.

Response​

{
"outputs": {
"label1": 0.85,
"label2": 0.10,
"label3": 0.05
}
}

Each label is associated with a probability score indicating the model's confidence.

Response Fields​

  • outputs: Array of label-score pairs
    • label: The predicted label string
    • score: Float probability/confidence from the GLiClass pipeline
    • Only labels with score >= threshold are returned

Error Codes​

Status CodeDescription
200OK – Request successful.
400Bad Request – Invalid or incomplete input.
401Unauthorized – Invalid API key.
404Not Found – Invalid endpoint or payload.
413Payload Too Large – Exceeds 30 KB limit.
500Internal Server Error – Server-side issue.

Example Usage​

SDK Usage​

💡 Dedicated SDK Guides: See Python SDK | TypeScript SDK

TypeScript/JavaScript​

import { createClient } from '@knowledgator/typescript-sdk';

const kg = createClient('YOUR_API_KEY');

const result = await kg.comprehend.it({
text: "I love this product! It exceeded my expectations.",
tasks: {
sentiment: {
type: "classify",
labels: ["positive", "negative", "neutral"],
threshold: 0.5,
},
},
adapter_id: "your-lora-adapter-id", // Optional LoRA adapter
});

console.log(result.outputs.sentiment);

Python​

from knowledgator import Knowledgator

kg = Knowledgator(api_key="YOUR_API_KEY")

# Using the default model with Unified Inference tasks
result = kg.comprehend.it(
text="I love this product! It exceeded my expectations.",
tasks={
"sentiment": {
"type": "classify",
"labels": ["positive", "negative", "neutral"],
"threshold": 0.5,
}
},
)

print(result.outputs["sentiment"].scores)

# Using a fine-tuned LoRA adapter
result = kg.comprehend.it(
text="I love this product! It exceeded my expectations.",
tasks={
"sentiment": {
"type": "classify",
"labels": ["positive", "negative", "neutral"],
"threshold": 0.5,
}
},
adapter_id="your-fine-tuned-adapter-id",
)

print(result.outputs["sentiment"].scores)

Expected SDK Output​

{
"positive": 0.942,
"neutral": 0.045,
"negative": 0.013
}

Python (requests)​

import requests

url = "https://api.platform.knowledgator.com/inference/comprehend/"
headers = {
"Content-Type": "application/json",
"KnowledgatorAPI-Key": "YOUR_API_KEY",
"KnowledgatorAPI-Model-ID": "your-model-id" # Optional
}
payload = {
"labels": ["positive", "negative", "neutral"],
"text": "I love this product!",
"threshold": 0.5
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

# Using a fine-tuned adapter
headers_with_adapter = {
"Content-Type": "application/json",
"KnowledgatorAPI-Key": "YOUR_API_KEY",
"KnowledgatorAPI-Model-ID": "your-fine-tuned-adapter-id"
}

response = requests.post(url, json=payload, headers=headers_with_adapter)
print(response.json())

cURL​

# Using the default model
curl -X POST https://api.platform.knowledgator.com/comprehend/ \
-H "Content-Type: application/json" \
-H "KnowledgatorAPI-Key: YOUR_API_KEY" \
-d '{
"text": "I love this product! It exceeded my expectations.",
"labels": ["positive", "negative", "neutral"],
"threshold": 0.5
}'

# Using a fine-tuned adapter
curl -X POST https://api.platform.knowledgator.com/comprehend/ \
-H "Content-Type: application/json" \
-H "KnowledgatorAPI-Key: YOUR_API_KEY" \
-H "KnowledgatorAPI-Model-ID: your-fine-tuned-adapter-id" \
-d '{
"text": "I love this product! It exceeded my expectations.",
"labels": ["positive", "negative", "neutral"],
"threshold": 0.5
}'

Expected Response (cURL & requests)​

{
"outputs": {
"positive": 0.942,
"neutral": 0.045,
"negative": 0.013
}
}

Additional Information​

  • Input Size Limit: The maximum payload size is 30 KB.
  • Label Flexibility: You can specify any set of labels relevant to your classification task.
  • Use Cases: Sentiment analysis, topic classification, intent detection, etc.

For more details, refer to the Comprehend-it API Documentation.