Lesan AI Documentation

Welcome to Lesan AI! This guide will help you get started with our API in just a few minutes.

Prerequisites

A Lesan AI account
An API key (see Authentication)
Basic knowledge of HTTP requests

Step 1 — Verify your API key

Before anything else, confirm your key works. Replace YOUR_API_KEY with your real key and run the request below. A valid key returns 200 OK with your (possibly empty) list of jobs; an invalid or missing key returns 401.

curl -i "https://asr.lesan.ai/v1/transcriptions?limit=1" \
  -H "Authorization: Bearer YOUR_API_KEY"


# 200 OK  → your key is valid
# 401     → {"error":{"code":"INVALID_API_KEY", ...}} — check the key

💡 Tip

The /health endpoint is public and does not check your key — it always returns200. Use an authenticated endpoint like GET /v1/transcriptions (above) to actually validate a key.

Step 2 — Your first transcription

Now transcribe audio in a single request. The block below uses a sample Amharic clip we host, so the only thing you need to change is your API key. Using mode: "sync" tells the API to wait and return the finished transcript in one response — no polling required.

curl "https://asr.lesan.ai/v1/transcriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://docs.lesan.ai/audio/am/01.wav",
    "language": "am",
    "mode": "sync"
  }'


# Returns the completed job, e.g.:
# {
#   "id": "...",
#   "status": "completed",
#   "language": "am",
#   "text": "ሰላም ለዓለም ...",
#   "duration_seconds": 6.4,
#   ...
# }

ℹ Note

Want to transcribe your own audio? Swap audio_url for any public URL, or upload a file directly withmultipart/form-data. See the ASR guide for upload methods and supported formats.

⚠ Warning

Sync mode waits up to 5 minutes (300 seconds) for the result, then returns 408 Request Timeout(the job keeps processing in the background, so you can still fetch it by its id). Use sync for short clips — for longer audio or high volume, use async mode.

Which mode should I use?

All three paths share the same transcription pipeline and produce the same result — they differ only in how you receive it. For production systems, prefer async with webhooks.

Mode	Best for	How you get the result
sync	Trying it out; short clips that finish within 5 minutes	Returned inline in the same request — no extra calls
async + webhooks (recommended for production)	Production workloads, long audio, high volume	Lesan POSTs the result to your endpoint when the job completes — no blocking, no polling
async + polling	Production when you cannot receive inbound webhooks	You poll GET /v1/transcriptions/{job_id} until status is completed

Production: async transcription

For production, submit jobs in async mode. The recommended pattern is to register a webhook and let Lesan notify your endpoint when each job completes — no open connections, no polling, and it scales cleanly to long audio and high volume.

💡 Tip

Recommended for production: async + webhooks. Reach for the polling loop below only when your client cannot receive inbound webhook calls (for example, a script behind a firewall).

If you cannot receive webhooks, poll the job until it completes. This example shows the complete polling workflow including error handling and getting the final result:

# Step 1: Submit transcription job
curl "https://asr.lesan.ai/v1/transcriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/audio.mp3",
    "language": "am",
    "mode": "async"
  }'


# Response: {"id": "job_123", "status": "queued", ...}


# Step 2: Check job status (poll until completed)
curl -X GET "https://asr.lesan.ai/v1/transcriptions/job_123" \
  -H "Authorization: Bearer YOUR_API_KEY"


# Response when complete:
# {
#   "id": "job_123",
#   "status": "completed",
#   "text": "ሰላም እንዴት ነህ ዛሬ",
#   "duration_seconds": 5.2,
#   "segments": [...]
# }

Understanding the Response

In async mode the API immediately returns a job object with a queued status that you poll until completion. (In sync mode, as in Step 2 above, the same fields come back already populated with completed status and the transcript text.)

json

{
  "id": "cc1f2764-89a8-4808-a843-993ca0e3fb3d",
  "object": "transcription",
  "status": "queued",
  "language": "am",
  "text": null,
  "segments": null,
  "speakers": null,
  "progress": null,
  "duration_seconds": null,
  "processing_time_seconds": null,
  "error": null,
  "metadata": null,
  "created_at": "2026-03-05T11:59:47.100183Z",
  "completed_at": null,
  "result_url": null,
  "audio_url": null,
  "url": "/v1/transcriptions/cc1f2764-89a8-4808-a843-993ca0e3fb3d"
}

id — Unique identifier for the transcription job
status — Job status: queued, processing, completed, or failed
text — Full transcription text (null until completed)
progress — Completion percentage (null until processing starts)
duration_seconds — Audio duration in seconds (null until completed)
url — Endpoint to poll for job status and results

Troubleshooting Common Issues

400 Bad Request on Status Check

If you get a 400 Bad Request error when checking job status, verify:

HTTP Method — Use GET not POST for status checks
Authorization Header — Ensure Authorization: Bearer YOUR_API_KEY is included
Valid Job ID — Use the exact ID returned from the submission response
URL Format — Correct format: /v1/transcriptions/{job_id}

Example Debugging Commands

bash

# Test with explicit GET method
curl -v -X GET "https://asr.lesan.ai/v1/transcriptions/cc1f2764-89a8-4808-a843-993ca0e3fb3d" \
  -H "Authorization: Bearer YOUR_API_KEY"


# Check if the job exists and get current status
curl -v "https://asr.lesan.ai/v1/transcriptions/cc1f2764-89a8-4808-a843-993ca0e3fb3d" \
  -H "Authorization: Bearer YOUR_API_KEY"


# List all your jobs to see if the job ID is valid
curl -v "https://asr.lesan.ai/v1/transcriptions" \
  -H "Authorization: Bearer YOUR_API_KEY"

Production Best Practices

When using Lesan AI in production, consider these important practices:

Handling Transcription Results

Store Results — Save transcriptions to your database with metadata (duration, language, confidence scores)
Process Segments — Use segment data for timestamps, speaker identification, and confidence analysis
Format Output — Convert raw text to your desired format (SRT, VTT, plain text, JSON)
Quality Control — Implement confidence thresholds and human review for low-confidence transcriptions

Error Handling & Reliability

Retry Logic — Implement exponential backoff for failed requests
Timeout Management — Set appropriate timeouts (5-10 minutes for most audio files)
Rate Limiting — Respect API rate limits and implement queueing for high volume
Monitoring — Track success rates, processing times, and error patterns

Security & Performance

API Key Management — Store API keys securely (environment variables, secret managers)
Input Validation — Validate audio URLs and file formats before submission
Async Processing — Use webhooks for long-running jobs instead of polling
Caching — Cache transcriptions for repeated audio content

Next Steps

Read the Authentication guide to learn about API key types and scopes
Explore the ASR guide for async processing, batch uploads, and job management
Try the MT guide to translate text between languages
Set up real-time streaming for live transcription
Configure webhooks to get notified when async jobs complete
Review error codes and rate limits for production readiness
Check out the API Reference for detailed endpoint documentation

Getting Started