The translation API processes text files asynchronously. Submit source file URIs and target languages, then poll for progress and retrieve translated output. Supports plain text and KI-AVA transcript JSON files.

Supported languages

• am — Amharic
• en — English
• ti — Tigrinya

Source and target languages must differ. A single job can translate to multiple target languages.

Workflow

• Submit a translation job with source file URIs and target languages
• Receive a job_id immediately
• Poll the status endpoint to track progress
• Retrieve results with per-file output URIs
• Delete the job when no longer needed (optional)

1. Submit a translation job

POST to /translate with source file URIs, source language, target languages, and an output destination.

curl -X POST "https://kiava-api.lesan.ai/translate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_language": "am",
    "target_languages": ["en"],
    "input_config": {
      "type": "BLOB_STORAGE",
      "uris": ["https://storage.googleapis.com/bucket/source/transcript.txt"]
    },
    "output_config": {
      "destination_uri": "https://storage.googleapis.com/bucket/results/batch_001/"
    }
  }'

Response:

{
  "job_id": "job_789abc",
  "status": "PENDING",
  "message": "Translation job submitted for 1 files to 1 languages."
}

2. Poll job status

GET /translate/{job_id} to check progress. A translation unit is one (file, target language) pair.

curl "https://kiava-api.lesan.ai/translate/YOUR_JOB_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Example response:

{
  "job_id": "job_789abc",
  "status": "RUNNING",
  "created_at": "2026-02-04T10:00:00Z",
  "progress": {
    "total_units": 2,
    "completed_units": 1,
    "failed_units": 0
  }
}

Statuses: PENDING, RUNNING, SUCCEEDED, PARTIAL_SUCCESS, FAILED.

3. Get results

GET /translate/{job_id}/results after the job completes. Returns a summary and per-file output URIs. Returns 409 if the job is still in progress.

curl "https://kiava-api.lesan.ai/translate/YOUR_JOB_ID/results" \
  -H "X-API-Key: YOUR_API_KEY"

Example response:

{
  "job_id": "job_789abc",
  "summary": {
    "status": "SUCCEEDED",
    "total_characters": 15400,
    "success_count": 1,
    "failure_count": 0
  },
  "outputs": [
    {
      "source_uri": "https://storage.googleapis.com/bucket/source/transcript.txt",
      "target_uri": "https://storage.googleapis.com/bucket/results/batch_001/transcript_en.txt",
      "target_language": "en",
      "status": "SUCCEEDED"
    }
  ]
}

4. Delete job (optional)

DELETE /translate/{job_id} removes the job metadata. Translated files already in cloud storage are not affected.

curl -X DELETE "https://kiava-api.lesan.ai/translate/YOUR_JOB_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Transcript JSON support

When the input is a KI-AVA transcript JSON file, the API translates each segment's text while preserving timestamps, speaker labels, segment types, and duration. The language field in the output is updated to the target language.

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