Documentation

Documentation

Everything you need to integrate CallRolin's Urdu STT and English/Arabic/Urdu TTS API.

Getting started

CallRolin is a voice AI API for Urdu, Arabic, and English — text-to-speech (TTS) and speech-to-text (STT), built for Pakistan with data sovereignty by default. Three steps to your first request: create an account and sign in to the dashboard; generate an API key under Settings → API Keys; then make your first request to the TTS or STT endpoint below. All requests are made over HTTPS to https://www.callrolin.com. Responses are JSON, except audio endpoints, which return audio bytes or a stream.

Authentication

CallRolin uses API keys. Pass your key as a Bearer token in the Authorization header on every request. Generate and revoke keys from the dashboard. Your plan determines how many active keys you can hold — Starter 2, Business 10, Enterprise unlimited. Treat keys as secrets: never expose them in client-side code or commit them to source control. If a key is leaked, revoke it immediately and issue a new one.

http
Authorization: Bearer YOUR_API_KEY

Text-to-Speech

Convert text into natural speech in Urdu, Arabic, or English with POST /v1/audio/speech. First audio typically returns in under 150ms. Body parameters: text (required), voice (required — see Voices & Models), language — ur (Urdu), ar (Arabic), or en (English), and format — mp3 or wav.

bash
curl https://www.callrolin.com/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Assalam-o-alaikum, CallRolin mein khush aamdeed.",
    "voice": "VOICE_ID",
    "language": "ur",
    "format": "mp3"
  }' --output speech.mp3

Speech-to-Text

Transcribe audio into text with POST /v1/audio/transcriptions. Supports Urdu, Arabic, and English. Typical transcription latency is under 200ms, with a real-time factor of about 0.3× (roughly three times faster than real time). Business and Enterprise plans include word-level timestamps.

bash
curl https://www.callrolin.com/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "audio=@recording.wav" \
  -F "language=ur"

Streaming

TTS streaming — POST /v1/audio/speech/stream returns audio as it's generated, so playback can start before the full text is synthesized. STT streaming — audio is transcribed incrementally via chunking, so partial transcripts arrive while the speaker is still talking. [[ confirm the STT streaming endpoint and message format — not yet listed in the API Reference ]]

Voices & models

CallRolin currently offers 7 voices across Urdu, Arabic, and English. List the voices available to your account with GET /v1/voices. Custom voices (trained on your own consented recordings) are available to Enterprise customers — contact sales to get started.

bash
curl https://www.callrolin.com/v1/voices \
  -H "Authorization: Bearer YOUR_API_KEY"

Error handling

CallRolin uses standard HTTP status codes and returns a JSON error body. 400 — bad request, check your parameters. 401 — missing or invalid API key. 403 — not permitted on your plan. 404 — resource not found. 429 — rate limit or concurrency limit exceeded. 5xx — server error, retry with backoff.

json
{ "error": { "code": "invalid_request", "message": "Description of what went wrong." } }

Rate limits

Concurrency is capped per plan: Starter 3, Business 10, Enterprise 30+ concurrent requests. Exceeding your limit returns 429. Handle it by retrying with exponential backoff, and upgrade your plan if you consistently hit the ceiling. Request limits follow your plan package.