Text Embeddings

AI Model Hub for Free: From December 1, 2024, to June 30, 2025, IONOS is offering all foundation models in the AI Model Hub for free. Create your contract today and kickstart your AI journey!

The IONOS AI Model Hub 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 following models are available for embedding generation in the IONOS AI Model Hub, each suited for different use cases:

Model Source	Model Name	Description
Hugging Face (Publication)	Paraphrase Multilingual MPNet base v2	Transformer model supporting several different languages with high performance and short input length (128 tokens).
Hugging Face (License)	BAAI Large EN V1.5	Embedding model specific for english, medium sized inputs (512 tokens).
Hugging Face (License)	BAAI M3	Multipurpose embedding model for multilingual text(100 working languages) and large documents (8192 tokens).

Overview

In this tutorial, you will learn how to generate embeddings through the OpenAI compatible API. This tutorial 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 embeddings

By the end, you will be able to:

1. Retrieve a list of available embedding models in the IONOS AI Model Hub.

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 easily access embedding-specific scripts and examples and generate the intended output:

Python Notebook

Download this Python Notebook file to easily access embedding-specific scripts and examples and generate the intended output.

69KB

ai-model-hub-text-embeddings.ipynb

Python Code

Download this Python code file to easily access embedding-specific scripts and examples and generate the intended output.

2KB

ai-model-hub-text-embeddings.py

Bash Code

Download this Bash code file to easily access embedding-specific scripts and examples and generate the intended output.

1KB

ai-model-hub-text-embeddings.sh

Step 1: Retrieve Available Models

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

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()

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

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,
      },

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.

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)

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

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:

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

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.

Summary

In this tutorial, you learned how to:

1. Access available embedding models.

2. Generate embeddings with these models.

3. Calculate similarity scores using the numpy library.

For information on how to use embeddings in document collections, see our dedicated tutorial on Document Collections.