Text Embeddings

The IONOS CLOUD 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 IONOS CLOUD AI Model Hub models list shows all models available for embedding generation. Refer to the relevant model cards for each embedding model's suitable use cases.

Overview

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 embeddings

By the end, you will be able to:

1. Retrieve a list of available embedding models in the IONOS CLOUD 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 access embedding-specific scripts and examples and generate the intended output:

Python Notebook

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

ai-model-hub-text-embeddings.ipynb

69KB

Open

Python Code

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

ai-model-hub-text-embeddings.py

2KB

Open

Bash Code

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

ai-model-hub-text-embeddings.sh

1KB

Open

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,
      },
      {
         "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.

The request accepts the following fields:

Field	Required	Description
model	Yes	The embedding model to use.
input	One of	The text to embed. Either a single string, or an array of up to 2048 non-empty strings. Mutually exclusive with messages.
messages	One of	Multi-modal input, as an alternative to input. See Embed an Image. Mutually exclusive with input.
encoding_format	No	float to receive the vector as numbers, or base64 for a compact encoding. Defaults to float.
user	No	An end-user identifier for your own tracking, up to 256 characters.

Provide exactly one of input or messages. Sending both, or neither, returns a 400 error.

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

Embed an Image

Models advertising image input, such as Qwen3 VL Embedding 8B, accept a messages array instead of input. It holds a single user turn whose content is an ordered list of parts, so an image can be embedded on its own or together with text describing it.

Parts use the same names as chat completions: text, image_url, and video_url. A multi-modal request produces exactly one embedding, rather than one per input.

Python

body = {
    "model": "Qwen/Qwen3-VL-Embedding-8B",
    "messages": [{
        "role": "user",
        "content": [
            {"type": "text", "text": "A product photo of a red bicycle"},
            {"type": "image_url", "image_url": {"url": "https://example.com/bicycle.png"}}
        ]
    }]
}
result = requests.post(endpoint, json=body, headers=header).json()
embedding = result["data"][0]["embedding"]

Sending an image to a model that does not advertise image input returns an error naming the missing capability, so check the model card before using this form.

For the accepted formats and the request size limits, see Image Input.

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

For a list of possible error codes and handling instructions, see Error Codes.

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 Retrieval Augmented Generation.