Text & Audio API: Translation and transcription service

What is the Text & Audio API?

The Text and Audio API is a stateless, content-agnostic translation and transcription service. You supply input (text or audio), specify the input language, the target language, and the output format you want back (text or audio). If the language pair is supported, the API returns the translated result. The service does not interpret what you send, there is no agricultural model, no follow-up logic, and no memory between calls.

Two flows are supported: text → text or audio (submit a string, receive translation as text or synthesised speech), and audio → text or audio (submit an audio file, receive transcript optionally translated and synthesised back to speech).

Authentication and scopes

All endpoints require a valid API key. Use user keys only for creating text translation requests. Use a server key for audio uploads, locale discovery, and job polling.

X-Api-Key: YOUR_API_KEY

# Bearer style is also accepted
Authorization: Bearer YOUR_API_KEY

Text and audio operations use separate scopes, allowing you to grant minimal permissions to each integration:

Synchronous text translation

POST /api/v1/text translates a text string and optionally synthesises it to audio in a single synchronous call. Use this for short strings where low latency matters.

curl -X POST "https://api.fildraai.com/api/v1/text" \
  -H "X-Api-Key: YOUR_USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, how are you today?",
    "lang": "sw",
    "output": "text",
    "source_lang": "en"
  }'

{
  "ok": true,
  "input_modality": "text",
  "output_modality": "text",
  "source_lang": "en",
  "source_detection": "langdetect",
  "target_lang": "sw",
  "target_display": "Swahili",
  "translation_used": true,
  "translation_backend": "bedrock",
  "text": "Habari, habari yako leo?",
  "audio_url": null,
  "audio_format": null,
  "audio_duration_seconds": null,
  "latency_ms": 1090.5
}

The response includes translation_used (whether translation was applied), text (the output string), and, when output is "audio", an audio_url link and audio_format.

Asynchronous audio jobs

Audio processing, transcription and synthesis, is handled asynchronously via a job queue. This allows large audio files to be processed in the background without blocking your application.

curl -X POST "https://api.fildraai.com/api/v1/audio" \
  -H "X-Api-Key: YOUR_SERVER_API_KEY" \
  -F "[email protected]" \
  -F "lang=sw" \
  -F "output=text" \
  -F "source_lang=auto"

import requests

url = "https://api.fildraai.com/api/v1/audio"
headers = {"X-Api-Key": "YOUR_SERVER_API_KEY"}

# `files` triggers multipart/form-data automatically.
with open("/absolute/path/to/recording.wav", "rb") as fh:
    response = requests.post(
        url,
        headers=headers,
        data={"lang": "sw", "output": "text", "source_lang": "auto"},
        files={"file": ("recording.wav", fh, "audio/wav")},
        timeout=60,
    )

response.raise_for_status()
job = response.json()
print("job_id:", job["job_id"])

# Then poll /api/v1/audio/{job_id} until status is "DONE".

// Works in browsers and Node 18+ (built-in fetch + FormData).
// `audioFile` is a File or Blob, from <input type="file"> or recorded audio.
async function uploadAudio(audioFile) {
  const form = new FormData();
  form.append('file', audioFile, audioFile.name || 'recording.wav');
  form.append('lang', 'sw');
  form.append('output', 'text');
  form.append('source_lang', 'auto');

  const response = await fetch('https://api.fildraai.com/api/v1/audio', {
    method: 'POST',
    headers: { 'X-Api-Key': 'YOUR_SERVER_API_KEY' },
    // IMPORTANT: do NOT set Content-Type, the browser sets the
    // correct multipart boundary automatically when you pass FormData.
    body: form,
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const job = await response.json();
  return job.job_id; // poll /api/v1/audio/{job_id} for completion
}

Polling job status

After submitting an audio or text job, poll the status endpoint from your backend until the job reaches a terminal state. The current production policy requires a server-audience key for status polling.

Example responses

Submitting a job returns 202 with a job_id. Polling GET /api/v1/audio/{job_id} returns 200 at every stage; read status to know where the job is.

# 1. Submit response (HTTP 202)
{ "ok": true, "status": "QUEUED", "job_id": "53aeb56cfb8f4c1fb5c2d64198f2f9be" }

# 2. Completed job (HTTP 200, status DONE)
{
  "status": "DONE",
  "job_id": "53aeb56cfb8f4c1fb5c2d64198f2f9be",
  "input_modality": "audio",
  "output_modality": "text",
  "source_lang": "en",
  "target_lang": "sw",
  "transcript_text": "Good morning, the maize in the lower field is turning yellow.",
  "text": "Habari za asubuhi, mahindi katika shambani la chini yanabadilika kuwa manjano.",
  "audio_url": null,
  "audio_duration_seconds": null,
  "error_code": null,
  "error_message": null
}

# 3. Failed job (HTTP 200, status FAILED)
{
  "status": "FAILED",
  "job_id": "…",
  "error_code": "adapter_job_failed",
  "error_message": "Audio exceeds the maximum duration for your plan."
}

When you requested output: "audio", a DONE job also carries audio_url, audio_format, and audio_duration_seconds. Note: the synthesized audio_url is not directly downloadable yet (see the warning above); prefer text output until that is fixed.

Supported languages

Use GET /api/v1/locales to retrieve the current list of supported languages at runtime. Each locale entry includes whether audio synthesis (audio_supported) is available, since not all text locales have voice synthesis.

Showing the built-in baseline (live list unavailable right now). 14 languages translate text; 14 also speak back with output: "audio".

Languages marked No for audio translate text but return 400 if you request output: "audio".

Output modes

The output parameter controls what the API returns. Both text and audio endpoints support the same two modes:

Error codes

Common error responses from the Text and Audio API: