# Migration Guide from the Legacy predictions Endpoint

{% hint style="warning" %}
**Retired**: The native `/predictions` endpoint retired on May 5, 2026.
{% endhint %}

If you use the native `/predictions` endpoint (For example: `https://inference.de-txl.ionos.com/models/{modelId}/predictions`), migrate to the OpenAI-compatible API for standard text and image generation use cases. The migration does not affect the `/collections`, `/documents`, and `/query` endpoints.

This migration simplifies integration with OpenAI-compatible tools and SDKs and provides a standardized developer experience.

## Before you begin

To complete this migration you need:

* An active <code class="expression">space.vars.ionos\_cloud\_ai\_model\_hub</code> account with a valid API token.
* A model ID for your use case, which you can retrieve from `https://openai.inference.de-txl.ionos.com/v1/models`.
* An existing document collection. It is required for Retrieval Augmented Generation (RAG) only.

{% hint style="warning" %}
**Best practice:** Place the retrieved context in the system message to separate the instructional context from the user’s question. The approach ensures a cleaner separation of concerns, simplifies follow-up questions, and improves model adherence to grounding information.
{% endhint %}

## Migrate text generation

{% stepper %}
{% step %}

#### Update the endpoint URL

Replace the native endpoint with the OpenAI-compatible chat completions endpoint:

* **Before:** `POST https://inference.de-txl.ionos.com/models/{modelId}/predictions`
* **After:** `POST https://openai.inference.de-txl.ionos.com/v1/chat/completions`

{% hint style="info" %}
**Note:** Move the model ID from the URL to the request body. You can retrieve available IDs using `https://openai.inference.de-txl.ionos.com/v1/models`. Example: `openai/gpt-oss-120b`.
{% endhint %}
{% endstep %}

{% step %}

#### Restructure the request body

**Before:**

```json
{
  "type": "prediction",
  "properties": {
    "input": "Please give me 5 domain suggestions for a flower shop in Berlin. Provide for each domain name a paragraph explaining the domain name and why it is valuable.",
    "options": {
      "max_length": "1000",
      "temperature": "0.5"
    }
  }
}
```

**After:**

```json
{
  "model": "openai/gpt-oss-120b",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Please give me 5 domain suggestions for a flower shop in Berlin. Provide for each domain name a paragraph explaining the domain name and why it is valuable."
    }
  ],
  "max_tokens": 2000,
  "temperature": 0.5
}
```

{% endstep %}

{% step %}

#### Update field names

| Native field                     | OpenAI-compatible field          |
| -------------------------------- | -------------------------------- |
| `properties.input`               | `messages[].content` (user role) |
| `properties.options.max_length`  | `max_tokens`                     |
| `properties.options.temperature` | `temperature`                    |
| `modelId` in the URL             | `model` in the request body      |
| {% endstep %}                    |                                  |
| {% endstepper %}                 |                                  |

## Migrate image generation

{% stepper %}
{% step %}

#### Update the endpoint URL

Replace the native endpoint with the OpenAI-compatible images endpoint:

* **Before:** `POST https://inference.de-txl.ionos.com/models/{modelId}/predictions`
* **After:** `POST https://openai.inference.de-txl.ionos.com/v1/images/generations`

{% hint style="info" %}
**Note:** You can retrieve available model IDs using `https://openai.inference.de-txl.ionos.com/v1/models`. Example: `black-forest-labs/FLUX.1-schnell`.
{% endhint %}
{% endstep %}

{% step %}

#### Restructure the request body

**Before:**

```json
{
  "type": "prediction",
  "properties": {
    "input": "Draw an image of a futuristic city skyline at sunset, digital art.",
    "options": {
      "size": "1024x1024"
    }
  }
}
```

**After:**

```json
{
  "model": "black-forest-labs/FLUX.1-schnell",
  "prompt": "A futuristic city skyline at sunset, digital art.",
  "n": 1,
  "size": "1024x1024"
}
```

{% endstep %}

{% step %}

#### Update field names

| **Native field**          | **OpenAI-compatible field** |
| ------------------------- | --------------------------- |
| `properties.input`        | `prompt`                    |
| `properties.options.size` | `size`                      |
| `modelId` in the URL      | `model` in the request body |
| {% endstep %}             |                             |
| {% endstepper %}          |                             |

## Migrate retrieval augmented generation

Users requiring Retrieval-Augmented Generation (RAG) or document-based querying can now migrate to the native `/query` endpoint alongside the OpenAI-compatible API. This approach splits the process into two distinct steps:

{% stepper %}
{% step %}

#### Query your document collection

**Endpoint:** `POST https://inference.de-txl.ionos.com/collections/{collectionId}/query`

**Request Body:**

```json
{
  "query": "What are the supported models for AI Model Hub?",
  "limit": 5
}
```

**Response Example:**

```json
{
  "results": [
    {
      "documentId": "doc-123",
      "content": "IONOS AI Model Hub supports various models including GPT-OSS-120B, Llama 3, Mistral, and FLUX.1 for image generation...",
      "score": 0.92
    },
    {
      "documentId": "doc-456",
      "content": "The following embedding models are available: text-embedding-ada-002...",
      "score": 0.87
    }
  ]
}
```

{% endstep %}

{% step %}

#### Generate a response using retrieved context

**Endpoint:** `POST https://openai.inference.de-txl.ionos.com/v1/chat/completions`

**Request Body:**

```json
{
  "model": "openai/gpt-oss-120b",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant. Answer the user's question based only on the provided context. If the context doesn't contain enough information, say so.\n\nContext:\n---\nIONOS AI Model Hub supports various models including GPT-OSS-120B, Llama 3, Mistral, and FLUX.1 for image generation...\n\nThe following embedding models are available: text-embedding-ada-002...\n---"
    },
    {
      "role": "user",
      "content": "Which models does IONOS AI Model Hub offer?"
    }
  ],
  "max_tokens": 1000,
  "temperature": 0
}
```

{% endstep %}
{% endstepper %}


---

# 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/migration-guide.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.