> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.userbot.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.userbot.ai/_mcp/server.

# Embeddings

Un embedding è un elenco di numeri che rappresenta il significato di un testo.
Due testi che dicono la stessa cosa con parole diverse hanno vettori vicini: è
quello che serve per costruire una ricerca semantica nel tuo software, trovare
duplicati o raggruppare richieste simili.

`POST /embeddings` lo calcola. Serve una chiave con il permesso **Embedding**: le
chiavi personali ce l'hanno sempre, quelle dell'area di lavoro solo se è stato
scelto alla creazione.

## La richiesta

| Campo        | Obbligatorio | Cosa fa                                                                               |
| ------------ | ------------ | ------------------------------------------------------------------------------------- |
| `model`      | Sì           | Un modello di embedding: in `GET /models` sono quelli con `kind` uguale a `embedding` |
| `input`      | Sì           | Una stringa, oppure una lista di stringhe. Nessuna può essere vuota                   |
| `dimensions` | No           | Il numero di dimensioni del vettore, per i modelli che permettono di sceglierlo       |

```bash
curl https://api.userbot.ai/api/eu/v1/embeddings \
  -H "Authorization: Bearer $USERBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": ["Il listino 2026 è in vigore da gennaio.", "Prezzi aggiornati dal primo dell'\''anno."]
  }'
```

Con l'SDK OpenAI per Python:

```python
result = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input=["Il listino 2026 è in vigore da gennaio.", "Prezzi aggiornati dal primo dell'anno."],
)
vettori = [row.embedding for row in result.data]
```

## La risposta

```json
{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, 0.0789] },
    { "object": "embedding", "index": 1, "embedding": [0.0119, -0.0441, 0.0802] }
  ],
  "model": "openai/text-embedding-3-small",
  "usage": { "prompt_tokens": 22, "total_tokens": 22 }
}
```

Un elemento di `data` per ogni testo mandato, nello stesso ordine: `index` ti
dice a quale corrisponde. I vettori veri sono molto più lunghi di quelli
dell'esempio. Le chiamate di embedding si pagano solo sui token in ingresso.

## Come usarli bene

**Usa sempre lo stesso modello.** Vettori calcolati con modelli diversi, o con
`dimensions` diverse, non si possono confrontare fra loro. Se cambi modello,
ricalcola tutto l'archivio.

**Manda i testi in gruppo.** Una lista di stringhe in una sola chiamata costa
quanto le chiamate separate, ma pesa molto meno sul limite di richieste al
minuto. → [Limiti e quote](/api-limiti)

**Calcola una volta, conserva.** Il vettore di un documento non cambia finché non
cambia il testo: salvalo insieme al documento e ricalcolalo solo quando serve.

Un modello di completamento usato su questo endpoint viene rifiutato come
modello sconosciuto: `400` su **Global**, `451` su **EU**. Lo stesso vale al
contrario.