# Tone (`tone-1`): Sentiment analysis

Positive, neutral or negative, in 30+ languages.

Tone reads a review, message or post and says whether it's positive, neutral or negative, with a polarity score from -1 to 1 you can sort and average.

Mixed opinions, plain facts and questions come back neutral, so a ticket that only asks for an invoice doesn't drag your average down.

- **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:** 30+ languages, strongest in English, Spanish, French, German, Portuguese, Italian, Arabic, Hindi
- **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/multilingual-sentiment-small](https://huggingface.co/Horizon-Labs/multilingual-sentiment-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":"tone-1","input":"Arrived two days early and the fit is perfect. Ordering a second one in green."}'
```

## 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. |


## Output

| Field | Type | Description |
|---|---|---|
| `label` | string | `positive`, `neutral` or `negative`. |
| `score` | number | Confidence in `label`, 0 to 1. |
| `polarity` | number | P(positive) minus P(negative), from -1 to 1. |
| `labels` | object[] | All three labels with scores. |

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)

### Happy review

```json
{
  "model": "tone-1",
  "input": "Arrived two days early and the fit is perfect. Ordering a second one in green."
}
```

```json
{
  "label": "positive",
  "score": 0.9942,
  "polarity": 0.9917,
  "labels": [
    {
      "label": "positive",
      "score": 0.9942
    },
    {
      "label": "neutral",
      "score": 0.0034
    },
    {
      "label": "negative",
      "score": 0.0025
    }
  ]
}
```

60 ms, $0.00002.

### Unhappy ticket

```json
{
  "model": "tone-1",
  "input": "Third time this month the export has failed and nobody has replied to my emails."
}
```

```json
{
  "label": "negative",
  "score": 0.9985,
  "polarity": -0.9985,
  "labels": [
    {
      "label": "negative",
      "score": 0.9985
    },
    {
      "label": "neutral",
      "score": 0.0015
    },
    {
      "label": "positive",
      "score": 0
    }
  ]
}
```

39 ms, $0.00002.

### Neutral question

```json
{
  "model": "tone-1",
  "input": "Can you send me last month's invoice as a PDF?"
}
```

```json
{
  "label": "neutral",
  "score": 0.9991,
  "polarity": 0.0002,
  "labels": [
    {
      "label": "neutral",
      "score": 0.9991
    },
    {
      "label": "positive",
      "score": 0.0005
    },
    {
      "label": "negative",
      "score": 0.0004
    }
  ]
}
```

38 ms, $0.00002.

## Good for

- Score reviews and NPS comments
- Flag angry support tickets for a fast reply
- Track brand mentions over time
- Sort feedback before you read it

## Limits and caveats

- Sarcasm is hard: "great, it broke again" can come back positive.
- Not for decisions about individual people.
