# Text Embeddings

The <code class="expression">space.vars.ionos\_cloud\_ai\_model\_hub</code> provides an OpenAI-compatible API that enables embedding generation for text input using state-of-the-art embedding models. Embeddings are multi-dimensional vectors that are lists of numerical values-the more semantically similar the text input, the more similar the embeddings.

## Supported Embedding Models

The <code class="expression">space.vars.ionos\_cloud\_ai\_model\_hub</code> [<mark style="color:blue;">models list</mark>](/cloud/ai/ai-model-hub/models.md) shows all models available for embedding generation. Refer to the relevant model cards for each embedding model's suitable use cases.

## About this guide

In this guide, you will learn how to generate embeddings through the OpenAI compatible API. This guide is intended for developers with basic knowledge of:

* REST APIs
* A programming language for handling REST API endpoints (Python and Bash examples are provided)
* Basic understanding of [<mark style="color:blue;">**embeddings**</mark>](/cloud/ai/ai-model-hub/advanced-concepts/embeddings.md)

By the end, you will be able to:

1. Retrieve a list of available embedding models in the <code class="expression">space.vars.ionos\_cloud\_ai\_model\_hub</code>.
2. Use the API to generate embeddings with these models.
3. Use the generated embeddings as input to calculate similarity scores.

## Getting started with embedding generation

To use embedding models, first set up your environment and authenticate using the OpenAI-compatible API endpoints.

Download the respective code files to access embedding-specific scripts and examples and generate the intended output:

{% tabs %}
{% tab title="Python Notebook" %}
Download this Python Notebook file to use embedding-specific scripts and examples and generate the intended output.

{% file src="/files/bQxzYLFlA9o2P82o63TN" %}
{% endtab %}

{% tab title="Python Code" %}
Download this Python code file to use embedding-specific scripts and examples and generate the intended output.

{% file src="/files/epO7dM92lG9DdgBmEKBV" %}
{% endtab %}

{% tab title="Bash Code" %}
Download this Bash code file to use embedding-specific scripts and examples and generate the intended output.

{% file src="/files/kOLw6fSBI1ABBy4ZBjxy" %}
{% endtab %}
{% endtabs %}

### Step 1: Retrieve Available Models

Fetch a list of embedding models to see which models are available for your use case:

{% tabs %}
{% tab title="Python" %}

```python
# Python example to retrieve available models
import requests

IONOS_API_TOKEN = "[YOUR API TOKEN HERE]"

endpoint = "https://openai.inference.de-txl.ionos.com/v1/models"

header = {
    "Authorization": f"Bearer {IONOS_API_TOKEN}", 
    "Content-Type": "application/json"
}
requests.get(endpoint, headers=header).json()
```

{% endtab %}

{% tab title="Bash" %}

```bash
#!/bin/bash

IONOS_API_TOKEN=[YOUR API TOKEN HERE]

curl -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
        --get https://openai.inference.de-txl.ionos.com/v1/models
```

{% endtab %}
{% endtabs %}

#### Output

```
      {
         "id":"sentence-transformers/paraphrase-multilingual-mpnet-base-v2",
         "object":"model",
         "created":1677610602,
      },
      {
         "id":"BAAI/bge-m3",
         "object":"model",
         "created":1677610602,
      },
      {
         "id":"BAAI/bge-large-en-v1.5",
         "object":"model",
         "created":1677610602,
      },
      {
         "id":"Qwen/Qwen3-VL-Embedding-8B",
         "object":"model",
         "created":1677610602,
      },
```

This query returns a JSON document listing each model's name, which you’ll use to specify a model for embedding generation in later steps.

### Step 2: Generate Embeddings with Your Prompt

To generate an embedding, send the text to the `/embeddings` endpoint.

{% tabs %}
{% tab title="Python" %}

```python
# Python example for embedding generation
import requests

IONOS_API_TOKEN = "[YOUR API TOKEN HERE]"
MODEL_NAME = "[MODEL NAME HERE]"
INPUT = ["Michael Jackson", "Metallica"]

endpoint = "https://openai.inference.de-txl.ionos.com/v1/embeddings"

header = {
    "Authorization": f"Bearer {IONOS_API_TOKEN}", 
    "Content-Type": "application/json"
}
body = {
    "model": MODEL_NAME,
    "input": INPUT
}
result = requests.post(endpoint, json=body, headers=header)
```

{% endtab %}

{% tab title="Bash" %}

```bash
#!/bin/bash

IONOS_API_TOKEN=[YOUR API TOKEN HERE]
MODEL_NAME=[MODEL NAME HERE]
INPUT='["Michael Jackson", "Metallica"]'

BODY='{
    "model": "'$MODEL_NAME'",
    "input": '$INPUT'
}'

curl -X POST -H "Authorization: Bearer ${IONOS_API_TOKEN}" \
     -H "Content-Type: application/json" \
     -d "$BODY" \
     https://openai.inference.de-txl.ionos.com/v1/embeddings
```

{% endtab %}
{% endtabs %}

### Step 3: Calculate Similarity Scores

The returned JSON includes several key fields, most importantly:

* **`data.[..].embedding`**: The generated embedding as a vector of numeric values.
* **`usage.prompt_tokens`**: Token count for the input prompt.
* **`usage.total_tokens`**: Token count for the entire process.

Using python, you can calculate the similarity of two results:

{% tabs %}
{% tab title="Python" %}

```python
# Python example for similarity scoring
import numpy as np
import requests

IONOS_API_TOKEN = "[YOUR API TOKEN HERE]"
MODEL_NAME = "sentence-transformers/paraphrase-multilingual-mpnet-base-v2"
INPUT = ["Michael Jackson", "Metallica"]

endpoint = "https://openai.inference.de-txl.ionos.com/v1/embeddings"

header = {
    "Authorization": f"Bearer {IONOS_API_TOKEN}", 
    "Content-Type": "application/json"
}
body = {
    "model": MODEL_NAME,
    "input": INPUT
}
result = requests.post(endpoint, json=body, headers=header).json()

embedding_1 = result['data'][0]['embedding']
embedding_2 = result['data'][1]['embedding']

similarity = np.dot(embedding_1, embedding_2)

# 0.18887
```

{% endtab %}
{% endtabs %}

The Embeddings API uses standard HTTP error codes to indicate the outcome of a request. The error codes and their description are as below:

* `200 OK`: The request was successful.
* `401 Unauthorized`: The request was unauthorized.
* `404 Not Found`: The requested resource was not found.
* `500 Internal Server Error`: An internal server error occurred.

## What you learned

In this guide, you learned how to:

1. Access available embedding models.
2. Generate embeddings with these models.
3. Calculate similarity scores using the numpy library.

To learn how to use embeddings to build a full RAG pipeline, see [<mark style="color:blue;">Retrieval Augmented Generation</mark>](/cloud/ai/ai-model-hub/how-tos/retrieval-augmented-generation.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ionos.com/cloud/ai/ai-model-hub/how-tos/text-embeddings.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.