# Valsea

> Valsea is an AI-powered speech intelligence API platform built for Southeast Asia. It provides enterprise-grade speech-to-text transcription, text-to-speech, translation, annotation, clarification, conversion, formatting, and sentiment analysis through simple REST endpoints. The transcription and text-to-speech endpoints are OpenAI SDK compatible. It also offers real-time live transcription and realtime text-to-speech via WebSocket.

- Base URL: https://api.valsea.ai
- Authentication: Bearer token via `Authorization: Bearer YOUR_API_KEY` header
- Alternative auth: `X-API-Key: YOUR_API_KEY` header
- API keys start with `vl_` prefix
- Get API keys from the dashboard at https://valsea.ai/dashboard/api-keys
- All endpoints consume credits from your account balance
- All POST endpoints support two response formats: `json` (default, minimal) and `verbose_json` (extended with metadata)

## Rate Limits and Billing Multipliers

- Paid rate-limit bypass is opt-in for transcription requests and realtime WebSocket sessions.
- To bypass rate limits, send `X-Bypass-Rate-Limit: true` or query `bypass_rate_limit=true` / `bypassRateLimit=true`.
- Bypass skips only the per-organization rate-limit check. Authentication, credit checks, upload/session limits, and all other validation still apply.
- Bypass bills at 2x normal credits and surfaces `X-Credits-Multiplier: 2` on transcription responses or `billingMultiplier: 2` on realtime `session.created` events.
- Speaker diarization also bills at 2x. Bypass plus diarization bills at 4x.

## Docs

