Lesan AI

Getting Started

Get started with Lesan AI services in minutes.

View as Markdown

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 returns 200. 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 with multipart/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.

ModeBest forHow you get the result
syncTrying it out; short clips that finish within 5 minutesReturned inline in the same request — no extra calls
async + webhooks (recommended for production)Production workloads, long audio, high volumeLesan POSTs the result to your endpoint when the job completes — no blocking, no polling
async + pollingProduction when you cannot receive inbound webhooksYou 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