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
| Name | Type | Required | Description |
|---|---|---|---|
KnowledgatorAPI-Key | String | Yes | Your API key |
Content-Type | String | Yes | application/json |
KnowledgatorAPI-Model-ID | String | No | Fine-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 pairslabel: The predicted label stringscore: Float probability/confidence from the GLiClass pipeline- Only labels with
score >= thresholdare returned
Error Codes
| Status Code | Description |
|---|---|
| 200 | OK – Request successful. |
| 400 | Bad Request – Invalid or incomplete input. |
| 401 | Unauthorized – Invalid API key. |
| 404 | Not Found – Invalid endpoint or payload. |
| 413 | Payload Too Large – Exceeds 30 KB limit. |
| 500 | Internal 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.