API Reference

Base URL: https://api.mayaresaerch.com

All requests must include an Authorization: Bearer YOUR_API_KEY header. API keys are issued at registration and can be rotated from the dashboard.

Authentication

Pass your API key in the Authorization header on every request:

Authorization: Bearer myr_live_xxxxxxxxxxxxxxxxxxxxxxxx

Keys are prefixed myr_live_ for production and myr_test_ for sandbox. Test keys return synthesized audio with a short watermark tone at the beginning.

POST /v1/synthesize

Synthesize text to audio and return the complete audio file in a single response. Best for short inputs where buffering the full file is acceptable. For real-time or user-facing applications, prefer the streaming endpoint.

Request body

Example request

POST /v1/synthesize
Content-Type: application/json
Authorization: Bearer myr_live_xxxx

{
  "text": "नमस्ते, आज का मौसम अच्छा है।",
  "language": "hi-IN",
  "format": "mp3"
}

Response

Returns binary audio data with content type matching the requested format (audio/mpeg, audio/pcm, or audio/ogg).

Response headers include:

Content-Type: audio/mpeg
X-Maya-Characters: 23
X-Maya-Language: hi-IN
X-Maya-Voice: hi-female-1
X-Maya-Latency-Ms: 142

POST /v1/synthesize/stream

Synthesize text and stream audio chunks as they are generated. The server returns chunks progressively, allowing clients to begin playback before the full synthesis is complete. First-byte latency is typically under 180ms for inputs up to 500 characters.

Request body

Identical to POST /v1/synthesize with one additional parameter:

Example request

POST /v1/synthesize/stream
Content-Type: application/json
Authorization: Bearer myr_live_xxxx

{
  "text": "مرحبا بكم في تطبيقنا الجديد.",
  "language": "ar-EG",
  "format": "pcm_16"
}

Streaming response

The response uses HTTP chunked transfer encoding. Audio bytes are sent as soon as synthesis chunks are ready. Clients should open a connection and pipe the response bytes directly to an audio player.

import maya_tts

client = maya_tts.Client("myr_live_xxxx")

with client.synthesize_stream(
    text="مرحبا بكم في تطبيقنا الجديد.",
    language="ar-EG"
) as stream:
    for chunk in stream:
        audio_player.write(chunk)

GET /v1/languages

Returns the list of supported languages and their available voices.

No request body

This endpoint takes no body. Authentication header required.

Example response

{
  "languages": [
    {
      "code": "hi-IN",
      "name": "Hindi",
      "native_name": "हिन्दी",
      "script": "Devanagari",
      "status": "ga",
      "voice_count": 4
    },
    {
      "code": "ar-EG",
      "name": "Arabic (Egyptian)",
      "native_name": "عربي (مصري)",
      "script": "Arabic",
      "status": "ga",
      "voice_count": 2
    }
  ]
}

GET /v1/voices

Returns all available voices with metadata. Filter by language using the language query parameter.

Query parameters

Example response

{
  "voices": [
    {
      "id": "hi-female-1",
      "language": "hi-IN",
      "gender": "female",
      "style": "conversational",
      "is_default": true
    }
  ]
}

Error codes

The API returns standard HTTP status codes. All error responses include a JSON body with a code and message field.

Rate limits

Rate limits are applied per API key. Limits reset on a rolling 60-second window.

When a rate limit is exceeded, the API returns 429 with a Retry-After header indicating seconds until the limit resets. Implement exponential backoff in any production integration.