API reference

Your first call

Base URL https://api-enterprise-ai.teeoff.tech/api/enterprise/v1. Every operation below hangs off it.

X-Client-Id: ACME-PROD
X-API-Key:   tea_live_…

curl -X POST https://api-enterprise-ai.teeoff.tech/api/enterprise/v1/tts/speak \
  -H "X-Client-Id: $CLIENT_ID" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Mhoro, ndinonzi Natasha.", "voice": "natasha"}'

const ws = new WebSocket("wss://api-enterprise-ai.teeoff.tech/api/enterprise/v1/ws/tts")
ws.onopen = () => ws.send(JSON.stringify({
  type: "auth", client_id: CLIENT_ID, api_key: API_KEY
}))
// binary frames back are raw PCM, mono int16 LE

Authentication

Server-to-server calls authenticate with an API key sent as two headers. The key has the form <prefix>_<secret>; only the 12-character prefix is stored in the clear, and the secret is hashed with a per-key salt. Verification is constant-time, so an unknown client costs the same CPU as a valid one.

X-Client-Id: ACME-PROD
X-API-Key:   tea_live_<22-char-suffix>

Browser code must never carry an API key. The console issues a short-lived JWT for that case, which the WebSocket routes accept as ?token=.

Response envelope

Every JSON response — success and error alike — arrives in the same wrapper. body carries the typed payload and is null on error; errors carries stable catalogue codes and is null on success. Write your client against the envelope once and every endpoint behaves the same.

{
  "status": 200,
  "message": "OK",
  "errors": null,
  "timestamp": 1712534400000,
  "path": "/api/enterprise/v1/tts/speak",
  "body": { "…": "T" },
  "paginationDetails": null
}

Every paginated route takes the same two query parameters — no cursor, no POST body. Page numbers are 0-indexed.

{
  "numberOfElements": 20,
  "totalElements": 117,
  "size": 20,
  "pageNumber": 0,
  "totalPages": 6,
  "empty": false,
  "first": true,
  "last": false
}

How audio crosses the wire

The one table worth reading before writing a client — the four routes carry media four different ways.

• The two sockets negotiate different sample rates — 24 kHz down from TTS, 16 kHz up to STT. Piping one into the other needs a resample, and the session frame tells you what was actually negotiated.
• Streaming audio is never archived. Only POST /tts/speak produces a stored artifact; STT audio is never stored in either mode.

{
  "text": "Mhoro, ndinonzi Natasha.",
  "voice": "natasha",
  "max_duration_seconds": 60
}

{
  "request_id": "01K1EXAMPLE",
  "audio_url": "https://content-enterprise-ai.teeoff.tech/…wav",
  "provider": "teevoice-speak",
  "voice": "natasha",
  "duration_seconds": 5.723,
  "sample_rate": 24000,
  "billed_seconds": 6
}

curl -X POST https://api-enterprise-ai.teeoff.tech/api/enterprise/v1/tts/speak \
  -H "X-Client-Id: $CLIENT_ID" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Mhoro, ndinonzi Natasha.", "voice": "natasha"}'

[
  {
    "id": "natasha",
    "name": "Natasha",
    "language": "sn",
    "description": "Shona female, fine-tuned accent (production default)"
  }
]

curl https://api-enterprise-ai.teeoff.tech/api/enterprise/v1/tts/voices \
  -H "X-Client-Id: $CLIENT_ID" -H "X-API-Key: $API_KEY"

{"voice":"natasha","encoding":"pcm_s16le","max_duration_seconds":60}

{"type":"text","text":"Mhoro, ndinonzi Natasha."}
{"type":"flush"}   // speak what is buffered now
{"type":"clear"}   // barge-in: drop buffered and in-flight audio
{"type":"end"}     // no more text; drain and close

// binary frame  -> audio: raw PCM, mono int16 LE @ negotiated sample_rate
{"type":"session","voice":"natasha","encoding":"pcm_s16le","sample_rate":24000}
{"type":"error","message":"…"}

curl "https://api-enterprise-ai.teeoff.tech/api/enterprise/v1/tts/history?page=0&size=20" \
  -H "X-Client-Id: $CLIENT_ID" -H "X-API-Key: $API_KEY"

{
  "request_id": "01K1EXAMPLE",
  "text": "mhoro ndinonzi natasha uku kuedza kwetv",
  "provider": "teevoice-listen",
  "language": "sn",
  "duration_seconds": 5.72,
  "billed_seconds": 6,
  "segments": [
    { "text": "mhoro ndinonzi natasha", "is_final": true,
      "start": 0.0, "end": 2.1 }
  ]
}

# transcode first if needed:
# ffmpeg -i in.mp3 -ac 1 -ar 16000 -c:a pcm_s16le out.wav

curl -X POST https://api-enterprise-ai.teeoff.tech/api/enterprise/v1/stt/transcribe \
  -H "X-Client-Id: $CLIENT_ID" -H "X-API-Key: $API_KEY" \
  -F "file=@speech.wav" -F "language=sn"

{"language":"sn","sample_rate":16000}

// binary frames -> raw PCM, mono int16 LE @ 16000 Hz
{"type":"end"}   // flush the final transcript and close

{"type":"session","language":"sn","sample_rate":16000,"encoding":"pcm_s16le"}
{"type":"partial","text":"hongu natasha","start":null,"end":null}
{"type":"final","text":"mhoro ndinonzi natasha","start":0.0,"end":2.1}

curl "https://api-enterprise-ai.teeoff.tech/api/enterprise/v1/stt/history?page=0&size=20" \
  -H "X-Client-Id: $CLIENT_ID" -H "X-API-Key: $API_KEY"

WebSocket admission

Both sockets share one admission sequence; only the config and data frames differ. Neither route appears in the OpenAPI document — OpenAPI cannot describe them — so this is their specification.

{"type": "auth", "client_id": "acme", "api_key": "tea_live_…"}

// or, as a query string
?client_id=…&api_key=…     machine clients
?token=<console JWT>       browser code, which must never embed an API key

{"type":"ready","request_id":"01K1…","feature":"TTS",
 "max_session_seconds":900,"quota_remaining_seconds":1794}

// client → server (optional)
{"voice":"natasha","encoding":"pcm_s16le","max_duration_seconds":60}

// server → client, confirming what was negotiated
{"type":"session","voice":"natasha","encoding":"pcm_s16le","sample_rate":24000}

• Idle timeout 120 s with no input; hard session cap 900 s. Either sends a notice frame before closing.
• max_session_seconds is the lesser of the configured cap and your remaining monthly quota — quota is checked once at connect, so it acts as a limit rather than a gate.
• A clean end closes 1000; admission failures close 1008 — but the structured error arrives as a normal frame first, because browsers cannot read a close reason reliably.
• Metering is per connection, not per frame: one usage row is written at close. Audio arrives at roughly 50 frames a second, and a rate-limit round-trip per frame would cost more than the inference.

{"type":"error","status":402,"code":"quota_exceeded","message":"…"}

status mirrors the HTTP status the same failure would have produced — 401, 402, 403, 429, 500 — so telemetry stays comparable across transports.