Responses API

The IONOS CLOUD AI Model Hub provides a Responses API at /v1/responses as an alternative to standard chat completions for text generation. Instead of a message array, it accepts a flat list of input items and returns a list of typed output items. This structure isolates the model's reasoning and tool calls into distinct, readable objects rather than bundling them into a single message.

Supported models

All Large Language Models (LLMs) shown on the AI Model Hub Models can be used with the Responses API. Reasoning-capable models return an additional reasoning item, described in Read the output.

Overview

In this guide, you will learn how to generate responses using the Responses API. It targets developers who already understand:

• REST APIs.
• A programming language for interacting with REST endpoints, such as Python or Bash.

By the end, you will be able to:

1. Send a request to the Responses API and read the result.
2. Tell the output item types apart, including the model's reasoning.
3. Call a tool and return its result to the model.
4. Recognize which parts of the OpenAI Responses API are not available.

Getting started

Provide a model and an input. The input is either a string, for a single turn, or an array of items for a conversation.

Python

import requests

IONOS_API_TOKEN = "[YOUR API TOKEN HERE]"
MODEL_NAME = "[MODEL NAME HERE]"

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

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

Bash

#!/bin/bash

IONOS_API_TOKEN=[YOUR API TOKEN HERE]
MODEL_NAME=[MODEL NAME HERE]

BODY='{
    "model": "'"$MODEL_NAME"'",
    "input": "Name three cities on the Rhine."
}'

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

To send a conversation instead of a single string, pass an array of items with a role and content:

body = {
    "model": MODEL_NAME,
    "input": [
        {"role": "user", "content": "Name three cities on the Rhine."},
        {"role": "assistant", "content": "Cologne, Bonn, and Mainz."},
        {"role": "user", "content": "Which of those is furthest south?"}
    ]
}

Use instructions for a system prompt. It applies to the whole request and does not need a message of its own.

Read the output

The response carries an output array rather than a single message. Each item has a type, and the fields that apply depend on it:

type	What it holds
message	The answer. Its content array holds parts of type output_text.
reasoning	The model's reasoning trace, in parts of type reasoning_text. Only reasoning-capable models emit it.
function_call	A tool the model wants called, with name, arguments, and a call_id.

Read the answer by taking the output_text parts of the message item, rather than assuming the first item is the answer. A reasoning model puts its reasoning item first.

Python

answer = "".join(
    part["text"]
    for item in result["output"]
    if item["type"] == "message"
    for part in item.get("content", [])
    if part["type"] == "output_text"
)

The top-level status field can be completed, failed, or incomplete. If a response is cut short by the max_output_tokens limit, the status will be incomplete. Always check this status before processing the output.

Call a Tool

Tools are declared with the function definition at the top level of the tool object. This differs from standard chat completions, where the definition is nested under a function key.

tools = [{
    "type": "function",
    "name": "get_weather",
    "description": "Get the current weather for a city.",
    "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
    }
}]

body = {
    "model": MODEL_NAME,
    "input": "What is the weather in Berlin?",
    "tools": tools
}

When the model decides to call the tool, the output contains a function_call item:

{
  "type": "function_call",
  "call_id": "call_abc123",
  "name": "get_weather",
  "arguments": "{\"city\": \"Berlin\"}"
}

Run the function yourself, then send a second request containing the whole conversation: your original input, the function_call item exactly as you received it, and a function_call_output item carrying the result. Match the two with call_id.

body = {
    "model": MODEL_NAME,
    "input": [
        {"role": "user", "content": "What is the weather in Berlin?"},
        {"type": "function_call", "call_id": "call_abc123",
         "name": "get_weather", "arguments": "{\"city\": \"Berlin\"}"},
        {"type": "function_call_output", "call_id": "call_abc123",
         "output": "{\"temperature_c\": 18, \"conditions\": \"cloudy\"}"}
    ],
    "tools": tools
}

Note: The service keeps no conversation state, so every request must carry the full conversation, including any earlier tool calls, and their results.

Limitations

The following parts of the OpenAI Responses API are not available. Sending one of these fields returns a 400 error that names the field, so a request never appears to succeed while quietly ignoring what you asked for. For more information, see Error Codes.

Field	Instead
store, previous_response_id, conversation	Send the full conversation in the input field on each request and save the responses.
background	Omit it to receive the response synchronously.
stream	Omit it to receive the complete response.
Built-in tools such as web_search and file_search	Only function tools are available.

tool_choice accepts auto and none. required and named tool choice are not supported: depending on the model, such a request either returns an error or is answered without the forced call. Use auto and treat a tool call as something the model may or may not decide to make.

Image input depends on the model: input_image parts are accepted by models whose model card advertises image input, and return an error for models that do not. Pass the image as a publicly reachable URL or a base64 data URI:

{
  "role": "user",
  "content": [
    { "type": "input_text", "text": "What does this diagram show?" },
    { "type": "input_image", "image_url": "data:image/webp;base64,[BASE64 IMAGE DATA]" }
  ]
}

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

Important: Fields not listed in this guide are silently ignored rather than refused. If you pass a field that the standard OpenAI Responses API defines but this API omits, such as metadata or include, the request is accepted, but the field has no effect. Always refer to the API Reference before relying on a specific parameter.

What you learned

In this guide, you learned how to:

1. Send a request to the Responses API using a string or a conversation array.
2. Read the typed output items, including the reasoning trace.
3. Call a tool and return its result.
4. Recognize the unsupported fields and what to use instead.

For the equivalent workflow using the chat completions API, see Text Generation and Tool Calling.