# Speech playground and APIs

Integration contracts for real transcription, synthesis, and translation engines.

## Select a project first [#select-a-project-first]

Choose a project in the console sidebar, then open speech recognition, speech synthesis, or text translation. The playground uses your current login session; you do not need to paste an API key into the browser.

Only owners and developers in the project's organization can submit requests; viewers can see the entry points. The project needs approved cloud-service access and a valid, unexpired license. An unconfigured engine returns 503, and the page explicitly shows that it is not connected.

## File transcription [#file-transcription]

`POST /api/platform/v1/audio/transcriptions`

Headers: `Authorization: Bearer YOUR_API_KEY`, `Content-Type: application/json`.

```json
{
  "audioBase64": "<Base64 audio without a data: prefix>",
  "mimeType": "audio/wav",
  "language": "en"
}
```

`language` is optional. Supported containers are WAV, MP3, OGG, WebM, and MP4/M4A, with a maximum file size of 5 MiB. The server validates Base64, file size, and consistency between the audio header and MIME type. This is not full media-decoding validation; the upstream must still decode safely and enforce duration limits.

This example illustrates the response structure only. Actual results come from the connected engine:

```json
{
  "text": "Actual transcription text",
  "language": "en",
  "segments": [
    { "start": 0, "end": 1.2, "text": "Actual transcription text", "speaker": "speaker_1" }
  ]
}
```

`segments`, `language`, and `speaker` are optional. The interface does not invent timestamps or speakers when the upstream omits them.

## Speech synthesis [#speech-synthesis]

`POST /api/platform/v1/audio/speech`

```json
{ "text": "Hello, welcome to Elejo.", "language": "en" }
```

`text` accepts 1–5000 characters. `language` is optional. `voice` is an upstream-supported voice ID; omit it to use the engine's default. No fictitious voice catalog is provided.

The response is `{ "audioBase64": "...", "mimeType": "audio/wav" }`. The playground converts the actual audio to a Blob in the current browser for playback and download, then releases the Blob URL when you leave the page. Synthesized audio is also limited to 5 MiB. The browser does not load arbitrary audio URLs returned by the upstream.

## Text translation [#text-translation]

`POST /api/platform/v1/translate`

```json
{ "text": "Hello, world.", "source": "en", "target": "zh" }
```

The response is `{ "translation": "Actual translated text" }`. Input is limited to 5000 characters. Language codes accept forms such as `zh`, `en`, or `en-US`.

## Server-side adapters [#server-side-adapters]

The server reads `AI_UPSTREAM_URL`, `STT_UPSTREAM_URL`, `TTS_UPSTREAM_URL`, and each corresponding `_TOKEN`. Upstreams must use HTTPS. The browser cannot supply an arbitrary upstream address. Requests and responses follow the JSON protocols on this page; deploy a translation layer if the provider uses a different protocol.

Optional model settings are `TRANSLATION_MODEL`, `STT_MODEL`, and `TTS_MODEL`. When configured, the platform adds a `model` field to upstream requests. Credentials remain on the server and are not exposed in capability status or project cards.

All upstreams have a 30-second timeout. Responses are constrained by size, structure, status, and audio format. Invalid responses return 502; timeouts return 504. Billable calls are not retried automatically, to avoid duplicate execution.

## Usage and quotas [#usage-and-quotas]

Each request reserves organization and project quota in a transaction. Success writes one usage record. Failure releases the reserved monthly character quota but still consumes a request in the rolling 60-second window. Translation and synthesis record input characters. File transcription records request count only, with zero characters; audio-duration billing is not implemented.

The platform does not store raw input text, audio, or inference results in its database. Content is sent to the administrator-configured upstream. The deployment operator and upstream provider must agree on retention policies.

## Current scope [#current-scope]

These are HTTP endpoints for file transcription and synthesis. Real-time WebSocket transcription, streaming synthesis, long-audio task queues, and a voice catalog are not implemented. Providing a cloud gateway does not mean speech models have been delivered or deployed.

See [OpenAPI](/openapi.json) for the machine-readable contract and [console management](/en/docs/console) for quota and security settings.
