> ## Documentation Index > Fetch the complete documentation index at: https://docs.sunbird.ai/llms.txt > Use this file to discover all available pages before exploring further. # Translate > Translate text between supported languages using the Sunflower model. Languages are accepted as ISO 639-3 codes (e.g. ``lug``) or full names (e.g. ``Luganda``), case-insensitively. ``source_language`` is optional — when omitted, Sunflower infers the source language from the text. Translation works between any pair of supported languages. Supported languages: Acholi (ach), Alur (alz), Aringa (luc), Ateso (teo), Bari (bfa), English (eng), Jopadhola (adh), Kakwa (keo), Karamojong (kdj), Kinyarwanda (kin), Kumam (kdi), Kupsabiny (kpz), Kwamba (rwm), Lango (laj), Lubwisi (tlj), Luganda (lug), Lugbara (lgg), Lugungu (rub), Lugwere (gwr), Lumasaba (myx), Lunyole (nuj), Lusoga (xog), Ma'di (mhi), Pokot (pok), Rukiga (cgg), Rukonjo (koo), Runyankole (nyn), Runyoro (nyo), Ruruuli (ruc), Rutooro (ttj), Samia (lsm), Swahili (swa). Example: Request body: { "source_language": "eng", "target_language": "lug", "text": "Hello, how are you?" } Response: { "id": "trans-1a2b3c...", "status": "COMPLETED", "output": { "translated_text": "Oli otya?", "source_language": "eng", "target_language": "lug" } } Raises: BadRequestError: Unsupported language, or source == target. ServiceUnavailableError: Model loading or inference timeout. ExternalServiceError: Empty model output or unexpected failure. ## OpenAPI ````yaml api-reference/openapi.json POST /tasks/translate openapi: 3.1.0 info: title: Sunbird AI API description: > Welcome to the Sunbird AI API documentation. The Sunbird AI API provides access to Sunbird's language models and AI services for Ugandan languages. ## Supported Languages **English**, **Acholi**, **Ateso**, **Luganda**, **Lugbara**, **Runyankole**, **Swahili** and **20+** more Ugandan languages supported via sunflower. ## Getting Started You can checkout the [usage guide](https://salt.sunbird.ai/API/) for a full tutorial. For quickstart tutorials, visit our [GitHub repository](https://github.com/SunbirdAI/sunbird-ai-api/blob/main/docs/tutorial.md) ### Authentication #### Signing Up If you don't already have an account, use the `/auth/register` endpoint to create one. #### Getting an Access Token Authentication is done via a Bearer token. Use the `/auth/token` endpoint to get your access token. This token lasts for 7 days. Use the `Authorize` button below to login and access the protected endpoints. ## API Endpoints ### Translation - **`POST /tasks/translate`** - Translate text between 32 Ugandan and East African languages using the Sunflower model. Languages are accepted as ISO codes (`lug`) or full names (`Luganda`); `source_language` is optional (auto-detected when omitted). Translation works between any pair of supported languages. ### Language Detection - **`POST /tasks/language_id`** - Auto-detect the language of text input (supports Acholi, Ateso, English, Luganda, Lugbara, Runyankole) ### Speech-to-Text (STT) - **`POST /tasks/audio/transcriptions`** - STT endpoint (OpenAI-style). - Accepts an uploaded audio file (`audio`) or a GCS object (`gcs_blob_name`). - `platform`: `modal` (default, Whisper large-v3) or `runpod`. - RunPod options: `adapter` (language adapter), `whisper`, `recognise_speakers` (diarization), and the `org` organization workflow. - `language`: 3-letter code (e.g. `eng`, `lug`) or full name; improves accuracy. Supports WAV, MP3, OGG, M4A, and more. Auto-detects when omitted. - **Deprecated** → use `POST /tasks/audio/transcriptions`: - `POST /tasks/stt`, `POST /tasks/stt_from_gcs`, `POST /tasks/org/stt`, `POST /tasks/modal/stt` ### Text-to-Speech (TTS) - **`POST /tasks/audio/speech`** - single-synthesis endpoint. - `model`: `orpheus-3b-tts` (default) or `spark-tts`; `platform`: `modal` or `runpod`. - `voice`: speaker tag/name. `response_mode`: `url` (default), `stream`, or `both` (`stream`/`both` require `spark-tts` on `modal`). - Orpheus tuning: `language`, `temperature`, `top_p`, `repetition_penalty`, `max_tokens`, `seed`. Returns a signed GCP Storage URL. - **`POST /tasks/audio/speech/batch`** - Batch synthesis (orpheus-3b-tts only), 1-128 items. - **`GET /tasks/voice/speakers`** - List voices for a `model` (optional orpheus `language`). - **orpheus-3b-tts** covers 20 African languages: Acholi (`ach`), Afrikaans (`afr`), English (`eng`), Ewe (`ewe`), Fulah (`ful`), Hausa (`hau`), Igbo (`ibo`), Kikuyu (`kik`), Kinyarwanda (`kin`), Lugbara (`lgg`), Lingala (`lin`), Luganda (`lug`), Luo (`luo`), Runyankole (`nyn`), Sesotho (`sot`), Swahili (`swa`), Ateso (`teo`), Setswana (`tsn`), Xhosa (`xho`), Yoruba (`yor`). A few (`lgg`, `sot`, `tsn`) are in the training mix but expose no individual voice IDs yet. Full per-speaker catalog: see the [tutorial](https://github.com/SunbirdAI/sunbird-ai-api/blob/main/docs/tutorial.md) or call `GET /tasks/voice/speakers`. - **`GET /tasks/audio/speech/url`** - Refresh an expired signed URL for a stored audio object. - **Deprecated** → superseded by the new endpoints above: - `POST /tasks/modal/tts`, `POST /tasks/runpod/tts`, `POST /tasks/modal/orpheus/tts` → `POST /tasks/audio/speech` - `POST /tasks/modal/tts/stream` → `/tasks/audio/speech` (`response_mode=stream`) - `POST /tasks/modal/tts/stream-with-url` → `/tasks/audio/speech` (`response_mode=both`) - `POST /tasks/modal/orpheus/tts/batch` → `POST /tasks/audio/speech/batch` - `GET /tasks/modal/tts/speakers`, `GET /tasks/modal/orpheus/speakers`, `GET /tasks/modal/orpheus/speakers/{language}` → `GET /tasks/voice/speakers` - `GET /tasks/modal/tts/refresh-url` → `GET /tasks/audio/speech/url` ### Inference (Sunflower Chat) - **`POST /tasks/chat/completions`** - OpenAI-compatible chat completions (Sunflower model). Supports single instructions, multi-turn conversations, and SSE streaming (`stream: true`). Use model `Sunbird/Sunflower-14B`. - **Deprecated** → superseded by the unified endpoint above: - `POST /tasks/sunflower_inference` → `POST /tasks/chat/completions` - `POST /tasks/sunflower_simple` → `POST /tasks/chat/completions` (send the instruction as a single user message) ### File Upload - **`POST /tasks/generate-upload-url`** - Generate signed URLs for direct client uploads to GCP Storage - Supports audio files, images, and other content types - Includes path traversal protection and input validation - Returns temporary signed URL valid for 30 minutes ### WhatsApp Integration (Webhooks) - **`POST /tasks/webhook`** - Handle incoming WhatsApp Business API messages - **`GET /tasks/webhook`** - Verify webhook endpoint ownership for WhatsApp ### Legacy Endpoints - **`POST /tasks/summarise`** - *(Deprecated)* Anonymized text summarization (use Sunflower inference instead) ## Rate Limiting API endpoints are rate-limited to ensure fair usage. Authentication is required for most endpoints. version: 0.1.0 servers: - url: https://api.sunbird.ai security: [] tags: - name: Authentication Endpoints description: >- Operations for authentication, including user registration and login. Get access tokens to use protected endpoints. - name: Speech-to-Text description: >- Convert speech audio to text. The /tasks/audio/transcriptions endpoint accepts an uploaded file or a GCS object, routes to the Modal or RunPod backend, and supports optional speaker diarization for Acholi, Ateso, English, Luganda, Lugbara, and Runyankole. - name: Text-to-Speech description: >- Synthesize speech from text. Endpoints for single (/tasks/audio/speech) and batch (/tasks/audio/speech/batch) synthesis across the orpheus-3b-tts and spark-tts models, plus voice listing (/tasks/voice/speakers) and signed-URL refresh (/tasks/audio/speech/url). Returns signed GCS audio URLs. - name: Translation description: >- Translate text using the Sunflower model. Supports 32 languages (e.g. Luganda, Acholi, Ateso, Lugbara, Runyankole, Swahili, Kinyarwanda) accepted as ISO codes or full names; source language is optional and translation works between any supported pair. - name: Language description: >- Language identification and detection. Automatically detect the language of text input from supported languages. - name: Chat description: >- OpenAI-compatible chat completions powered by the Sunflower model. Supports single instructions, multi-turn conversations, and SSE streaming. - name: Upload description: >- File upload utilities. Generate signed URLs for direct client uploads to GCP Storage with security validation. - name: Webhooks description: >- WhatsApp Business API webhook integration. Handle incoming messages and verify webhook endpoints for WhatsApp chatbot functionality. paths: /tasks/translate: post: tags: - Translation summary: Translate description: >- Translate text between supported languages using the Sunflower model. Languages are accepted as ISO 639-3 codes (e.g. ``lug``) or full names (e.g. ``Luganda``), case-insensitively. ``source_language`` is optional — when omitted, Sunflower infers the source language from the text. Translation works between any pair of supported languages. Supported languages: Acholi (ach), Alur (alz), Aringa (luc), Ateso (teo), Bari (bfa), English (eng), Jopadhola (adh), Kakwa (keo), Karamojong (kdj), Kinyarwanda (kin), Kumam (kdi), Kupsabiny (kpz), Kwamba (rwm), Lango (laj), Lubwisi (tlj), Luganda (lug), Lugbara (lgg), Lugungu (rub), Lugwere (gwr), Lumasaba (myx), Lunyole (nuj), Lusoga (xog), Ma'di (mhi), Pokot (pok), Rukiga (cgg), Rukonjo (koo), Runyankole (nyn), Runyoro (nyo), Ruruuli (ruc), Rutooro (ttj), Samia (lsm), Swahili (swa). Example: Request body: { "source_language": "eng", "target_language": "lug", "text": "Hello, how are you?" } Response: { "id": "trans-1a2b3c...", "status": "COMPLETED", "output": { "translated_text": "Oli otya?", "source_language": "eng", "target_language": "lug" } } Raises: BadRequestError: Unsupported language, or source == target. ServiceUnavailableError: Model loading or inference timeout. ExternalServiceError: Empty model output or unexpected failure. operationId: translate_tasks_translate_post requestBody: content: application/json: schema: $ref: '#/components/schemas/SunflowerTranslationRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/WorkerTranslationResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - OAuth2PasswordBearer: [] components: schemas: SunflowerTranslationRequest: properties: source_language: anyOf: - type: string - type: 'null' title: Source Language description: >- Source language ISO code or full name (optional; auto-detected when omitted) target_language: type: string title: Target Language description: Target language ISO code or full name text: type: string minLength: 1 title: Text description: The text to translate type: object required: - target_language - text title: SunflowerTranslationRequest description: |- Request model for Sunflower-backed text translation. Languages may be given as ISO 639-3 codes (e.g. ``lug``) or full names (e.g. ``Luganda``). This schema stores the raw value as-is; the router normalizes case and validates membership in the supported language set via ``resolve_language`` (returning a 400 with the supported list for anything unsupported). Attributes: source_language: Optional source language; auto-detected when omitted. target_language: The target language (code or full name). text: The text to translate (min 1 character, whitespace stripped). WorkerTranslationResponse: properties: delayTime: anyOf: - type: integer - type: 'null' title: Delaytime description: Time spent waiting in queue (ms) executionTime: anyOf: - type: integer - type: 'null' title: Executiontime description: Time spent executing the job (ms) id: anyOf: - type: string - type: 'null' title: Id description: Unique job identifier output: anyOf: - $ref: '#/components/schemas/WorkerTranslationOutput' - type: 'null' description: The translation output data status: anyOf: - type: string - type: 'null' title: Status description: Job status (e.g., COMPLETED, FAILED) workerId: anyOf: - type: string - type: 'null' title: Workerid description: Identifier of the worker that processed the job additionalProperties: true type: object title: WorkerTranslationResponse description: |- Response model for translation worker API calls. This model wraps the translation worker output with metadata about the job execution. Attributes: delayTime: Time spent waiting in queue (ms). executionTime: Time spent executing the job (ms). id: Unique job identifier. output: The translation output data. status: Job status (e.g., "COMPLETED", "FAILED"). workerId: Identifier of the worker that processed the job. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError WorkerTranslationOutput: properties: text: anyOf: - type: string - type: 'null' title: Text description: Translated text output translated_text: anyOf: - type: string - type: 'null' title: Translated Text description: Alternative translated text field source_language: anyOf: - type: string - type: 'null' title: Source Language description: Source language code if returned target_language: anyOf: - type: string - type: 'null' title: Target Language description: Target language code if returned Error: anyOf: - type: string - type: 'null' title: Error description: Error message if translation failed additionalProperties: true type: object title: WorkerTranslationOutput description: |- Output model for translation worker results. This model represents the output from the RunPod translation worker. It handles various response formats from the worker. Attributes: text: The translated text (some workers use this field). translated_text: The translated text (alternative field name). source_language: The source language code if returned. target_language: The target language code if returned. error: Error message if translation failed. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: OAuth2PasswordBearer: type: oauth2 flows: password: scopes: {} tokenUrl: /auth/token ````