# Embeddings

> Référence de POST /v1/embeddings : transformer des textes en vecteurs au format d’OpenAI, pour la recherche sémantique ou le regroupement, avec Moon Blur.

`POST /v1/embeddings` transforme un ou plusieurs textes en vecteurs de nombres. Deux textes proches par le sens donnent des vecteurs proches : c’est la base d’une recherche sémantique, d’un regroupement de documents ou d’une détection de doublons. Le point d’accès suit le format d’OpenAI ; les SDK s’utilisent sans changement.

```http
POST https://api.realmoon.ai/v1/embeddings
```

- Authentification : clé `sk-moon-…` avec la portée `inference` (voir [Authentification](https://realmoon.ai/documentation/api/authentification/)).
- Corps : JSON, 8 Mo au plus.
- Réponse : un objet `list` de vecteurs.

## Paramètres

| Paramètre | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `model` | chaîne | oui | Un modèle de type `embedding` de `GET /v1/models?type=embedding`. |
| `input` | chaîne, tableau de chaînes, ou jetons | oui | Le texte, ou jusqu’à 2 048 textes. Une liste d’entiers (ou une liste de listes d’entiers) est lue comme des jetons déjà découpés. Pas de chaîne vide. |
| `dimensions` | entier | non | Taille des vecteurs, entre 1 et la taille du modèle. Seulement pour les modèles qui l’acceptent (`custom_dimensions` à `true` dans `/v1/models`). |
| `encoding_format` | chaîne | non | `float` (par défaut) ou `base64` : les nombres en float32 little-endian, encodés en base64. |
| `input_type` | chaîne | non | `query` (une question) ou `document` (un texte à retrouver), pour les modèles qui distinguent les deux. |
| `user` | chaîne | non | Identifiant de votre utilisateur final. Accepté, n’est pas transmis. |

Tout autre paramètre est refusé avec `400 unknown_parameter`.

> [!NOTE]
> **Format base64 des SDK**
>
> Sans `encoding_format`, les SDK d’OpenAI demandent le format `base64` et décodent eux-mêmes les vecteurs. L’API le sert : vous recevez des listes de nombres comme d’habitude.

## Exemple

```bash title="cURL"
curl https://api.realmoon.ai/v1/embeddings \
  -H "Authorization: Bearer $MOONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistralai/mistral-embed-2312",
    "input": ["Comment résilier mon contrat ?", "Les horaires d’ouverture du magasin"]
  }'
```

```python title="Python"
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.realmoon.ai/v1", api_key=os.environ["MOONAI_API_KEY"])

result = client.embeddings.create(
    model="mistralai/mistral-embed-2312",
    input=["Comment résilier mon contrat ?", "Les horaires d’ouverture du magasin"],
)
for item in result.data:
    print(item.index, len(item.embedding))
```

```javascript title="JavaScript"
import OpenAI from 'openai';

const client = new OpenAI({ baseURL: 'https://api.realmoon.ai/v1', apiKey: process.env.MOONAI_API_KEY });

const result = await client.embeddings.create({
  model: 'mistralai/mistral-embed-2312',
  input: ['Comment résilier mon contrat ?', 'Les horaires d’ouverture du magasin'],
});
for (const item of result.data) console.log(item.index, item.embedding.length);
```

## Réponse

```json title="Réponse"
{
  "object": "list",
  "model": "mistralai/mistral-embed-2312",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, 0.0789] },
    { "object": "embedding", "index": 1, "embedding": [-0.0311, 0.0042, 0.0517] }
  ],
  "usage": { "prompt_tokens": 18, "total_tokens": 18, "credits": 1 }
}
```

Les vecteurs sont raccourcis dans l’exemple : un vrai vecteur de ce modèle a 1 024 nombres.

| Champ | Type | Description |
| --- | --- | --- |
| `object` | chaîne | Toujours `list`. |
| `model` | chaîne | Le modèle appelé. |
| `data[].object` | chaîne | Toujours `embedding`. |
| `data[].index` | entier | Position du texte dans `input`. |
| `data[].embedding` | tableau ou chaîne | Le vecteur : une liste de nombres, ou une chaîne base64 avec `encoding_format: "base64"`. |
| `usage.prompt_tokens`, `usage.total_tokens` | entier | Jetons comptés. |
| `usage.credits` | entier | Crédits facturés pour la requête. |

En-têtes : `X-Moon-Request-Id`, `X-Moon-Prompt-Storage: none`, `X-Moon-Blur` et, quand Moon Blur a remplacé des valeurs, `X-Moon-Blur-Redactions`.

## Moon Blur

Quand Moon Blur est actif sur la clé (c’est le cas par défaut), les données personnelles détectées dans les textes sont remplacées avant l’envoi au modèle. Seuls les vecteurs des passages concernés changent. L’en-tête `X-Moon-Blur` vaut `on` ou `off`, et `X-Moon-Blur-Redactions` donne le nombre de valeurs remplacées. Un texte donné sous forme de jetons n’est pas lu par Moon Blur. Voir [Confidentialité](https://realmoon.ai/documentation/api/confidentialite/#moon-blur).

## Modèles

Liste au 5 novembre 2026 ; la liste à jour, avec les prix et la taille des vecteurs, vient de `GET /v1/models?type=embedding`.

| Modèle | Taille des vecteurs | `dimensions` |
| --- | --- | --- |
| `openai/text-embedding-3-small` | 1 536 | oui |
| `openai/text-embedding-3-large` | 3 072 | oui |
| `mistralai/mistral-embed-2312` | 1 024 | non |
| `mistralai/codestral-embed-2505` | 1 536 | non |
| `google/gemini-embedding-001` | 3 072 | non |
| `qwen/qwen3-embedding-8b` | 4 096 | non |
| `qwen/qwen3-embedding-4b` | 2 560 | non |
| `baai/bge-m3` | 1 024 | non |
| `intfloat/multilingual-e5-large` | 1 024 | non |
| `voyageai/voyage-4`, `voyageai/voyage-4-lite`, `voyageai/voyage-code-4` | selon le modèle | non |
| `perplexity/pplx-embed-v1-4b` | selon le modèle | non |

Gardez le même modèle pour vos documents et pour vos questions : des vecteurs de deux modèles différents ne se comparent pas.

## Coûts

Avant l’appel, la requête retient le plus que les textes peuvent compter (un jeton par octet du texte, plus quelques jetons par texte). Elle est ensuite facturée sur les jetons réellement comptés, ou sur le coût réel annoncé par le fournisseur. Une requête qui échoue ne coûte rien.

## Limites

| Limite | Valeur |
| --- | --- |
| Textes par requête | 2 048 |
| Taille de la requête | 8 Mo, et environ 1 million de jetons |
| Taille de la réponse | nombre de textes × taille des vecteurs : 3 millions de nombres au plus |
| Requêtes en cours par workspace | 8 |
| Attente de la réponse du modèle | 85 secondes au plus |

Au-delà de la taille de réponse, l’API indique combien de textes ce modèle accepte en une requête : découpez en plusieurs appels.

## Erreurs

| HTTP | `code` | Signification |
| --- | --- | --- |
| 400 | `missing_required_parameter` | `model` absent. |
| 400 | `unknown_parameter` | Paramètre inconnu. |
| 400 | `unsupported_parameter` | `dimensions` sur un modèle qui ne l’accepte pas, ou valeur refusée par le modèle (avec une indication). |
| 400 | `unsupported_value` | `dimensions` hors limites, ou `encoding_format` inconnu. |
| 400 | `null` | `input` mal formé, vide, trop gros, ou trop de textes (`param: "input"`) ; `input_type` inconnu ; corps JSON invalide. |
| 403 | `org_policy` | Les règles de votre organisation refusent ce modèle. |
| 404 | `model_not_found` | Modèle inconnu ou qui ne sert pas ce point d’accès. |
| 413 | `request_too_large` | Corps de plus de 8 Mo. |
| 413 | `moon_blur_payload_too_large` | Un texte dépasse 500 000 caractères, trop long pour Moon Blur : rien n’est envoyé ni facturé. |
| 429 | `too_many_concurrent` | Déjà 8 requêtes d’embeddings en cours pour ce workspace. |
| 429 | `upstream_rate_limited` | Le modèle est surchargé : réessayez après `Retry-After` (10 secondes). |
| 502, 504 | `upstream_error`, `upstream_timeout` | Le modèle a échoué ou n’a pas répondu à temps. |
| 503 | `moon_blur_unavailable` | Moon Blur n’a pas pu analyser les textes : rien n’est envoyé ni facturé. |

Les erreurs de clé, de solde et de plafonds sont dans [Erreurs](https://realmoon.ai/documentation/api/erreurs/).

## Voir aussi

- [Modèles](https://realmoon.ai/documentation/api/modeles/#medias) : les champs `dimensions`, `custom_dimensions` et `context_length`.
- [Confidentialité](https://realmoon.ai/documentation/api/confidentialite/#moon-blur) : ce que Moon Blur détecte et ne détecte pas.

---

Documentation Moon AI › API développeur › Embeddings. Page : https://realmoon.ai/documentation/api/embeddings/. Modifiée le 5 novembre 2026.

© 2026 Stellarr Studio SAS. Tous droits réservés. Moon AI, Moon Blur et Stellarr Studio sont des marques déposées à l’INPI.