The KI-AVA Amharic API is a RESTful interface for transcribing audio files asynchronously, designed for use cases where real-time results are not required, such as transcribing the DW Amharic archive.

Authentication

All API endpoints require authentication via an API Key passed in the request header, using X-API-Key.

X-API-Key: YOUR_API_KEY

Workflow

The API follows a "job-based" pattern:

• Submit a request to create a transcription job with audio file URI(s)
• Receive a unique jobId immediately
• Processing happens in the background
• Poll the status endpoint to check progress
• Retrieve results when status is "Succeeded"

Quick Start Examples

1. Create a Basic Transcription Job

Let's see a sample request:

curl -X POST "https://kiava-api.lesan.ai/transcribe" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_urls": ["https://example.com/audio.mp3"],
    "language": "am"
  }'

This will return a json result with the following schema:

{
    "job_id": "923af241-6eeb-4672-991b-97955220fc69",
    "status": "pending",
    "message": "Batch transcription job submitted successfully for 1 files."
}

2. Check Job Status

To check the status of a job that's submitted successfully, we use the job_id to check the status as follows:

curl -X GET "https://kiava-api.lesan.ai/transcribe/{job_id}" \
  -H "X-API-Key: YOUR_API_KEY"

While processing the job, the system will respond with a status processing and return a json response:

{
  "job_id": "90310bc7-62a2-45c7-b92c-91fc5ccf3bcc",
  "status": "processing",
  "transcript_urls": null,
  "results": null,
  "error": null,
  "submitted_at": "2025-11-23T16:50:10.901572Z",
  "completed_at": null,
  "processing_time": null
}

When the job is complete and successful it will return status completed with a json response:

{
  "job_id": "90310bc7-62a2-45c7-b92c-91fc5ccf3bcc",
  "status": "completed",
  "transcript_urls": [
    "https://storage.googleapis.com/kiava-api/.../..._0001_transcript.json?X-Goog-Algorithm=..."
  ],
  "results": [
    {
      "original_url": "https://radiodownloaddw-a.akamaihd.net/Events/dwelle/dira/mp3/amh/E9437257_2.mp3",
      "status": "completed",
      "transcript_url": "https://storage.googleapis.com/kiava-api/...",
      "error": null,
      "processing_time": 35.735,
      "duration": 608.8098125,
      "num_segments": 30
    }
  ],
  "error": null,
  "submitted_at": "2025-11-23T16:50:10.901572Z",
  "completed_at": "2025-11-23T16:50:46.652621Z",
  "processing_time": 35.751
}

3. Get Transcription Results

We can find the urls containing transcriptions in the json output of the job status transcript_urls. These are signed URLs on a cloud storage that are valid for 15 minutes. To get the actual transcription, we download the json pointed to by the url. For example to download the transcript JSON of the first URL:

TRANSCRIPT_URL=$(curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://kiava-api.lesan.ai/transcribe/{job_id}" | jq -r '.transcript_urls[0]')
curl "$TRANSCRIPT_URL"

This will give us a json output such as the following. Some segments are omitted for brevity.

{
  "job_id": "90310bc7-62a2-45c7-b92c-91fc5ccf3bcc",
  "status": "COMPLETED",
  "duration": 608.81,
  "language": "am",
  "text": "",
  "segments": [
    {
      "id": 0,
      "start_time": "7.34",
      "end_time": "24.04",
      "type": "male",
      "text": "በጣም የተለመዱት የአፍ ምርሬት..."
    },
    {
      "id": 1,
      "start_time": "24.04",
      "end_time": "42.24",
      "type": "female",
      "text": "ጤና ይስጥልኝ የዝግጅታችን..."
    },
    ...
    {
      "id": 29,
      "start_time": "606.66",
      "end_time": "608.80",
      "type": "female",
      "text": "ሸዋ እየለገሰ ነኝ ሰላም ኑ።"
    }
  ]
}

Supported Features

• Multi-file processing: Submit multiple audio files in one job
• Language identification: Automatic detection between candidate locales
• Batch processing: Handle large volumes of audio files
• Batch translation: Translate text files between Amharic, English, and Tigrinya

Supported Audio Formats

• .aac, .flac, .m4a, .mp3, .mp4, .mkv, .wav, .webm, .3gpp
• Maximum file size: 1GB per file
• Files must be accessible via public or pre-signed URLs

Rate Limits

• 100 job submissions per hour per API key
• Maximum 10 concurrent jobs per API key
• Jobs expire after 48 hours by default (configurable up to 168 hours)

Translation

The KI-AVA API also provides batch translation of text files between Amharic, English, and Tigrinya via the Lesan MT engine. The workflow is similar to transcription: submit source file URIs, poll for progress, then retrieve translated output files.

For a complete walkthrough, see the Translation guide.

For full endpoint and schema details, see the API Reference.