# Mutarjim Translation



Overview [#overview]

**Mutarjim** (مترجم) translates English text into Arabic. Send plain English text of up to 30,000 characters and receive the Arabic translation in a single response.

***

Endpoint [#endpoint]

```
POST /v1/translations
```

Requires an [API Key](/docs/api-keys) passed via the `x-api-key` header or `Authorization: Bearer <YOUR_API_KEY>`.

Request Body [#request-body]

| Field   | Type     | Required | Description                                                                  |
| ------- | -------- | -------- | ---------------------------------------------------------------------------- |
| `model` | `string` | Yes      | The translation model to use. See [Models](/docs/models/translation#models). |
| `text`  | `string` | Yes      | The English text to translate, up to 30,000 characters.                      |

HTML tags and control characters are removed before translation. Paragraphs separated by a blank line stay separated in the translation; single line breaks are not kept.

Example Request [#example-request]

```bash
curl -X POST https://api.kawn.ai/v1/translations \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mutarjim/v1",
    "text": "Knowledge is a light that guides people."
  }'
```

Response [#response]

| Field                   | Type     | Description                                 |
| ----------------------- | -------- | ------------------------------------------- |
| `translation`           | `string` | The Arabic translation.                     |
| `model`                 | `string` | The model that produced the translation.    |
| `usage.charactersCount` | `number` | The billed characters, after text cleaning. |
| `creditsConsumed`       | `number` | The credits deducted for this request.      |

***

Models [#models]

| Model         | Direction         | Price                  |
| ------------- | ----------------- | ---------------------- |
| `mutarjim/v1` | English to Arabic | 1 credit per character |

Every character of the cleaned text is billed, including spaces and punctuation. A failed request is not billed.

***

Errors [#errors]

| Status | Meaning                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------- |
| `400`  | The request is invalid, the text exceeds 30,000 characters, or nothing is left after cleaning. |
| `401`  | The API key is missing or invalid.                                                             |
| `403`  | The organization's credit balance is not positive.                                             |
| `500`  | The translation failed. No credits were deducted.                                              |
