For AI agents: the complete documentation index is available at https://docs.ovhcloud.com/fr/llms.txt, the full documentation bundle is available at https://docs.ovhcloud.com/fr/llms-full.txt, and this page is available as Markdown at https://docs.ovhcloud.com/fr/guides/public-cloud/ai-machine-learning/ai-endpoints-responses-api.md.

AI Endpoints - API Responses

Voir en Markdown

Découvrez comment utiliser AI Endpoints avec l'API Responses

Info

AI Endpoints est couvert par les Conditions particulières OVHcloud Public Cloud (voir l’Annexe 10 – « Conditions spécifiques – AI Endpoints »).

Introduction

AI Endpoints est une plateforme serverless proposée par OVHcloud qui offre un accès simplifié à une sélection de modèles d'IA pré-entraînés, mondialement reconnus.

L'API Responses (/v1/responses) est la route compatible OpenAI la plus récente. Comme v1/chat/completions, elle peut être utilisée pour la génération de texte, les conversations multi-tours, l'appel d'outils/de fonctions, les sorties structurées et les entrées visuelles (sur les modèles compatibles).

La différence essentielle est que /v1/responses est conçue comme la base des futures capacités et comportements agentiques, introduisant des fonctionnalités avancées telles que la statefulness et les outils intégrés (built-in tools).

Warning

La route v1/responses a été ajoutée récemment. Certains paramètres et comportements peuvent varier selon les modèles. Pour connaître les limites à jour, consultez la section Limites de l'endpoint et vérifiez les capacités du modèle dans le Catalogue.

Objectif

Cette documentation présente un aperçu de la route v1/responses sur AI Endpoints, notamment :

  • Les requêtes de base et les champs de réponse courants
  • Des exemples d'utilisation en Python, JavaScript et cURL
  • Une explication détaillée des paramètres les plus importants
  • Les limites connues de la plateforme

Prérequis

Les exemples fournis dans ce guide peuvent être utilisés avec l'un des environnements suivants :

Python
JavaScript
cURL

Un environnement Python avec le client openai.

pip install openai

Authentification et limitation du débit

La plupart des exemples fournis dans ce guide sont authentifiés et supposent que AI_ENDPOINT_API_KEY est définie afin d'éviter les problèmes de limitation de débit. Si vous souhaitez activer l'authentification avec votre propre token, spécifiez votre propre clé API dans l'environnement (export AI_ENDPOINT_API_KEY='your_api_key').

Suivez les instructions du guide AI Endpoints - Premiers pas pour plus d'informations sur l'authentification.

Démarrage rapide

Warning

Sur AI Endpoints, la statefulness pour v1/responses n'est actuellement pas gérée. Pour éviter tout comportement inattendu et rester cohérent avec l'implémentation actuelle de la plateforme, envoyez toujours store: false.

Requête de base (entrée texte)

La requête la plus simple consiste en un input textuel unique.

Python
JavaScript
cURL
import os
from openai import OpenAI

api_key = os.environ["AI_ENDPOINT_API_KEY"]  # export AI_ENDPOINT_API_KEY='your_api_key'

client = OpenAI(
    base_url="https://oai.endpoints.kepler.ai.cloud.ovh.net/v1",
    api_key=api_key,
)

response = client.responses.create(
    model="gpt-oss-20b",
    input="Explain RAG in one paragraph.",
    store=False,
)

print(response.output_text)

Conversations multi-tours

Pour créer une conversation multi-tours, conservez l'historique complet de la conversation de votre côté et envoyez-le sous forme de liste input à chaque requête.

Info

Sur AI Endpoints, la statefulness pour v1/responses n'est actuellement pas disponible. Cela signifie que vous devez toujours envoyer l'historique complet au sein de input.

Conversation gérée côté client (liste input)

Python
JavaScript
cURL
import os
from openai import OpenAI

api_key = os.environ["AI_ENDPOINT_API_KEY"]  # export AI_ENDPOINT_API_KEY='your_api_key'

client = OpenAI(
  base_url="https://oai.endpoints.kepler.ai.cloud.ovh.net/v1",
  api_key=api_key,
)

resp = client.responses.create(
  model="gpt-oss-20b",
  store=False,
  input=[
    {"type": "message", "role": "user", "content": "My name is Stéphane."},
    {"type": "message", "role": "assistant", "content": "Hello Stéphane! How can I help?"},
    {"type": "message", "role": "user", "content": "What is my name?"},
  ],
)

print(resp.output_text)

Fournir un system prompt

