# Lingo (`lingo-1`): Language detection

Which language is this? 183 of them, from a few words up.

Lingo names the language of a text and its script, from a full page down to a short phrase. It returns an ISO code you can store, the language's English name, and the runner-up guesses with scores.

Use `only` to restrict the answer to languages you expect: it's the easiest way to stop a short message in Spanish being called Galician.

- **Price:** $0.02 per 1,000 texts. One unit per text up to 2,000 characters; longer texts are split into 2,000-character chunks and each chunk is a unit.
- **Languages:** 183 languages and scripts (FLORES-200)
- **Input:** A string, or an array of up to 64 strings to run as a batch.
- **Batch:** yes, up to 64 inputs per call
- **Status:** live
- **Built on:** [Horizon-Labs/language-detection-small](https://huggingface.co/Horizon-Labs/language-detection-small), Apache-2.0, 141M (mmBERT-small encoder)

## Request

```bash
curl https://labs.greatwork.company/v1/run \
  -H "Authorization: Bearer $GWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"lingo-1","input":"¿Dónde está la estación de tren más cercana? Llevamos una hora caminando."}'
```

## Options

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `input` | string or string[] | yes | | A string, or an array of up to 64 strings to run as a batch. |
| `top_k` | integer | no | `3` | How many candidate languages to return. |
| `only` | string[] | no |  | Restrict answers to these languages (ISO 639-1 like `en`, or FLORES codes like `eng_Latn`). |

## Output

| Field | Type | Description |
|---|---|---|
| `language` | string | Best guess as an ISO 639 code (`en`, `es`, `zh`), or the 3-letter code when no 2-letter code exists. |
| `name` | string | English name of the language. |
| `script` | string | ISO 15924 script code (`Latn`, `Cyrl`, `Hani`). |
| `code` | string | FLORES-200 code, language plus script (`eng_Latn`). |
| `score` | number | Confidence, 0 to 1. |
| `candidates` | object[] | Top guesses with `language`, `name`, `code` and `score`. |

The response envelope is always `{"id", "object": "run", "model", "created", "output", "usage": {"units", "unit", "cost_usd", "cost_micros"}, "latency_ms"}`. With an array input, `output` is an array in the same order.

## Examples (real outputs from our servers)

### Spanish

```json
{
  "model": "lingo-1",
  "input": "¿Dónde está la estación de tren más cercana? Llevamos una hora caminando."
}
```

```json
{
  "language": "es",
  "name": "Spanish",
  "script": "Latn",
  "code": "spa_Latn",
  "score": 0.8457,
  "candidates": [
    {
      "language": "es",
      "name": "Spanish",
      "script": "Latn",
      "code": "spa_Latn",
      "score": 0.8457
    },
    {
      "language": "eu",
      "name": "Basque",
      "script": "Latn",
      "code": "eus_Latn",
      "score": 0.0376
    },
    {
      "language": "gn",
      "name": "Guarani",
      "script": "Latn",
      "code": "grn_Latn",
      "score": 0.0269
    }
  ]
}
```

85 ms, $0.00002.

### Batch of three

```json
{
  "model": "lingo-1",
  "input": [
    "Merci beaucoup pour votre aide !",
    "Vielen Dank für die schnelle Antwort.",
    "ありがとうございます、助かりました。"
  ]
}
```

```json
[
  {
    "language": "fr",
    "name": "French",
    "script": "Latn",
    "code": "fra_Latn",
    "score": 0.3579,
    "candidates": [
      {
        "language": "fr",
        "name": "French",
        "script": "Latn",
        "code": "fra_Latn",
        "score": 0.3579
      },
      {
        "language": "ln",
        "name": "Lingala",
        "script": "Latn",
        "code": "lin_Latn",
        "score": 0.1971
      },
      {
        "language": "wo",
        "name": "Wolof",
        "script": "Latn",
        "code": "wol_Latn",
        "score": 0.1914
      }
    ]
  },
  {
    "language": "de",
    "name": "German",
    "script": "Latn",
    "code": "deu_Latn",
    "score": 0.9045,
    "candidates": [
      {
        "language": "de",
        "name": "German",
        "script": "Latn",
        "code": "deu_Latn",
        "score": 0.9045
      },
      {
        "language": "ak",
        "name": "Akan",
        "script": "Latn",
        "code": "aka_Latn",
        "score": 0.0107
      },
      {
        "language": "lb",
        "name": "Luxembourgish",
        "script": "Latn",
        "code": "ltz_Latn",
        "score": 0.0104
      }
    ]
  },
  {
    "language": "ja",
    "name": "Japanese",
    "script": "Jpan",
    "code": "jpn_Jpan",
    "score": 0.9974,
    "candidates": [
      {
        "language": "ja",
        "name": "Japanese",
        "script": "Jpan",
        "code": "jpn_Jpan",
        "score": 0.9974
      },
      {
        "language": "ak",
        "name": "Akan",
        "script": "Latn",
        "code": "aka_Latn",
        "score": 0.0003
      },
      {
        "language": "ko",
        "name": "Korean",
        "script": "Hang",
        "code": "kor_Hang",
        "score": 0.0002
      }
    ]
  }
]
```

115 ms, $0.00006.

### Restricted

```json
{
  "model": "lingo-1",
  "input": "obrigado pela ajuda",
  "only": [
    "pt",
    "es",
    "gl"
  ]
}
```

```json
{
  "language": "pt",
  "name": "Portuguese",
  "script": "Latn",
  "code": "por_Latn",
  "score": 0.9805,
  "candidates": [
    {
      "language": "pt",
      "name": "Portuguese",
      "script": "Latn",
      "code": "por_Latn",
      "score": 0.9805
    },
    {
      "language": "gl",
      "name": "Galician",
      "script": "Latn",
      "code": "glg_Latn",
      "score": 0.0148
    },
    {
      "language": "es",
      "name": "Spanish",
      "script": "Latn",
      "code": "spa_Latn",
      "score": 0.0046
    }
  ]
}
```

23 ms, $0.00002.

## Good for

- Route support tickets to the right team
- Pick the translation or speech model to call next
- Tag user content for search filters
- Spot replies in the wrong language before sending

## Limits and caveats

- Very short texts (one or two words) are often low confidence: check `score`.
- Mixed-language text gets one label.
- Chinese is one label (`zh`, Simplified and Traditional together); Arabic dialects are one label (`ar`).
- Weaker on Bosnian vs Croatian vs Serbian (Latin).
