LLM Text Tools¶
Eight endpoints that apply an LLM to common text-intelligence tasks — no LLM SDK, no API keys of your own, no prompt plumbing.
Moved: these endpoints used to be documented as
/v1/llm-*on the Dev Toolkit. They now live on the AI Text service under/v1/ai/*. The/v1/llm-*paths no longer exist and return404. Update any hard-coded URLs.
Base URL: https://ai-text.toolkitapi.io
| Endpoint | Purpose |
|---|---|
POST /v1/ai/extract |
Extract structured data from text via JSON Schema |
POST /v1/ai/classify |
Classify text into one or more categories |
POST /v1/ai/summarize |
Summarize text (paragraph, bullets, or one line) |
POST /v1/ai/summarize-local |
Summarize on a self-hosted GPU model (BART) |
POST /v1/ai/sentiment |
Detect sentiment, score, and emotions |
POST /v1/ai/translate |
Translate text with optional tone control |
POST /v1/ai/rewrite |
Rewrite text in a different tone |
POST /v1/ai/entities |
Extract named entities |
All endpoints are POST with a JSON body and require X-API-Key.
Common request fields¶
| Field | Type | Default | Notes |
|---|---|---|---|
text |
string | required | Input text. Max 4000 chars on most endpoints, 8000 on summarize. |
temperature |
number | varies | 0.0–1.0. Defaults: 0.1 (extract/classify/sentiment/entities), 0.3 (summarize/translate), 0.5 (rewrite). |
Every successful response echoes input_length (character count of your input).
Extract¶
POST /v1/ai/extract
| Field | Type | Required | Notes |
|---|---|---|---|
text |
string | yes | Text to extract from (≤4000 chars) |
schema |
object | yes | JSON Schema describing the output shape |
temperature |
number | no | Default 0.1 |
schema is also accepted under its internal name schema_def; both are mapped to the same field.
curl -X POST "https://ai-text.toolkitapi.io/v1/ai/extract" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Invoice #1042 from Acme Corp. Total: $4,250. Due: July 15, 2024",
"schema": {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"vendor": {"type": "string"},
"total": {"type": "number"}
}
}
}'
import requests
r = requests.post(
"https://ai-text.toolkitapi.io/v1/ai/extract",
headers={"X-API-Key": "YOUR_KEY"},
json={
"text": "Invoice #1042 from Acme Corp. Total: $4,250. Due: July 15, 2024",
"schema": {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"vendor": {"type": "string"},
"total": {"type": "number"},
"due_date": {"type": "string"},
},
},
},
timeout=90,
)
r.raise_for_status()
print(r.json()["extracted"])
const resp = await fetch("https://ai-text.toolkitapi.io/v1/ai/extract", {
method: "POST",
headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
body: JSON.stringify({
text: "Invoice #1042 from Acme Corp. Total: $4,250. Due: July 15, 2024",
schema: {
type: "object",
properties: {
invoice_number: { type: "string" },
vendor: { type: "string" },
total: { type: "number" },
},
},
}),
});
const data = await resp.json();
console.log(data.extracted);
Response:
{
"extracted": {
"invoice_number": "1042",
"vendor": "Acme Corp",
"total": 4250.0
},
"input_length": 58
}
Classify¶
POST /v1/ai/classify
| Field | Type | Required | Notes |
|---|---|---|---|
text |
string | yes | ≤4000 chars |
categories |
string[] | yes | 2–50 candidate labels |
multi_label |
boolean | no | Default false. When true, several labels may match. |
temperature |
number | no | Default 0.1 |
curl -X POST "https://ai-text.toolkitapi.io/v1/ai/classify" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "My order arrived damaged and support has not responded",
"categories": ["billing", "shipping", "product_quality", "customer_support"]
}'
import requests
r = requests.post(
"https://ai-text.toolkitapi.io/v1/ai/classify",
headers={"X-API-Key": "YOUR_KEY"},
json={
"text": "The package was crushed and the invoice was wrong.",
"categories": ["billing", "shipping", "product_quality", "customer_support"],
"multi_label": True,
},
timeout=90,
)
print(r.json())
const resp = await fetch("https://ai-text.toolkitapi.io/v1/ai/classify", {
method: "POST",
headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
body: JSON.stringify({
text: "My order arrived damaged",
categories: ["billing", "shipping", "product_quality", "customer_support"],
}),
});
const data = await resp.json();
console.log(data.categories, data.confidence);
Response shape (categories is always an array, even in single-label mode):
{
"categories": ["product_quality"],
"confidence": { "product_quality": 0.92 },
"reasoning": "The text describes a damaged product rather than a billing or shipping issue.",
"input_length": 26
}
Summarize¶
POST /v1/ai/summarize
| Field | Type | Required | Notes |
|---|---|---|---|
text |
string | yes | ≤8000 chars |
max_length |
integer | no | Target words, 10–1000, default 150 |
style |
enum | no | paragraph (default), bullets, one_line |
temperature |
number | no | Default 0.3 |
curl -X POST "https://ai-text.toolkitapi.io/v1/ai/summarize" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Long article text...", "max_length": 100, "style": "bullets"}'
import requests
r = requests.post(
"https://ai-text.toolkitapi.io/v1/ai/summarize",
headers={"X-API-Key": "YOUR_KEY"},
json={"text": article, "style": "bullets", "max_length": 100},
timeout=120,
)
print(r.json()["summary"])
const resp = await fetch("https://ai-text.toolkitapi.io/v1/ai/summarize", {
method: "POST",
headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
body: JSON.stringify({ text: article, style: "one_line", max_length: 40 }),
});
const data = await resp.json();
console.log(data.summary);
Response:
{
"summary": "- Point one\n- Point two\n- Point three",
"word_count": 12,
"input_length": 4210
}
Summarize locally (GPU)¶
POST /v1/ai/summarize-local
Same request body as summarize (max_length maps to the model's output length). Runs a locally hosted BART model instead of a hosted LLM — free, but requires the GPU worker.
Response includes model: "bart-large-cnn".
curl -X POST "https://ai-text.toolkitapi.io/v1/ai/summarize-local" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Long article text...", "max_length": 150}'
This endpoint returns 503 when the GPU task API is unreachable, and 504 if the job times out — unlike the hosted endpoints, which return 200 with an error payload.
Sentiment¶
POST /v1/ai/sentiment
| Field | Type | Required | Notes |
|---|---|---|---|
text |
string | yes | ≤4000 chars |
temperature |
number | no | Default 0.1 |
curl -X POST "https://ai-text.toolkitapi.io/v1/ai/sentiment" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Absolutely love the new update, it fixed everything!"}'
import requests
r = requests.post(
"https://ai-text.toolkitapi.io/v1/ai/sentiment",
headers={"X-API-Key": "YOUR_KEY"},
json={"text": review},
timeout=90,
)
d = r.json()
print(d["sentiment"], d["score"], d["emotions"])
const resp = await fetch("https://ai-text.toolkitapi.io/v1/ai/sentiment", {
method: "POST",
headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
body: JSON.stringify({ text: "Love the new update!" }),
});
const data = await resp.json();
console.log(`${data.sentiment} (${data.score})`);
Response:
{
"sentiment": "positive",
"score": 0.87,
"emotions": { "joy": 0.82, "trust": 0.55, "surprise": 0.12 },
"reasoning": "The text expresses strong satisfaction with the update.",
"input_length": 19
}
sentiment is one of positive, negative, neutral, mixed. score runs -1.0 (very negative) to 1.0 (very positive).
Translate¶
POST /v1/ai/translate
| Field | Type | Required | Notes |
|---|---|---|---|
text |
string | yes | ≤4000 chars |
target_language |
string | yes | Name or code, ≤50 chars, e.g. Spanish, ja |
source_language |
string | no | Omit to auto-detect |
tone |
enum | no | neutral (default), formal, casual |
temperature |
number | no | Default 0.3 |
curl -X POST "https://ai-text.toolkitapi.io/v1/ai/translate" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Hello, how are you?", "target_language": "Spanish", "tone": "casual"}'
import requests
r = requests.post(
"https://ai-text.toolkitapi.io/v1/ai/translate",
headers={"X-API-Key": "YOUR_KEY"},
json={
"text": "Welcome to our platform. Please review our terms.",
"target_language": "Japanese",
"tone": "formal",
},
timeout=90,
)
d = r.json()
print(d["translated"], d["source_language"])
const resp = await fetch("https://ai-text.toolkitapi.io/v1/ai/translate", {
method: "POST",
headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
body: JSON.stringify({ text: "Hello!", target_language: "French", tone: "casual" }),
});
const data = await resp.json();
console.log(data.translated, data.source_language);
Response uses translated (not translated_text):
{
"translated": "¡Hola! ¿Cómo estás?",
"source_language": "English",
"target_language": "Spanish",
"input_length": 19
}
Rewrite¶
POST /v1/ai/rewrite
| Field | Type | Required | Notes |
|---|---|---|---|
text |
string | yes | ≤4000 chars |
tone |
enum | yes | formal, casual, concise, persuasive, friendly, professional, technical, simple |
instructions |
string | no | Extra guidance, ≤500 chars |
temperature |
number | no | Default 0.5 |
curl -X POST "https://ai-text.toolkitapi.io/v1/ai/rewrite" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Your request has been denied due to insufficient documentation.", "tone": "friendly"}'
import requests
r = requests.post(
"https://ai-text.toolkitapi.io/v1/ai/rewrite",
headers={"X-API-Key": "YOUR_KEY"},
json={
"text": original,
"tone": "concise",
"instructions": "Rewrite as a short SMS under 160 characters.",
},
timeout=90,
)
print(r.json()["rewritten"])
const resp = await fetch("https://ai-text.toolkitapi.io/v1/ai/rewrite", {
method: "POST",
headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
body: JSON.stringify({ text: original, tone: "professional" }),
});
const data = await resp.json();
console.log(data.rewritten, data.word_count);
Response:
{
"rewritten": "We're sorry — we couldn't approve this yet because some documents are missing.",
"tone": "friendly",
"word_count": 14,
"input_length": 63
}
Entities¶
POST /v1/ai/entities
| Field | Type | Required | Notes |
|---|---|---|---|
text |
string | yes | ≤4000 chars |
entity_types |
string[] | no | Omit for all types. Otherwise e.g. ["person", "organization"] |
temperature |
number | no | Default 0.1 |
curl -X POST "https://ai-text.toolkitapi.io/v1/ai/entities" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "On Monday, Apple CEO Tim Cook met Ursula von der Leyen in Brussels.", "entity_types": ["person", "organization", "location"]}'
import requests
r = requests.post(
"https://ai-text.toolkitapi.io/v1/ai/entities",
headers={"X-API-Key": "YOUR_KEY"},
json={"text": text},
timeout=90,
)
for e in r.json()["entities"]:
print(e["type"], "-", e["text"])
const resp = await fetch("https://ai-text.toolkitapi.io/v1/ai/entities", {
method: "POST",
headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
body: JSON.stringify({ text, entity_types: ["person", "organization"] }),
});
const data = await resp.json();
console.log(data.entity_count, data.entities);
Response — each entity has text, type, and a short context snippet:
{
"entities": [
{ "text": "Apple", "type": "organization", "context": "Apple CEO Tim Cook" },
{ "text": "Tim Cook", "type": "person", "context": "Apple CEO Tim Cook met" },
{ "text": "Brussels", "type": "location", "context": "in Brussels" }
],
"entity_count": 3,
"input_length": 78
}
Error handling¶
Validation failures (missing text, categories shorter than 2 items, max_length outside 10–1000, text over the length cap) return 422:
{
"detail": [
{ "type": "missing", "loc": ["body", "text"], "msg": "Field required" }
]
}
LLM failures do not raise HTTP errors. The hosted endpoints catch exceptions and return 200 with an error payload — always check for it:
{ "error": "LLM returned invalid JSON", "raw_response": "Here is the data you asked for: ..." }
{ "error": "LLM extraction failed: LLM is not configured" }
The raw_response field is invaluable for debugging malformed model output — tighten your schema or lower temperature and retry.
Missing credentials return 401; GPU endpoints return 503 (worker unavailable) or 504 (timeout).
Tips¶
- Schemas beat instructions. For
extract, the more specific your JSON Schema (types, required fields, enums), the more reliable the output. Follow up withjson-schema-validateon the Dev Toolkit to verify before trusting it downstream. - Lower
temperaturefor structure.0.0–0.2keeps JSON output stable; raise it only for creative rewrites. - Chunk long documents.
summarizeaccepts 8000 chars; everything else caps at 4000. For longer input, split on paragraph boundaries and summarize each chunk, then summarize the summaries. input_lengthis your cost signal. It's returned on every call so you can log token-ish volume per request without a separate accounting path.- Prefer
summarize-localfor volume. It avoids per-call LLM cost entirely when the GPU worker is up — good for batch backfills.
Related endpoints¶
GET /v1/image/describe— caption an image with a vision modelPOST /v1/pdf/text— pull text out of a PDF first, then feed it herePOST /v1/scrape— fetch page content to summarize