> For the complete documentation index, see [llms.txt](https://docs.ionos.com/cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ionos.com/cloud/ai/ai-model-hub/how-tos/text-embeddings.md). # Text Embeddings The space.vars.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 space.vars.ionos\_cloud\_ai\_model\_hub [models list](/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. ## 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**](/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 space.vars.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: {% 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/QAAahNmE21M67BAksk0m" %} {% 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/Uc1Dbyb8nNnQWFq75LC0" %} {% 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/v0aTXbi5MpQkz5MCDfeS" %} {% 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. 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](#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. {% 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 %} ### 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. {% tabs %} {% tab title="Python" %} ```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"] ``` {% endtab %} {% endtabs %} 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](/cloud/ai/ai-model-hub/how-tos/image-input.md). ### 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 %} For a list of possible error codes and handling instructions, see [Error Codes](/cloud/ai/ai-model-hub/error-codes.md). ## 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](/cloud/ai/ai-model-hub/how-tos/retrieval-augmented-generation.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.ionos.com/cloud/ai/ai-model-hub/how-tos/text-embeddings.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.