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 return 404. 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 with json-schema-validate on the Dev Toolkit to verify before trusting it downstream.
  • Lower temperature for structure. 0.0–0.2 keeps JSON output stable; raise it only for creative rewrites.
  • Chunk long documents. summarize accepts 8000 chars; everything else caps at 4000. For longer input, split on paragraph boundaries and summarize each chunk, then summarize the summaries.
  • input_length is 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-local for volume. It avoids per-call LLM cost entirely when the GPU worker is up — good for batch backfills.
  • GET /v1/image/describe — caption an image with a vision model
  • POST /v1/pdf/text — pull text out of a PDF first, then feed it here
  • POST /v1/scrape — fetch page content to summarize