Text Summarizer
Overview
The Text Summarizer endpoint is a knowledge agent that generates intelligent summaries from documents using advanced AI-powered abstractive and extractive summarization techniques. Choose between AI-generated abstractive summaries or sentence-based extractive summaries, with customizable compression ratios and focus areas.
Use this endpoint to:
- Generate concise summaries of lengthy documents automatically
- Choose between AI-generated (abstractive) or sentence-based (extractive) summaries
- Control summary length with compression ratios (20%-80%)
- Focus summaries on specific topics or areas of interest
- Create executive summaries, document briefs, and quick overviews
Endpoint Details
Method:
POST
Endpoint:/api/agent/text_summarizer
Base URL:https://api.k-v.ai
Authentication: Access Key (Required)
Request Specification
Headers
| Header | Type | Required | Description |
|---|---|---|---|
access-key | string | Yes | Your unique access-key generated from the platform UI |
Content-Type | string | Yes | Must be application/json |
Request Body
{
"doc_process_ids": [
"264dfa262b748d15ccbeaada89430c68"
],
"focus_areas": [],
"compression_ratio": 30,
"type": "abstractive",
"model_data": {
"model_name": "gpt-5.1",
"api_key": ""
}
}Body Fields
| Field | Type | Required | Description |
|---|---|---|---|
doc_process_ids | array | Yes | Array of document IDs to summarize (obtained from Upload or List Documents APIs) |
focus_areas | array | No | List of specific topics or areas to focus the summary on. Leave empty for general summary |
compression_ratio | integer | Yes | Compression percentage (20-80). Only applicable for abstractive type |
type | string | Yes | Summarization type: abstractive (AI-generated) or extractive (sentence-based) |
model_data | object | Yes | AI model configuration (only used for abstractive type) |
model_data.model_name | string | Yes | AI model to use for summarization (see supported models below) |
Summarization Types
| Type | Description | AI Required | Compression Control |
|---|---|---|---|
abstractive | AI-generated summary with paraphrasing and rewriting | Yes | Yes (20-80%) |
extractive | Sentence-based extraction directly from document | No | No |
Note: For extractive type, the compression ratio parameter is ignored.
Supported AI Models
| Model Name | Provider |
|---|---|
gpt-5.1 | OpenAI |
gpt-5-mini | OpenAI |
claude-sonnet-4-5-20250929 | Anthropic |
gemini/gemini-2.5-flash-lite | |
gemini/gemini-2.5-pro | |
gemini/gemini-3-pro-preview | |
mistral/mistral-small-latest | Mistral AI |
mistral/mistral-medium-latest | Mistral AI |
llama3.1-70b | Meta |
Using Your Own LLM API Keys
Platform Keys (Default):
{
"model_data": {
"model_name": "gpt-5.1",
"api_key": ""
}
}Your Own Keys:
{
"model_data": {
"model_name": "gpt-5.1",
"api_key": "sk-your-openai-api-key-here"
}
}Response Specification
Success Response (200 OK) - Abstractive
{
"data": {
"summary": [
"Settlement Agreement and Release between ABC Software Corporation (Plaintiff) and Widget Corporation (Defendant) resolving a dispute over a faxed advertisement sent on January 12, 2009. After Plaintiff's February 1, 2009 demand letter, the parties agree to settle all claims related to the fax. \n\nPlaintiff fully releases and forever discharges Defendant from all past, present, and future claims arising from or related to the faxed advertisement. In exchange, Defendant will pay Plaintiff $1,000 and will cease sending fax advertisements to Plaintiff. Defendant agrees to liquidated damages of $10,000 for each fax advertisement sent to Propel Software Corporation after execution of the Agreement. \n\nEach party bears its own attorneys' fees and costs incurred before execution. In any later action relating to the Agreement, the prevailing party is entitled to reasonable attorneys' fees and costs. Plaintiff warrants it has not assigned or transferred any claims. The Agreement is the entire agreement on these matters and binds and benefits the parties' executors, administrators, representatives, heirs, successors, and assigns. \n\nPlaintiff confirms it has relied on its own chosen attorneys, that the Agreement has been read and explained, and that its terms are understood and accepted. The Agreement is governed by California law. The parties agree to execute any further documents needed to carry out its terms. The Agreement becomes effective upon execution, signed by Plaintiff's CEO and Defendant, with Plaintiff's counsel confirming it was explained and executed per their advice."
],
"tokens": {
"input": 984,
"output": 310,
"total": 1294
}
},
"message": "Summary extracted successfully"
}Success Response (200 OK) - Extractive
{
"data": {
"summary": [
"Release and Discharge\nIn consideration of Defendant's agreement to make the payments called for herein, the Plaintiff completely releases and forever discharge the Defendant, of and from any and all past, present or future claims, demands, obligations, actions, causes of action, rights, damages, costs, loss of services, expenses and compensation which the Plaintiff now has, or which may hereafter accrue or otherwise be acquired by plaintiff, on account of, or in any way growing out of the faxed advertisement",
" Entire Agreement and Successors in Interest\nThis Settlement Agreement contains the entire agreement between the Plaintiff and the Defendant with regard to the matters set forth herein and shall be binding upon and inure to the benefit of the executors, administrators, personal representatives, heirs, successors and assigns of each",
" SETTLEMENT AGREEMENT AND RELEASE\nTHIS SETTLEMENT AGREEMENT AND RELEASE (\"Settlement Agreement'') is entered into between ABC Software Corporation (hereinafter \"Plaintiff''), and Widget Corporation (hereinafter \"Defendant'')"
],
"tokens": {
"input": 0,
"output": 0,
"total": 0
}
},
"message": "Summary extracted successfully"
}Response Fields
| Field | Type | Description |
|---|---|---|
data | object | Response data object |
data.summary | array | Array of summary text. Abstractive returns single element; Extractive returns multiple extracted sentences |
data.tokens | object | Token usage (only for abstractive type) |
data.tokens.input | integer | Input tokens consumed |
data.tokens.output | integer | Output tokens generated |
data.tokens.total | integer | Total tokens used |
message | string | Human-readable response message |
Understanding Token Usage
For Abstractive Type:
Token usage is calculated based on document size and compression ratio:
- Input tokens: Tokens from the original document
- Output tokens: Tokens in the generated summary
- Total tokens: Combined input + output tokens
For Extractive Type:
- All token values are 0 (no AI processing required)
- No LLM costs incurred
Error Responses
401 Unauthorized
{
"data": {},
"message": "Invalid or missing access key"
}Cause: Missing or invalid access-key header
422 Unprocessable Entity - Invalid Model Name
{
"detail": [
{
"type": "literal_error",
"loc": [
"body",
"model_data",
"model_name"
],
"msg": "Input should be 'gpt-5-chat-latest', 'gpt-5.1', 'gpt-5-mini', 'claude-sonnet-4-5-20250929', 'gemini/gemini-2.5-flash-lite', 'mistral/mistral-small-latest', 'mistral/mistral-medium-latest', 'gemini/gemini-2.5-pro', 'gemini/gemini-3-pro-preview' or 'llama3.1-70b'",
"input": "",
"ctx": {
"expected": "'gpt-5-chat-latest', 'gpt-5.1', 'gpt-5-mini', 'claude-sonnet-4-5-20250929', 'gemini/gemini-2.5-flash-lite', 'mistral/mistral-small-latest', 'mistral/mistral-medium-latest', 'gemini/gemini-2.5-pro', 'gemini/gemini-3-pro-preview' or 'llama3.1-70b'"
}
}
]
}Cause: Invalid or unsupported model_name in model_data. See supported models list above.
422 Unprocessable Entity - Invalid Type
{
"detail": [
{
"type": "literal_error",
"loc": [
"body",
"type"
],
"msg": "Input should be 'abstractive' or 'extractive'",
"input": "",
"ctx": {
"expected": "'abstractive' or 'extractive'"
}
}
]
}Cause: Invalid value for type field. Must be either abstractive or extractive.
422 Unprocessable Entity - Missing Compression Ratio
{
"detail": [
{
"type": "json_invalid",
"loc": [
"body",
124
],
"msg": "JSON decode error",
"input": {},
"ctx": {
"error": "Expecting value"
}
}
]
}Causes:
- Missing
compression_ratiofield - Invalid
compression_ratiovalue (must be 20-80) - Malformed JSON request body
400 Bad Request - Invalid Document IDs
{
"data": {},
"message": "Invalid docs selected"
}Causes: Missing or invalid doc_process_ids.
500 Internal Server Error - Invalid LLM API Key
{
"data": {},
"message": "litellm.AuthenticationError: AuthenticationError: OpenAIException - Incorrect API key provided: tyrdfuih**uhf7. You can find your API key at https://platform.openai.com/account/api-keys."
}Cause: The api_key provided in model_data is invalid or expired. Verify your LLM provider API key.
500 Internal Server Error - General Error
{
"data": {},
"message": "Something went wrong"
}Causes:
- LLM service temporarily unavailable
- Server-side processing error
Code Snippets
cURL
curl --location 'https://api.k-v.ai/api/agent/text_summarizer' \
--header 'access-key: YOUR_ACCESS_KEY' \
--header 'Content-Type: application/json' \
--data '{
"doc_process_ids": [
"264dfa262b748d15ccbeaada89430c68"
],
"focus_areas":["pricing"],
"compression_ratio": 30,
"type": "abstractive",
"model_data": {
"model_name": "gpt-5.1",
"api_key": ""
}
}'Python
import requests
import json
url = "https://api.k-v.ai/api/agent/text_summarizer"
payload = json.dumps({
"doc_process_ids": [
"264dfa262b748d15ccbeaada89430c68"
],
"focus_areas": [
"pricing"
],
"compression_ratio": 30,
"type": "abstractive",
"model_data": {
"model_name": "gpt-5.1",
"api_key": ""
}
})
headers = {
'access-key': 'YOUR_ACCESS_KEY',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)JavaScript (Node.js)
const axios = require('axios');
let data = JSON.stringify({
"doc_process_ids": [
"264dfa262b748d15ccbeaada89430c68"
],
"focus_areas": [
"pricing"
],
"compression_ratio": 30,
"type": "abstractive",
"model_data": {
"model_name": "gpt-5.1",
"api_key": ""
}
});
let config = {
method: 'post',
maxBodyLength: Infinity,
url: 'https://api.k-v.ai/api/agent/text_summarizer',
headers: {
'access-key': 'YOUR_ACCESS_KEY',
'Content-Type': 'application/json'
},
data : data
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});Important Notes
- Document Processing: Only summarize documents with status: "processed"
- Compression Ratio: Only applicable for abstractive type (ignored for extractive)
- Model Selection: Model choice only matters for abstractive type
- Summary Length: Abstractive returns single summary; Extractive returns multiple sentences
Next Steps
After generating summaries:
- Review Quality: Verify summary accuracy against source document
- Adjust Parameters: Refine compression ratio and focus areas based on results
Need Help? Contact support at support@k-v.ai