Text Vetting Service API

Microservice for correcting speech-to-text transcription errors and generating summaries with AI. View Stats

Authentication: All endpoints (except /health, /stats, and docs) require X-API-Key header.

Endpoints

GET /health

Health check. No authentication required.

curl /health

Response: { "status": "ok", "provider": "GROQ", "model": "llama-3.3-70b-versatile" }

GET /balances

Return balance/usage information for all configured AI providers.

Requires X-API-Key header.

curl /balances \
  -H "X-API-Key: YOUR_KEY"

Response (example):

{
  "provider": "OPENROUTER_AI",
  "model": "google/gemini-3-flash-preview",
  "openrouter": {
    "enabled": true,
    "ok": true,
    "label": "your-key-label",
    "spendingLimitUsd": 100.0,
    "remainingLimitUsd": 42.5,
    "totalUsageUsd": 57.5
  },
  "groq": {
    "enabled": true,
    "ok": true,
    "remainingRequestsPerDay": "9999",
    "remainingTokensPerMinute": "100000"
  },
  "googleAi": {
    "enabled": false,
    "ok": false,
    "note": "Google AI Studio does not expose a simple balance endpoint; check billing dashboard for detailed usage."
  }
}

POST /correct

Submit text for transcription error correction. Returns a job ID for polling.

Body (JSON)TypeDescription
textstringThe raw transcription text to correct (min 10 chars)
languagestringLocale code: en, el, de, fr, etc.
curl -X POST /correct \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "...", "language": "en"}'

Response (202): { "jobId": "...", "status": "processing" }

GET /correct/:jobId

Poll correction job status. When status is completed, result contains the corrected text.

curl /correct/JOB_ID -H "X-API-Key: YOUR_KEY"

Response (completed):

{
  "id": "...",
  "status": "completed",
  "result": {
    "correctedText": "...",
    "model": "GROQ (llama-3.3-70b-versatile)",
    "wasTruncated": false
  }
}

POST /summarize

Submit text for summarization, headline extraction, and paragraph formatting. Optionally include diarization segments for speaker labeling.

Body (JSON)TypeDescription
textstringThe transcript text (min 20 chars)
languagestringLocale code
labeledParagraphsarray (optional)Best: finished, corrected speaker paragraphs [{speaker, text}]. Used verbatim; only SPEAKER_xx→name mapping runs.
labeledSegmentsarray (optional)Transcript segments joined to speakers on real timestamps: [{start, end, text, speaker}] (raw ASR text). Merged into paragraphs when labeledParagraphs is absent; also drives speaker count / interview detection.
isInterviewboolean (optional)Caller's audio-derived hint that this is an interview / Q&A. Overrides the internal heuristic.
diarizeSegmentsarray (optional)Legacy fallback when labeledSegments is absent: [{start, end, speaker}]; sentence times are estimated by character position (drifts on long audio).
curl -X POST /summarize \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "...", "language": "en"}'

Response (202): { "jobId": "...", "status": "processing" }

GET /summarize/:jobId

Poll summarization job status.

curl /summarize/JOB_ID -H "X-API-Key: YOUR_KEY"

Response (completed):

{
  "id": "...",
  "status": "completed",
  "result": {
    "headline": "...",
    "summary": "...",
    "formatIntro": "...",
    "mainPoints": ["..."],
    "participants": ["..."],
    "speakerCount": 2,
    "paragraphs": [{"speaker": "SPEAKER_00", "text": "..."}],
    "model": "GROQ (llama-3.3-70b-versatile)"
  }
}

Typical Integration Flow

1. POST /correct with raw transcription text -> get jobId
2. Poll GET /correct/{jobId} until status == "completed"
3. POST /summarize with corrected text + optional diarization -> get jobId
4. Poll GET /summarize/{jobId} until status == "completed"
5. Use result for display