- [Introduction](https://valsea.ai/docs): Overview of the platform — transcription, translation, annotation, clarification, conversion, formatting, sentiment analysis, and live transcription
- [Quickstart](https://valsea.ai/docs/quickstart): Get started in under 5 minutes with code examples in cURL, JavaScript, Python, and OpenAI SDK
- [Authentication](https://valsea.ai/docs/authentication): How to get and use API keys, credit system overview
- [Live Transcription via WebSocket](https://valsea.ai/docs/realtime): Real-time streaming speech-to-text via WebSocket at `wss://api.valsea.ai/v1/realtime`
- [Realtime Text to Speech via WebSocket](https://valsea.ai/docs/realtime-tts): Streaming TTS via WebSocket at `wss://api.valsea.ai/v1/realtime/tts`

## API Reference

- [API Overview](https://valsea.ai/docs/api): Summary of REST endpoints with base URL and authentication details

### POST /v1/audio/transcriptions — Transcribe Audio

- [Full documentation](https://valsea.ai/docs/api/transcribe)
- OpenAI SDK compatible — use `baseURL: 'https://api.valsea.ai/v1'` with the official OpenAI TypeScript or Python client
- Content-Type: multipart/form-data
- Parameters:
  - `file` (binary, required): Audio file — WAV, MP3, M4A, FLAC, OGG, WEBM. Max 10 MB, max 1 hour
  - `model` (string, required): Always `valsea-transcribe`
  - `language` (string, required): One of arabic, arabic-algeria, arabic-bahrain, arabic-egypt, arabic-israel, arabic-jordan, arabic-kuwait, arabic-lebanon, arabic-mauritania, arabic-morocco, arabic-oman, arabic-palestine, arabic-qatar, arabic-saudi, arabic-syria, arabic-tunisia, arabic-uae, arabic-yemen, bengali-bd, bengali-in, cantonese, chinese, chinese-simplified, chinese-traditional, english, english-au, english-gb, english-in, english-philippines, english-us, french, french-ca, portuguese, portuguese-br, spanish, spanish-es, spanish-mexico, spanish-us, swahili, swahili-ke, afrikaans, akan, albanian, amharic, armenian, assamese, asturian, azerbaijani, basque, bemba, bulgarian, catalan, croatian, czech, danish, dutch, estonian, filipino, finnish, fulani, ga, galician, georgian, german, greek, gujarati, hausa, hebrew, hindi, hungarian, icelandic, igbo, indonesian, italian, japanese, javanese, kannada, kazakh, khmer, kinyarwanda, korean, kurdish, kyrgyz, lao, latvian, lithuanian, luxembourgish, luganda, macedonian, malay, malayalam, maltese, maori, marathi, mongolian, nepali, northern-sotho, norwegian, nyankole, odia, oromo, oriya, persian, pidgin, polish, punjabi, romanian, russian, serbian, shona, sinhala, singlish, slovak, slovenian, sotho, swedish, tamil, telugu, thai, tswana, twi, turkish, ukrainian, uzbek, vietnamese, welsh, wolof, xhosa, yoruba, zulu
  - `response_format` (string, optional): `json` or `verbose_json`. Default: `json`
  - `enable_correction` (boolean, optional): Enable grammar/language correction. Default: true
  - `enable_tags` (boolean, optional): Enable semantic tagging. Default: true
  - `diarize` (boolean, optional): Enable speaker diarization. Requires `response_format=verbose_json`. Default: false
  - `diarization_min_speakers` / `diarization_max_speakers` (integer, optional): Expected speaker count range. Defaults: 2 and 6
- Response (json): `{ "text": "..." }`
- Response (verbose_json): `{ "text", "raw_transcript", "detected_languages", "corrections", "semantic_tags", "words", "utterances" }`
- Speaker diarization response fields: `words` contains word-level timing plus zero-based `speaker`; `utterances` contains contiguous speaker turns with `start`, `end`, `speaker`, `transcript`, and `words`.
- Speaker diarization bills at 2x normal transcription credits. Paid rate-limit bypass plus diarization bills at 4x.
- Paid rate-limit bypass: send `X-Bypass-Rate-Limit: true` or query `bypass_rate_limit=true` / `bypassRateLimit=true`. This skips only the per-organization rate-limit check and bills the request at 2x normal transcription credits. The response includes `X-Credits-Multiplier: 2`, or `4` when combined with diarization.
- OpenAI TypeScript SDK example: `client.audio.transcriptions.create({ file, model: 'valsea-transcribe', language: 'english' })`
- OpenAI Python SDK example: `client.audio.transcriptions.create(file=open("audio.wav","rb"), model="valsea-transcribe", language="english", extra_body={"enable_correction": True})`
- Diarization example: `client.audio.transcriptions.create({ file, model: 'valsea-transcribe', language: 'english', response_format: 'verbose_json', diarize: true, diarization_min_speakers: 2, diarization_max_speakers: 2 })`
- Bypass example: `fetch('https://api.valsea.ai/v1/audio/transcriptions?bypass_rate_limit=true', { method: 'POST', headers: { Authorization: 'Bearer YOUR_API_KEY', 'X-Bypass-Rate-Limit': 'true' }, body: formData })`

### POST /v1/audio/speech — Text to Speech

- [Full documentation](https://valsea.ai/docs/api/speech)
- OpenAI SDK compatible — use `baseURL: 'https://api.valsea.ai/v1'` with the official OpenAI TypeScript or Python client
- Content-Type: application/json
- Response: binary audio bytes (`audio/mpeg` or `audio/wav`)
- Parameters:
  - `model` (string, required): Always `valsea-tts`
  - `input` (string, required): Text to synthesize
  - `voice` (string, required): `valsea-neutral`, `valsea-male`, or `valsea-female`
  - `language` (string, optional): `vietnamese`, `english`, or Indian-language aliases such as `hindi`, `bengali-in`, `kannada`, `malayalam`, `marathi`, `odia`, `punjabi`, `tamil`, `telugu`, `gujarati`, and `english-in`. Default: `vietnamese`
  - `response_format` (string, optional): `mp3` or `wav`. Default: `mp3`
  - `speed` (number, optional): 0.25 to 4. Default: 1
- Billing: generated audio duration rounded up to the next whole minute
- OpenAI TypeScript SDK example: `client.audio.speech.create({ model: 'valsea-tts', voice: 'valsea-neutral', input: 'Xin chao', response_format: 'mp3', extra_body: { language: 'vietnamese' } })`

### POST /v1/translations — Translate Text

- [Full documentation](https://valsea.ai/docs/api/translate)
- Content-Type: application/json
- Parameters:
  - `model` (string, required): Always `valsea-translate`
  - `text` (string, required): Text to translate
  - `source` (string, optional): Source language name (e.g. "english", "chinese") or "auto" for detection. Default: "auto"
  - `target` (string, required): Target language name (e.g. "chinese", "vietnamese", "thai")
  - `response_format` (string, optional): `json` or `verbose_json`. Default: `json`
- Response (json): `{ "translated_text": "..." }`
- Response (verbose_json): `{ "translated_text", "source_language", "target_language" }`

### POST /v1/annotations — Annotate Text

- [Full documentation](https://valsea.ai/docs/api/annotate)
- Content-Type: application/json
- Annotate text with language corrections and semantic tags. Useful for processing colloquial transcriptions.
- Parameters:
  - `model` (string, required): Always `valsea-annotate`
  - `text` (string, required): Text to annotate
  - `response_format` (string, optional): `json` or `verbose_json`. Default: `json`
  - `language` (string, optional): Language hint (e.g. "singlish")
  - `enable_correction` (boolean, optional): Enable grammar/language correction
  - `enable_tags` (boolean, optional): Enable semantic tagging
- Response (json): `{ "text", "annotations" }`
- Response (verbose_json): `{ "text", "raw_text", "accent_corrections", "semantic_tags", "annotated_text", "annotations" }`

### POST /v1/clarifications — Clarify Text

- [Full documentation](https://valsea.ai/docs/api/clarify)
- Content-Type: application/json
- Transform noisy or colloquial transcriptions into clear, grammatically correct text.
- Parameters:
  - `model` (string, required): Always `valsea-clarify`
  - `text` (string, required): Text to clarify
  - `response_format` (string, optional): `json` or `verbose_json`. Default: `json`
  - `language` (string, optional): Language hint (e.g. "singlish")
- Response (json): `{ "clarified_text": "..." }`
- Response (verbose_json): `{ "clarified_text", "raw_text", "explanations", "revisions" }`

### POST /v1/conversions — Convert Annotated Text

- [Full documentation](https://valsea.ai/docs/api/convert)
- Content-Type: application/json
- Convert annotated text (with semantic tags) into clean, readable text.
- Parameters:
  - `model` (string, required): Always `valsea-convert`
  - `annotated_text` (string, required): Annotated text to convert
  - `response_format` (string, optional): `json` or `verbose_json`. Default: `json`
  - `semantic_tags` (array, optional): Array of `{ tag, phrase, meaning }` objects
- Response (json): `{ "converted_text": "..." }`
- Response (verbose_json): `{ "converted_text", "annotated_text" }`

### POST /v1/formatting — Format Transcript

- [Full documentation](https://valsea.ai/docs/api/format)
- Content-Type: application/json
- Transform a raw transcript into structured documents like meeting minutes, sales summaries, action items, subtitles, and more.
- Parameters:
  - `model` (string, required): Always `valsea-format`
  - `transcript` (string, required): The transcript to format
  - `output_type` (string, required): One of meeting_minutes, sales_summary, service_log, subtitles, email_summary, action_items, key_quotes, interview_notes
  - `response_format` (string, optional): `json` or `verbose_json`. Default: `json`
  - `semantic_tags` (array, optional): Array of `{ tag, phrase, meaning }` objects
  - `stream` (boolean, optional): Enable streaming response

### POST /v1/sentiment — Analyze Sentiment

- [Full documentation](https://valsea.ai/docs/api/sentiment)
- Content-Type: application/json
- Analyze the overall sentiment and emotional tone of a transcript.
- Parameters:
  - `model` (string, required): Always `valsea-sentiment`
  - `transcript` (string, required): The transcript to analyze
  - `response_format` (string, optional): `json` or `verbose_json`. Default: `json`
  - `semantic_tags` (array, optional): Array of `{ tag, phrase, meaning }` objects
- Response (json): `{ "sentiment": "positive"|"neutral"|"negative", "confidence": 0.0-1.0 }`
- Response (verbose_json): `{ "sentiment", "confidence", "reasoning" }`

## Live Transcription (WebSocket)

- [Full documentation](https://valsea.ai/docs/realtime)
- Endpoint: `wss://api.valsea.ai/v1/realtime`
- Auth: Pass `Authorization: Bearer YOUR_API_KEY` or `X-API-Key: YOUR_API_KEY` as WebSocket headers
- Paid rate-limit bypass: send `X-Bypass-Rate-Limit: true` on the WebSocket upgrade or query `bypass_rate_limit=true` / `bypassRateLimit=true`. This skips only the per-organization connection rate-limit check and bills the RTT session at 2x normal realtime credits. `session.created` includes `rateLimitBypass: true` and `billingMultiplier: 2` when active.
- Speaker diarization: include `diarize: true` in `session.start` to add speaker-labeled `words` and `utterances` to `transcript.final`. `diarization_min_speakers` and `diarization_max_speakers` are optional and default to 2 and 6. Diarization bills at 2x; bypass plus diarization bills at 4x.
- Audio format: Raw PCM 16-bit, 16kHz, mono, sent as base64

### Client messages:
- `session.start`: Initialize session with `{ type: "session.start", model: "valsea-rtt", language: "english", enable_correction: true, hint_text: "", target_language: "malay", diarize: true, diarization_min_speakers: 2, diarization_max_speakers: 6 }`. `language` is optional and defaults to `auto` (code-switch-aware auto-detection); set a specific language code to pin the input language. `target_language` is optional; omit it for transcription only, or set it to translate final transcript text.
- `audio.append`: Send audio chunk `{ type: "audio.append", audio: "BASE64_PCM16_DATA" }`
- `audio.commit`: Signal end of speech segment `{ type: "audio.commit" }`. This is important for diarized sessions because speaker metadata is emitted on final committed segments.
- `session.stop`: End session gracefully `{ type: "session.stop" }`

### Server messages:
- `session.created`: Connection established with `sessionId` and `supported_models`. May include `rateLimitBypass: true` and `billingMultiplier`.
- `session.ready`: Engine ready for audio
- `transcript.partial`: Intermediate mutable result `{ text, isFinal: false, timestampMs }`
- `transcript.final`: Stable committed segment `{ text, rawText, isFinal: true, timestampMs, corrections }`. If `diarize` is enabled, the payload also includes `words` and `utterances` with zero-based `speaker` labels. If `target_language` was set and differs from the input language, `text` is translated and the payload may include `translated`, `sourceLanguage`, and `targetLanguage`.
- `error`: Error event `{ code, message }`

### Transcript semantics:
- Keep partial text in temporary UI state only (it may change).
- Persist only final segments to transcript history/storage.
- Clear the current partial once a final event is received.

## Realtime Text to Speech (WebSocket)

- [Full documentation](https://valsea.ai/docs/realtime-tts)
- Endpoint: `wss://api.valsea.ai/v1/realtime/tts`
- Auth: Pass `Authorization: Bearer YOUR_API_KEY`, `X-API-Key: YOUR_API_KEY`, or query `api_key=YOUR_API_KEY`
- Client messages: `session.start`, `speech.create`, `session.stop`
- Server messages: `session.created`, `session.ready`, `speech.started`, binary audio chunks, `speech.finished`, `error`
- Voices: `valsea-neutral`, `valsea-male`, `valsea-female`

## Available Models

- `valsea-transcribe`: Audio-to-text transcription with accent-aware models
- `valsea-tts`: Text-to-speech with stable Valsea voice aliases
- `valsea-translate`: Text translation between 50+ languages
- `valsea-annotate`: Text annotation with semantic tags and corrections
- `valsea-clarify`: Transform colloquial/noisy text into clear standard text
- `valsea-convert`: Convert annotated text into clean readable output
- `valsea-format`: Format transcripts into meeting minutes, summaries, etc.
- `valsea-sentiment`: Sentiment and emotional tone detection
- `valsea-rtt`: Real-time transcription via WebSocket

## Supported Languages (Transcription)

arabic, arabic-algeria, arabic-bahrain, arabic-egypt, arabic-israel, arabic-jordan, arabic-kuwait, arabic-lebanon, arabic-mauritania, arabic-morocco, arabic-oman, arabic-palestine, arabic-qatar, arabic-saudi, arabic-syria, arabic-tunisia, arabic-uae, arabic-yemen, bengali-bd, bengali-in, cantonese, chinese, chinese-simplified, chinese-traditional, english, english-au, english-gb, english-in, english-philippines, english-us, french, french-ca, portuguese, portuguese-br, spanish, spanish-es, spanish-mexico, spanish-us, swahili, swahili-ke, afrikaans, akan, albanian, amharic, armenian, assamese, asturian, azerbaijani, basque, bemba, bulgarian, catalan, croatian, czech, danish, dutch, estonian, filipino, finnish, fulani, ga, galician, georgian, german, greek, gujarati, hausa, hebrew, hindi, hungarian, icelandic, igbo, indonesian, italian, japanese, javanese, kannada, kazakh, khmer, kinyarwanda, korean, kurdish, kyrgyz, lao, latvian, lithuanian, luxembourgish, luganda, macedonian, malay, malayalam, maltese, maori, marathi, mongolian, nepali, northern-sotho, norwegian, nyankole, odia, oromo, oriya, persian, pidgin, polish, punjabi, romanian, russian, serbian, shona, sinhala, singlish, slovak, slovenian, sotho, swedish, tamil, telugu, thai, tswana, twi, turkish, ukrainian, uzbek, vietnamese, welsh, wolof, xhosa, yoruba, zulu

## Errors

All endpoints return these standard error codes:
- 401: Missing or invalid API key
- 402: Insufficient credits
- 413: Audio file too large or too long (transcription only — max 10 MB, max 1 hour)

## Optional

- [Dashboard](https://valsea.ai/dashboard): Manage API keys, view analytics, test endpoints in the interactive playground
- [API Playground](https://valsea.ai/dashboard/playground): Interactive playground to test all endpoints with your API key