# Pluck (`pluck-1`): Keyphrase extraction

The phrases a text is about, ready for tags and SEO.

Pluck pulls out the words and short phrases that best describe a text, picked so they don't repeat each other. Use them as tags, search keywords, or labels for a cluster.

`diversity` trades relevance for variety: 0 gives the closest phrases even if they overlap, 1 spreads them across the text.

- **Price:** $0.03 per 1,000 texts. One unit per started 2,000 characters.
- **Languages:** Best in English; works in most European languages
- **Input:** A string or array of up to 16 (up to 8,000 characters each).
- **Batch:** yes, up to 16 inputs per call
- **Status:** live
- **Built on:** [intfloat/multilingual-e5-small (with our phrase selection)](https://huggingface.co/intfloat/multilingual-e5-small), MIT, 118M

## Request

```bash
curl https://labs.greatwork.company/v1/run \
  -H "Authorization: Bearer $GWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"pluck-1","input":"Our insulated stainless steel water bottle keeps drinks cold for 24 hours and hot for 12. The leak-proof lid fits in a cup holder, and the powder coat won't sweat or slip. Dishwasher safe, BPA free, available in 12 colors."}'
```

## Options

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `input` | string or string[] | yes | | A string or array of up to 16 (up to 8,000 characters each). |
| `top_k` | integer | no | `8` | How many phrases to return. |
| `diversity` | number | no | `0.3` | 0 for the most relevant phrases, 1 for the most varied. |

## Output

| Field | Type | Description |
|---|---|---|
| `keyphrases` | object[] | `text` and `score` (relevance to the whole text), in pick order. |

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)

### Product page

```json
{
  "model": "pluck-1",
  "input": "Our insulated stainless steel water bottle keeps drinks cold for 24 hours and hot for 12. The leak-proof lid fits in a cup holder, and the powder coat won't sweat or slip. Dishwasher safe, BPA free, available in 12 colors."
}
```

```json
{
  "keyphrases": [
    {
      "text": "keeps drinks cold",
      "score": 0.8442
    },
    {
      "text": "steel water bottle",
      "score": 0.8263
    },
    {
      "text": "leak-proof lid fits",
      "score": 0.818
    },
    {
      "text": "stainless",
      "score": 0.8091
    },
    {
      "text": "water bottle keeps",
      "score": 0.8237
    },
    {
      "text": "insulated",
      "score": 0.8116
    },
    {
      "text": "bottle keeps drinks",
      "score": 0.8345
    },
    {
      "text": "BPA free",
      "score": 0.8028
    }
  ]
}
```

806 ms, $0.00003.

### Article

```json
{
  "model": "pluck-1",
  "input": "Solar panel prices fell another 15% this year as new factories in Southeast Asia came online, while battery storage costs dropped even faster. Utilities say the combination is making evening peak demand easier to cover without gas plants.",
  "top_k": 5
}
```

```json
{
  "keyphrases": [
    {
      "text": "Solar panel prices",
      "score": 0.8539
    },
    {
      "text": "battery storage",
      "score": 0.8184
    },
    {
      "text": "Utilities",
      "score": 0.8165
    },
    {
      "text": "storage costs dropped",
      "score": 0.8075
    },
    {
      "text": "prices",
      "score": 0.8185
    }
  ]
}
```

679 ms, $0.00003.

## Good for

- Auto-tag blog posts and docs
- Suggest SEO keywords for a page
- Label clusters of feedback
- Build a tag cloud for a knowledge base

## Limits and caveats

- Phrases come from the text itself: it won't invent a category name that isn't written there (use Sort or Topic for that).