Vous pouvez fournir des instructions au niveau système de deux façons :

  • instructions (simple et compact)
  • Un élément role: "system" au sein d'une liste input (utile lorsque vous envoyez déjà une liste pour le multi-tours)

Option 1 : instructions

Python
JavaScript
cURL
import os
from openai import OpenAI

api_key = os.environ["AI_ENDPOINT_API_KEY"]  # export AI_ENDPOINT_API_KEY='your_api_key'

client = OpenAI(
  base_url="https://oai.endpoints.kepler.ai.cloud.ovh.net/v1",
  api_key=api_key,
)

resp = client.responses.create(
  model="gpt-oss-20b",
  instructions="You are a technical writer. Answer in British English.",
  input="Write a short definition of embeddings.",
  store=False,
)

print(resp.output_text)

Option 2 : role: "system" dans une liste input

Python
JavaScript
cURL
import os
from openai import OpenAI

api_key = os.environ["AI_ENDPOINT_API_KEY"]  # export AI_ENDPOINT_API_KEY='your_api_key'

client = OpenAI(
  base_url="https://oai.endpoints.kepler.ai.cloud.ovh.net/v1",
  api_key=api_key,
)

resp = client.responses.create(
  model="gpt-oss-20b",
  store=False,
  input=[
    {"type": "message", "role": "system", "content": "You are a technical writer. Answer in British English."},
    {"type": "message", "role": "user", "content": "Write a short definition of embeddings."}
  ],
)

print(resp.output_text)

Streaming (stream: true)

Si stream est activé, l'API renvoie des Server-Sent Events (SSE) avec une sortie incrémentale. Ceci est utile pour les interfaces de chat et les CLI.

Python
JavaScript
cURL
import os
from openai import OpenAI

api_key = os.environ["AI_ENDPOINT_API_KEY"]  # export AI_ENDPOINT_API_KEY='your_api_key'

client = OpenAI(
  base_url="https://oai.endpoints.kepler.ai.cloud.ovh.net/v1",
  api_key=api_key,
)

stream = client.responses.create(
  model="gpt-oss-20b",
  input="Write a haiku about cloud computing.",
  stream=True,
  store=False,
)

for event in stream:
  # The exact event fields can vary by SDK version.
  # A common approach is to print any incremental output text.
  delta = getattr(event, "delta", None)
  if delta:
    print(delta, end="", flush=True)

Sorties structurées (text.format)

Certains modèles prennent en charge l'imposition d'un format de sortie structuré. Ceci est utile lorsque vous avez besoin de réponses prévisibles et lisibles par une machine.

L'objet text.format peut être utilisé dans ces modes (selon le modèle) :

  • {"type": "text"} Format textuel par défaut.

  • {"type": "json_schema", "name": "...", "schema": { ... }} Mode avec schéma imposé : le modèle renvoie un JSON conforme à votre JSON Schema.

Exemple : extraction avec schéma JSON

Python
JavaScript
cURL
import json
import os
from openai import OpenAI

api_key = os.environ["AI_ENDPOINT_API_KEY"]  # export AI_ENDPOINT_API_KEY='your_api_key'

client = OpenAI(
  base_url="https://oai.endpoints.kepler.ai.cloud.ovh.net/v1",
  api_key=api_key,
)

resp = client.responses.create(
  model="gpt-oss-20b",
  store=False,
  input=[
    {
      "type": "message",
      "role": "system",
      "content": "You are a helpful extractor. Return only valid JSON.",
    },
    {
      "type": "message",
      "role": "user",
      "content": "Extract the company name and the contract start date from: Contract starts on 2026-01-12 with OVHcloud.",
    },
  ],
  text={
    "format": {
      "type": "json_schema",
      "name": "contract_data",
      "description": "Extract contract fields",
      "schema": {
        "type": "object",
        "properties": {
          "company": {"type": "string"},
          "start_date": {"type": "string"},
        },
        "required": ["company", "start_date"],
        "additionalProperties": False,
      },
      "strict": False,
    }
  },
)

# `output_text` is typically the JSON string generated by the model.
data = json.loads(resp.output_text)
print(json.dumps(data, indent=2))

Appel de fonctions (tools)

L'appel de fonctions (function calling / tool calling) permet au modèle de demander à votre application d'exécuter une fonction. Vous déclarez la signature de la fonction dans tools, le modèle peut émettre des appels d'outils, puis vous les exécutez et renvoyez les résultats afin que le modèle puisse produire une réponse finale.

Info

Sur OVHcloud AI Endpoints, pour v1/responses, les outils intégrés (built-in tools) ne sont pas pris en charge (par exemple web_search, file_search, computer_use, code_execution, ...). Seuls les outils de fonction personnalisés (custom function tools) sont pris en charge.

