# Ear (`ear-1`): Spoken language detection

Which language is being spoken, from the first 30 seconds.

Ear listens to the start of a recording and names the spoken language out of about 100, with a confidence and the runner-up guesses. Use it to route calls and voice notes to the right team, or to pick the language for a transcription model before you pay for the whole file.

- **Price:** $0.10 per 1,000 files. One unit per file, any length (only the first 30 seconds are analyzed).
- **Languages:** ~100 spoken languages

- **Input:** An audio or video file: an https URL, a data URL, or a file in a multipart upload, up to 25 MB. Only the first 30 seconds are used.
- **Batch:** no, one input per call
- **Status:** live
- **Built on:** [openai/whisper-base (language head)](https://huggingface.co/openai/whisper-base), Apache-2.0, 74M

## Request

```bash
curl https://labs.greatwork.company/v1/run \
  -H "Authorization: Bearer $GWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"ear-1","input":"https://labs.greatwork.company/examples/spanish.m4a"}'
```

Upload a local file with multipart: `curl https://labs.greatwork.company/v1/run -H "Authorization: Bearer $GWL_API_KEY" -F model=ear-1 -F input=@file`

## Options

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `input` | audio (URL, data URL or upload) | yes | | An audio or video file: an https URL, a data URL, or a file in a multipart upload, up to 25 MB. Only the first 30 seconds are used. |
| `top_k` | integer | no | `3` | How many candidate languages to return. |

## Output

| Field | Type | Description |
|---|---|---|
| `language` | string | ISO 639-1 code (`en`, `es`, `ja`). |
| `name` | string | English name of the language. |
| `score` | number | Confidence, 0 to 1. |
| `candidates` | object[] | Top guesses with `language`, `name`, `score`. |
| `listened` | number | Seconds of audio used (at most 30). |

The response envelope is always `{"id", "object": "run", "model", "created", "output", "usage": {"units", "unit", "cost_usd", "cost_micros"}, "latency_ms"}`.

## Examples (real outputs from our servers)

### Spanish

```json
{
  "model": "ear-1",
  "input": "https://labs.greatwork.company/examples/spanish.m4a"
}
```

```json
{
  "language": "es",
  "name": "Spanish",
  "score": 0.994,
  "candidates": [
    {
      "language": "es",
      "name": "Spanish",
      "score": 0.994
    },
    {
      "language": "en",
      "name": "English",
      "score": 0.0016
    },
    {
      "language": "fr",
      "name": "French",
      "score": 0.0005
    }
  ],
  "listened": 8.68
}
```

2216 ms, $0.0001.

### English

```json
{
  "model": "ear-1",
  "input": "https://labs.greatwork.company/examples/voice-note.m4a",
  "top_k": 5
}
```

```json
{
  "language": "en",
  "name": "English",
  "score": 0.9914,
  "candidates": [
    {
      "language": "en",
      "name": "English",
      "score": 0.9914
    },
    {
      "language": "hi",
      "name": "Hindi",
      "score": 0.001
    },
    {
      "language": "tl",
      "name": "Tagalog",
      "score": 0.0009
    },
    {
      "language": "tr",
      "name": "Turkish",
      "score": 0.0007
    },
    {
      "language": "el",
      "name": "Greek",
      "score": 0.0006
    }
  ],
  "listened": 10.73
}
```

1777 ms, $0.0001.

## Good for

- Route voicemails and calls by language
- Pick the right transcription or translation model
- Tag podcast and video libraries by language
- Spot callers who need an interpreter

## Limits and caveats

- Needs speech in the first 30 seconds: trim long intros or music first.
- Closely related languages (Spanish and Galician, Norwegian and Danish) can be confused.
