JSON Output

Stable JSON contracts for transcripts and models.

Overview

Transcription, alignment, and segmentation share EdgeSpeak's structured transcript conventions; the app export and CLI expose the same fields when the same output mode is selected. Speech synthesis, speaker, model, language-model, MCP, and Realtime endpoints use their own response contracts.

POST /v1/audio/transcriptions  →  {task:"transcribe", duration, language?, text, segments[], usage}
POST /v1/audio/alignments      →  {task:"align", duration, text, segments[], usage}
POST /v1/text/segmentations    →  {task:"segment", text, segments[]}
GET  /v1/models                →  {object:"list", data[]}

POST /v1/audio/transcriptions

Multipart upload. Use response_format=json, verbose_json, text, or diarized_json. Word or segment timestamp granularities require verbose_json or diarized_json; stream=true returns SSE text deltas only with the JSON mode and no timestamp granularities, and only on the desktop gateway — the headless service refuses stream=true with 400.

curl http://127.0.0.1:1117/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-edgespeak-..." \
  -F file=@meeting.m4a \
  -F model="lattice-2-flash" \
  -F response_format=verbose_json \
  -F "timestamp_granularities[]=word"

{
  "task": "transcribe",
  "duration": 19.69,
  "language": "English",
  "text": "EdgeSpeak AI is a high-performance engine ...",
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 6.44,
      "text": "EdgeSpeak AI is a high-performance engine designed for ...",
      "words": [
        { "word": "EdgeSpeak", "start": 0.22, "end": 0.64, "score": 0.991 }
      ]
    }
  ],
  "usage": { "type": "duration", "seconds": 19.69 }
}

POST /v1/audio/alignments

Forced alignment: you provide the transcript, the engine returns word-level timing. Reference text goes in the text field, or text_path — an absolute file path the gateway reads locally. The response never carries a language key; score is a confidence in [0, 1].

curl http://127.0.0.1:1117/v1/audio/alignments \
  -H "Authorization: Bearer sk-edgespeak-..." \
  -F file=@meeting.m4a \
  -F text="LattifAI is a high performance engine ..."

{
  "task": "align",
  "duration": 19.6909375,
  "text": "LattifAI is a high performance engine ...",
  "segments": [
    {
      "id": 0,
      "start": 0.22,
      "end": 19.52,
      "text": "LattifAI is a high performance engine ...",
      "words": [
        { "word": "LattifAI", "start": 0.22, "end": 1.04, "score": 0.8463 }
      ]
    }
  ],
  "usage": { "type": "duration", "seconds": 19.6909375 }
}

POST /v1/text/segmentations

Semantic sentence segmentation over a JSON body: text for plain text, or segments[] with timing. Plain-text input yields sentences without start and end — speaker, start, and end appear only when the input carried them. Optional threshold (default 0.35), min_chars, max_chars.

curl http://127.0.0.1:1117/v1/text/segmentations \
  -H "Authorization: Bearer sk-edgespeak-..." \
  -H "Content-Type: application/json" \
  -d '{"text": "LattifAI is a high-performance engine designed for the structuring of audio and video content assets. It runs entirely on local compute, ensuring your data security."}'

{
  "task": "segment",
  "text": "LattifAI is a high-performance engine ... It runs entirely on local compute ...",
  "segments": [
    { "text": "LattifAI is a high-performance engine designed for the structuring of audio and video content assets." },
    { "text": "It runs entirely on local compute, ensuring your data security." }
  ]
}

GET /v1/models

Lists the current model catalog. Select models by supported_endpoints, inspect features, check execution_location before sending private content, and use default_for instead of hard-coding aliases.

curl http://127.0.0.1:1117/v1/models \
  -H "Authorization: Bearer sk-edgespeak-..."

{
  "object": "list",
  "data": [
    {
      "id": "EdgeSpeak/Lattice-2-Flash",
      "object": "model",
      "created": 0,
      "owned_by": "EdgeSpeak",
      "supported_endpoints": ["/v1/audio/transcriptions"],
      "features": [],
      "execution_location": "local",
      "default_for": ["/v1/audio/transcriptions"]
    },
    {
      "id": "Qwen/Qwen3.5-4B",
      "object": "model",
      "created": 0,
      "owned_by": "EdgeSpeak",
      "supported_endpoints": ["/v1/chat/completions", "/v1/responses", "/v1/messages", "/v1/tokenize"],
      "features": ["reasoning", "vision", "tool_calling"],
      "execution_location": "local",
      "default_for": []
    }
  ]
}

Field semantics

All transcript timing values are seconds. segments[] items carry {id, start, end, text, words?}; word entries are {word, start, end, score?} with score in [0, 1]. Word timing lives under segments[].words. Transcription and alignment usage is {"type": "duration", "seconds": …}. Optional keys are omitted when unavailable; key order is not guaranteed.