Workflow de bout en bout (recommandé)

Le déroulement est similaire au guide d'appel de fonctions de v1/chat/completions :

  1. Appeler le modèle avec tools.
  2. Si le modèle renvoie un appel d'outil : exécuter l'outil dans votre application.
  3. Envoyer une nouvelle requête incluant le résultat de l'outil dans input, puis lire la réponse finale.

Voici un exemple minimal de bout en bout.

Python
JavaScript
cURL (déclaration de l'outil uniquement)
import json
import os
from openai import OpenAI

api_key = os.environ["AI_ENDPOINT_API_KEY"]  # export AI_ENDPOINT_API_KEY='your_api_key'

client = OpenAI(
  base_url="https://oai.endpoints.kepler.ai.cloud.ovh.net/v1",
  api_key=api_key,
)

# 1) Tool implementation (your code)
def get_vat_rate(country: str) -> float:
  if country.lower() in ["france", "fr"]:
    return 0.20
  raise ValueError("Unsupported country")

TOOLS = [
  {
    "type": "function",
    "name": "get_vat_rate",
    "strict": False,
    "description": "Return the VAT rate for a given country.",
    "parameters": {
      "type": "object",
      "properties": {"country": {"type": "string"}},
      "required": ["country"],
      "additionalProperties": False,
    },
  }
]

# 2) First call: let the model decide whether to call the tool
input_items = [
  {"type": "message", "role": "user", "content": "What is the VAT rate in France? If needed, call the tool."}
]

first = client.responses.create(
  model="gpt-oss-20b",
  store=False,
  input=input_items,
  tools=TOOLS,
)

# 3) If a tool call is present, execute it and send the tool result back
tool_calls = getattr(first, "tool_calls", None) or []
if tool_calls:
  call = tool_calls[0]
  args = json.loads(call.function.arguments)
  result = get_vat_rate(**args)

  input_items.extend([
    {
      "type": "message",
      "role": "assistant",
      "tool_calls": [
        {
          "id": call.id,
          "type": "function",
          "function": {"name": call.function.name, "arguments": call.function.arguments},
        }
      ],
    },
    {
      "type": "message",
      "role": "tool",
      "tool_call_id": call.id,
      "name": call.function.name,
      "content": json.dumps({"vat_rate": result}),
    },
  ])

  final = client.responses.create(
    model="gpt-oss-20b",
    store=False,
    input=input_items,
    tools=TOOLS,
  )

  print(final.output_text)
else:
  # The model might answer directly without calling a tool.
  print(first.output_text)

Modèles de vision (entrées image)

Certains modèles acceptent des entrées image. Lorsque c'est pris en charge, vous pouvez transmettre un tableau input contenant un mélange de parties texte et image.

Warning

OVHcloud AI Endpoints ne prend actuellement pas en charge la récupération d'images depuis des URLs distantes pour input_image. Fournissez les images sous forme de data URL encodée en base64 (par exemple : data:image/png;base64,...).

Python
JavaScript
cURL
import base64
import mimetypes
import os
from openai import OpenAI

api_key = os.environ["AI_ENDPOINT_API_KEY"]  # export AI_ENDPOINT_API_KEY='your_api_key'

client = OpenAI(
  base_url="https://oai.endpoints.kepler.ai.cloud.ovh.net/v1",
  api_key=api_key,
)

def to_data_url(image_path: str) -> str:
  mime_type, _ = mimetypes.guess_type(image_path)
  if mime_type is None:
    mime_type = "image/jpeg"

  with open(image_path, "rb") as f:
    b64 = base64.b64encode(f.read()).decode("utf-8")

  return f"data:{mime_type};base64,{b64}"

resp = client.responses.create(
  model="Qwen2.5-VL-72B-Instruct",
  store=False,
  input=[
    {
      "type": "message",
      "role": "user",
      "content": [
        {"type": "input_text", "text": "Describe this image."},
        {"type": "input_image", "image_url": to_data_url("sample.jpg")},
      ],
    }
  ],
)

print(resp.output_text)
Warning

Les entrées image ne sont prises en charge que par les modèles compatibles avec la vision. Consultez le Catalogue et les pages de chaque modèle pour connaître les types de contenu pris en charge.

Modèles de raisonnement (reasoning)

Certains modèles exposent des contrôles liés au raisonnement. Lorsque c'est pris en charge, un objet reasoning peut être utilisé pour ajuster l'effort de raisonnement et/ou récupérer les métadonnées de raisonnement.

Info

Les paramètres de raisonnement sont spécifiques à chaque modèle. Si vous obtenez des erreurs de validation, retirez reasoning ou passez à un modèle compatible avec le raisonnement.

Python
JavaScript
cURL
import os
from openai import OpenAI

api_key = os.environ["AI_ENDPOINT_API_KEY"]  # export AI_ENDPOINT_API_KEY='your_api_key'

client = OpenAI(
  base_url="https://oai.endpoints.kepler.ai.cloud.ovh.net/v1",
  api_key=api_key,
)

resp = client.responses.create(
  model="gpt-oss-20b",
  store=False,
  input="Compute 17*23 and explain the steps.",
  reasoning={"effort": "medium"},
)

print(resp.output_text)

Limites de l'endpoint

L'endpoint v1/responses est encore en cours de développement et toutes les fonctionnalités ne sont pas forcément disponibles. Si vous êtes intéressé par des fonctionnalités spécifiques que vous souhaiteriez nous voir prioriser, n'hésitez pas à nous le faire savoir sur le serveur Discord OVHcloud.

Statefulness

La statefulness n'est actuellement pas gérée sur AI Endpoints pour la route v1/responses.

  • Envoyez toujours store: false pour éviter tout comportement inattendu (la spécification OpenAI utilise store: true par défaut).
  • previous_response_id n'est actuellement pas pris en charge.
  • Pour implémenter le multi-tours, envoyez l'historique complet dans la liste input.

Outils intégrés (built-in tools)

Les outils intégrés compatibles OpenAI ne sont actuellement pas pris en charge sur OVHcloud AI Endpoints pour v1/responses (par exemple : web_search, file_search, computer_use, code_execution, les outils distants avec type: "mcp", etc.).

Si vous avez besoin d'appel d'outils, seuls les outils de fonction personnalisés (custom function tools) sont pris en charge : déclarez-les explicitement dans le tableau tools (voir Appel de fonctions (tools)).

Problèmes connus / paramètres non pris en charge

Les paramètres suivants peuvent être non pris en charge, ignorés, ou implémentés de manière incohérente selon le modèle/backend :

  • Les résumés de raisonnement et certains champs de métadonnées de raisonnement
  • background
  • include
  • max_tool_calls
  • prompt_cache_key
  • truncation
  • Les prompts réutilisables (paramètre prompt)
  • safety_identifier
  • service_tier
  • stream_options
  • user
  • verbosity

Limites spécifiques à certains modèles que vous pourriez rencontrer :

  • Certains modèles ne sont pas compatibles avec la route v1/responses
  • La prise en charge de l'objet JSON / du JSON Schema varie (sorties structurées)
  • L'appel d'outils peut ne pas être pris en charge, ou les valeurs de tool_choice peuvent être restreintes (par exemple : absence de prise en charge des modes autres que auto)
  • Certains modèles ne prennent pas en charge les system prompts / instructions
  • Les conversations multi-tours peuvent se comporter de manière inattendue lorsqu'elles combinent sorties structurées, instructions système, ou paramètres de raisonnement
  • Les sorties structurées avec streaming peuvent ne pas être prises en charge
  • logprobs peut ne pas être pris en charge sur certains modèles
  • Les appels d'outils en parallèle peuvent ne pas être pris en charge sur certains modèles
  • Les entrées image ne sont prises en charge que par les modèles compatibles avec la vision

Conclusion

L'API Responses offre un moyen unifié d'interagir avec des LLM sur AI Endpoints d'OVHcloud, couvrant la génération de texte de base ainsi que des cas d'usage avancés tels que les conversations multi-tours, le streaming, les sorties structurées, l'appel de fonctions, et les entrées visuelles (selon le modèle).

Pour maximiser la compatibilité, vérifiez toujours les fonctionnalités prises en charge pour le modèle choisi dans le catalogue AI Endpoints, et envisagez de revenir à v1/chat/completions lorsqu'une fonctionnalité n'est pas disponible sur v1/responses.

Aller plus loin

Parcourez la documentation AI Endpoints complète pour découvrir d'autres guides et tutoriels.

Si vous avez besoin d'une formation ou d'une assistance technique pour la mise en oeuvre de nos solutions, contactez votre commercial ou cliquez sur ce lien pour obtenir un devis et demander une analyse personnalisée de votre projet à nos experts de l’équipe Professional Services.

Nous voulons vos retours !

N’hésitez pas à nous faire part de vos questions, retours et suggestions pour améliorer le service :

Cette page vous a-t-elle aidé ?