Logo
Search & Inference

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

HeaderTypeRequiredDescription
access-keystringYesYour unique access-key generated from the platform UI
Content-TypestringYesMust 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

FieldTypeRequiredDescription
doc_process_idsarrayYesArray of document IDs to summarize (obtained from Upload or List Documents APIs)
focus_areasarrayNoList of specific topics or areas to focus the summary on. Leave empty for general summary
compression_ratiointegerYesCompression percentage (20-80). Only applicable for abstractive type
typestringYesSummarization type: abstractive (AI-generated) or extractive (sentence-based)
model_dataobjectYesAI model configuration (only used for abstractive type)
model_data.model_namestringYesAI model to use for summarization (see supported models below)

Summarization Types

TypeDescriptionAI RequiredCompression Control
abstractiveAI-generated summary with paraphrasing and rewritingYesYes (20-80%)
extractiveSentence-based extraction directly from documentNoNo

Note: For extractive type, the compression ratio parameter is ignored.


Supported AI Models

Model NameProvider
gpt-5.1OpenAI
gpt-5-miniOpenAI
claude-sonnet-4-5-20250929Anthropic
gemini/gemini-2.5-flash-liteGoogle
gemini/gemini-2.5-proGoogle
gemini/gemini-3-pro-previewGoogle
mistral/mistral-small-latestMistral AI
mistral/mistral-medium-latestMistral AI
llama3.1-70bMeta

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

FieldTypeDescription
dataobjectResponse data object
data.summaryarrayArray of summary text. Abstractive returns single element; Extractive returns multiple extracted sentences
data.tokensobjectToken usage (only for abstractive type)
data.tokens.inputintegerInput tokens consumed
data.tokens.outputintegerOutput tokens generated
data.tokens.totalintegerTotal tokens used
messagestringHuman-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_ratio field
  • Invalid compression_ratio value (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:

  1. Review Quality: Verify summary accuracy against source document
  2. Adjust Parameters: Refine compression ratio and focus areas based on results

Need Help? Contact support at support@k-v.ai

On this page