> ## Documentation Index
> Fetch the complete documentation index at: https://developers.deepl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Detect Language

> Detect the language of text using DeepL's language detection service

<Warning>
  **Beta Feature — Opt-in Required**

  The Detect Language API is currently in beta and requires explicit opt-in for your account. To request access, please [send a support request](https://support.deepl.com/hc/en-us/requests/new).
</Warning>

The Detect Language API allows you to identify the language of text content. This is a beta feature that requires special access permissions and is currently available only to select accounts.

## Best Practices

1. **Text Length**: Provide sufficient text for accurate detection. Very short texts may result in `insufficient_confidence` or `no_language_detected` status.

2. **Batch Processing**: You can detect multiple texts in a single request by providing an array of strings.

3. **Error Handling**: Check the `detection_status` field to understand the result. Only when `detection_status` is `success` will the `detected_language` field contain a valid language code.

4. **Rate Limiting**: Be mindful of API rate limits when making frequent requests.

## Feature Availability

This is a **beta feature** that requires:

* Account enrollment in the language detection beta program
* Compatible API key with appropriate permissions

Reach out to your DeepL contact to request access to the language detection API beta.

## Endpoint

```
POST /v3/detect/language
```

## Authentication

This endpoint requires authentication using the `DeepL-Auth-Key` header with a valid API key that has access to the language detection feature.

## Request Formats

<Tabs>
  <Tab title="JSON Request">
    ```bash theme={null}
    curl -X POST "https://api.deepl.com/v3/detect/language" \
      -H "Authorization: DeepL-Auth-Key YOUR_AUTH_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "text": [
          "Hello, how are you?",
          "Hola, ¿cómo estás?"
        ]
      }'
    ```
  </Tab>

  <Tab title="Form-Encoded Request">
    ```bash theme={null}
    curl -X POST "https://api.deepl.com/v3/detect/language" \
      -H "Authorization: DeepL-Auth-Key YOUR_AUTH_KEY" \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "text=Hello, how are you?" \
      -d "text=Hola, ¿cómo estás?"
    ```
  </Tab>

  <Tab title="HTTP Request">
    ```http theme={null}
    POST /v3/detect/language HTTP/1.1
    Host: api.deepl.com
    Authorization: DeepL-Auth-Key YOUR_AUTH_KEY
    Content-Type: application/json
    Content-Length: 84

    {
      "text": [
        "Hello, how are you?",
        "Hola, ¿cómo estás?"
      ]
    }
    ```
  </Tab>
</Tabs>

### Request Parameters

<ParamField body="text" type="string[]" required>
  List of text strings to detect languages for. Each string will be processed separately.

  The response detections are returned in the same order as they are requested. Each of the parameter values may contain multiple sentences. Up to 50 texts can sent in one request.
</ParamField>

## Response Format

<Tabs>
  <Tab title="200 Success">
    ```json theme={null}
    {
      "results": [
        {
          "detected_language": "en",
          "detection_status": "success"
        },
        {
          "detected_language": "es", 
          "detection_status": "success"
        }
      ]
    }
    ```

    Example responses for different detection statuses:

    ```json theme={null}
    {
      "results": [
        {
          "detected_language": "en",
          "detection_status": "success"
        },
        {
          "detection_status": "insufficient_confidence"
        },
        {
          "detection_status": "unsupported_language"
        },
        {
          "detection_status": "no_language_detected"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="400 Bad Request">
    ```json theme={null}
    {
      "message": "Missing parameter text."
    }
    ```

    This error occurs when:

    * The inputs in the request are malformed
  </Tab>

  <Tab title="403 Forbidden">
    ```json theme={null}
    {
      "message": "Forbidden"
    }
    ```

    This error occurs when:

    * The API key doesn't have access to the language detection feature
    * The account doesn't have the required permissions
    * The feature flag is not enabled for the account
  </Tab>

  <Tab title="415 Unsupported Media Type">
    ```json theme={null}
    {
      "message": "Called with an unsupported media type. Supported media types: application/json or application/x-www-form-urlencoded. Please set the Content-Type header to a supported type."
    }
    ```

    This error occurs when:

    * The request is in an unsupported format
  </Tab>

  <Tab title="500 Internal Server Error">
    ```json theme={null}
    {
      "message": "Internal server error."
    }
    ```

    This error occurs when there are issues with the internal language detection service.
  </Tab>
</Tabs>

### Response Fields

<ResponseField name="results" type="array" required>
  Array of detection results, one for each input text. Each result object contains a `detected_language` and a `detection_status` field.
</ResponseField>

<ResponseField name="detected_language" type="string">
  The detected language code when detection is successful.

  **Language Codes** (when `detection_successful` is `true`):

  * Standard BCP-47 language codes:  one of `"en"`, `"de"`, `"fr"`, `"es"`, `"pt"`, `"it"`, `"nl"`, `"pl"`, `"ru"`, `"zh"`, `"ja"`, `"bg"`, `"cs"`, `"da"`, `"el"`, `"et"`, `"fi"`, `"hu"`, `"lt"`, `"lv"`, `"ro"`, `"sk"`, `"sl"`, `"sv"`, `"tr"`, `"id"`, `"uk"`, `"ko"`, `"nb"`, `"ar"`, `"vi"`, `"he"`, `"th"`
  * See [supported languages](/docs/getting-started/supported-languages) for more info

  When `detection_status` is not `success`, this field is not defined.
</ResponseField>

<ResponseField name="detection_status" type="string" required>
  Indicates the result of language detection. Possible values:

  * `"success"` - Language successfully detected and returned in `detected_language`
  * `"insufficient_confidence"` - Detection confidence too low to return a reliable single result
  * `"unsupported_language"` - A language was detected but it's not supported by DeepL's translation service
  * `"no_language_detected"` - No language could be detected from the input text
</ResponseField>

## Limitations

* Only supports detection of languages that are available in DeepL's translation service
* Requires high confidence to return the language
* Only returns the first top language guess for any single text, may not work well with language variants that are very similar to each other
* Limited to text-based detection (no support for document formats)