Lesan AI

Getting Started

Learn how to get started with Lesan AI services in minutes.

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

Quick Start

First, verify your API key works by checking the health endpoint. Replace YOUR_API_KEY with your real key, or use an environment variable (e.g. $API_KEY in curl).

curl "https://asr.lesan.ai/health" \
  -H "Authorization: Bearer YOUR_API_KEY"

Your First Transcription

Let's transcribe an audio file from start to finish. This example shows the complete 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": "sync"
  }'


# 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

The API immediately returns a job object. For synchronous transcription, you'll get a queued status that needs to be polled until completion:

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