Translation - KI-AVA API

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://api.kiava.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:

json

{
  "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://api.kiava.lesan.ai/translate/YOUR_JOB_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Example response:

json

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

Statuses: PENDING, PROCESSING, COMPLETED, PARTIAL, FAILED. Terminal states are COMPLETED, PARTIAL, and 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://api.kiava.lesan.ai/translate/YOUR_JOB_ID/results" \
  -H "X-API-Key: YOUR_API_KEY"

Example response:

json

{
  "job_id": "job_789abc",
  "summary": {
    "status": "COMPLETED",
    "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/kiava-api/results/batch_001/transcript_en.txt?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Signature=...",
      "target_language": "en",
      "status": "COMPLETED"
    }
  ]
}

Each target_uri is a V4-signed URL that expires after SIGNED_URL_EXPIRATION seconds (default 24 h). Fetch it directly with no auth header.

4. Delete job (optional)

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

bash

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

Transcript JSON support

The same endpoint accepts KI-AVA transcript JSON files as input. Pass the signedtranscript_url from a completed transcription job directly as a urisentry. The API translates each segment's text while preserving timestamps, speaker labels, segment types, and duration. The output JSON has the same shape as the input with itslanguage field updated to the target.

curl -X POST "https://api.kiava.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/kiava-api/transcripts/JOB_ID_0001.json?X-Goog-Algorithm=..."]
    },
    "output_config": {
      "destination_uri": "https://storage.googleapis.com/bucket/results/batch_002/"
    }
  }'

Request reference

Full POST /translate request body:

Field	Type	Required	Notes
`source_language`	string	yes	One of `am`, `en`, `ti`.
`target_languages`	string[]	yes	1–5 codes. Must differ from `source_language`.
`input_config.type`	string	yes	Only `"BLOB_STORAGE"` is supported today.
`input_config.uris`	string[]	yes	1–100 HTTPS URIs. Plain-text (`.txt`) or KI-AVA transcript JSON. Signed URLs are fine.
`output_config.destination_uri`	string	yes	Cloud storage URI prefix. Output file names are derived from the source.
`callback_url`	string	no	Optional webhook invoked with the final job payload once the job leaves `PROCESSING`.

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