Responses API (Recommandé)
Créez des réponses de modèle. Prend en charge l’entrée de texte et d’images, génère une sortie texte ou JSON. Prend en charge l’appel de fonctions (Tool Calling), les réponses en streaming et les conversations multi-tours.
Recommandé pour les nouveaux projets. Il s’agit de la nouvelle génération d’API publiée par OpenAI. Comparée à Chat Completions, elle présente les avantages suivants :
- Prompt Caching natif —
instructionsetinputsont séparés, les instructions système servent automatiquement de préfixe de cache, le taux de hit du cache est plus élevé pour la partie préfixe inchangée lors des conversations multi-tours, permettant d’économiser jusqu’à 50 % des frais de tokens d’entrée tout en réduisant la latence - Mode item structuré — Formats d’entrée/sortie plus clairs, prise en charge native du flux d’appel d’outils
- Événements de streaming plus riches — Types d’événements SSE granulaires, facilitant le rendu UI en temps réel
Endpoint
POST https://api.ofox.ai/v1/responsesParamètres de requête
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
model | string | ✅ | Identifiant du modèle, ex. openai/gpt-5.4-mini |
input | string | array | ✅ | Contenu d’entrée, soit une chaîne de texte simple, soit un tableau de messages structurés |
instructions | string | — | Instructions système (indépendantes de input, bénéficient automatiquement du Prompt Caching) |
stream | boolean | — | Activer la réponse en streaming SSE, par défaut false |
max_output_tokens | number | — | Nombre maximum de tokens à générer |
temperature | number | — | Température d’échantillonnage 0-2, par défaut 1 |
top_p | number | — | Paramètre d’échantillonnage nucleus |
tools | array | — | Définition des outils disponibles (Function Calling) |
tool_choice | string | object | — | Stratégie de sélection d’outils : auto, none ou outil spécifié |
truncation | string | — | Stratégie de troncature : auto troncature automatique / disabled erreur en cas de dépassement (par défaut) |
text | object | — | Configuration du format de génération de texte |
store | boolean | — | Stocker la réponse (par défaut true) |
metadata | object | — | Paires clé-valeur de métadonnées personnalisées |
provider | object | — | Extension OfoxAI : configuration de routage et repli |
Format Input
input prend en charge deux formats :
1. Chaîne simple — Passez directement le texte
{
"input": "Bonjour, présentez-vous brièvement"
}2. Tableau de messages structurés — Conversations multi-tours et entrée multimodale
interface InputItem {
type: 'message'
role: 'user' | 'assistant'
content: ContentPart[]
id?: string // Obligatoire pour les messages assistant
status?: 'completed' // Obligatoire pour les messages assistant
}
type ContentPart =
| { type: 'input_text'; text: string } // Entrée texte utilisateur
| { type: 'input_image'; image_url: string } // Entrée image
| { type: 'output_text'; text: string; annotations?: any[] } // Sortie texte assistantLorsque vous incluez des messages avec le rôle assistant dans une conversation multi-tours, les champs id et status sont obligatoires.
Responses API est conçue sans état, chaque requête doit transporter l’historique complet de la conversation.
Exemple de requête
cURL
curl https://api.ofox.ai/v1/responses \
-H "Authorization: Bearer $OFOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5.4-mini",
"input": "Expliquez ce qu'est un API Gateway",
"instructions": "Vous êtes un assistant technique utile, répondez en français.",
"max_output_tokens": 1024
}'Format de réponse
{
"id": "resp_abc123",
"object": "response",
"created_at": 1703123456,
"model": "openai/gpt-5.4-mini",
"status": "completed",
"output": [
{
"type": "message",
"id": "msg_def456",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "Un API Gateway (passerelle d'API) est un...",
"annotations": []
}
]
}
],
"usage": {
"input_tokens": 25,
"output_tokens": 150,
"total_tokens": 175
}
}Description des champs de réponse
| Champ | Type | Description |
|---|---|---|
id | string | Identifiant unique de la réponse, commençant par resp_ |
object | string | Valeur fixe "response" |
created_at | number | Horodatage de création (Unix en secondes) |
model | string | ID du modèle réellement utilisé |
status | string | Statut de la réponse : completed, failed, in_progress, cancelled |
output | array | Tableau d’items de sortie, contenant messages et appels d’outils |
usage | object | Statistiques d’utilisation des tokens |
Entrée de messages structurés
Utilisez un tableau de messages structurés pour les conversations multi-tours :
Python
response = client.responses.create(
model="openai/gpt-5.4-mini",
input=[
{
"type": "message",
"role": "user",
"content": [
{"type": "input_text", "text": "Quelle est la capitale de la France ?"}
]
},
{
"type": "message",
"role": "assistant",
"id": "msg_abc123",
"status": "completed",
"content": [
{"type": "output_text", "text": "La capitale de la France est Paris.", "annotations": []}
]
},
{
"type": "message",
"role": "user",
"content": [
{"type": "input_text", "text": "Combien d'habitants y vivent ?"}
]
}
]
)
print(response.output_text)Réponse en streaming
Définissez stream: true pour activer la réponse en streaming SSE :
Python
stream = client.responses.create(
model="openai/gpt-5.4-mini",
input="Racontez-moi une blague sur la programmation",
stream=True
)
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)Types d’événements en streaming
La réponse en streaming envoie les événements suivants via SSE :
data: {"type":"response.created","response":{"id":"resp_abc123","object":"response","status":"in_progress"}}
data: {"type":"response.output_item.added","output_index":0,"item":{"type":"message","id":"msg_def456","role":"assistant","status":"in_progress","content":[]}}
data: {"type":"response.content_part.added","output_index":0,"content_index":0,"part":{"type":"output_text","text":""}}
data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"Bon"}
data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"jour"}
data: {"type":"response.output_item.done","output_index":0,"item":{"type":"message","id":"msg_def456","role":"assistant","status":"completed","content":[{"type":"output_text","text":"Bonjour..."}]}}
data: {"type":"response.completed","response":{"id":"resp_abc123","object":"response","status":"completed","usage":{"input_tokens":12,"output_tokens":45,"total_tokens":57}}}
data: [DONE]| Type d’événement | Description |
|---|---|
response.created | Objet réponse créé |
response.output_item.added | Nouvel item de sortie ajouté |
response.content_part.added | Nouveau fragment de contenu ajouté |
response.output_text.delta | Incrément de texte (sortie token par token) |
response.output_item.done | Item de sortie terminé |
response.completed | Réponse entièrement terminée |
response.function_call_arguments.delta | Incrément des arguments d’appel de fonction |
response.function_call_arguments.done | Arguments d’appel de fonction terminés |
Function Calling
Responses API prend en charge nativement l’appel d’outils :
Python
response = client.responses.create(
model="openai/gpt-5.4-mini",
input="Quel temps fait-il aujourd'hui à Paris ?",
tools=[
{
"type": "function",
"name": "get_weather",
"description": "Obtenir la météo actuelle d'une ville donnée",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Nom de la ville, ex. Paris"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location"]
}
}
],
tool_choice="auto"
)
# Traiter les appels d'outils
for item in response.output:
if item.type == "function_call":
print(f"Appel de fonction : {item.name}")
print(f"Arguments : {item.arguments}")Format de réponse d’appel d’outil
Lorsque le modèle appelle un outil, output contient un item de type function_call :
{
"id": "resp_abc123",
"object": "response",
"status": "completed",
"output": [
{
"type": "function_call",
"id": "fc_abc123",
"call_id": "call_xyz789",
"name": "get_weather",
"arguments": "{\"location\":\"Paris\",\"unit\":\"celsius\"}"
}
],
"usage": {
"input_tokens": 45,
"output_tokens": 25,
"total_tokens": 70
}
}Soumettre les résultats d’outils
Renvoyez les résultats d’exécution des outils au modèle, en incluant la chaîne d’appel complète dans input :
# Deuxième requête : soumettre les résultats d'outils
response = client.responses.create(
model="openai/gpt-5.4-mini",
input=[
{
"type": "message",
"role": "user",
"content": [{"type": "input_text", "text": "Quel temps fait-il aujourd'hui à Paris ?"}]
},
{
"type": "function_call",
"id": "fc_abc123",
"call_id": "call_xyz789",
"name": "get_weather",
"arguments": "{\"location\":\"Paris\",\"unit\":\"celsius\"}"
},
{
"type": "function_call_output",
"id": "fco_abc123",
"call_id": "call_xyz789",
"output": "{\"temperature\":\"22°C\",\"condition\":\"ensoleillé\"}"
}
]
)
print(response.output_text)
# => "Il fait beau aujourd'hui à Paris, avec une température de 22°C, idéal pour les activités en plein air."Options Tool Choice
| Valeur | Description |
|---|---|
"auto" | Le modèle décide lui-même s’il appelle un outil (par défaut) |
"none" | Interdire les appels d’outils |
{"type": "function", "name": "tool_name"} | Forcer l’appel d’un outil spécifié |
Comparaison avec Chat Completions
| Caractéristique | Chat Completions | Responses API |
|---|---|---|
| Endpoint | /v1/chat/completions | /v1/responses |
| Format d’entrée | Tableau messages | Chaîne input ou tableau d’items structurés |
| Instructions système | Message role: "system" | Paramètre instructions (cache indépendant) |
| Prompt Caching | Instructions système mélangées dans messages, préfixe de cache instable | instructions passées indépendamment, cache automatique, taux de hit plus élevé |
| Format de sortie | choices[0].message.content | output[0].content[0].text ou output_text |
| Appel d’outils | tool_calls dans message | Item de sortie function_call indépendant |
| Résultat d’outil | Message role: "tool" | Item d’entrée function_call_output |
| Événements de streaming | chat.completion.chunk | Types d’événements structurés (response.*) |
| Champs de tokens | prompt_tokens / completion_tokens | input_tokens / output_tokens |
Les deux API sont utilisables en production. Si vous avez déjà une intégration Chat Completions, aucune migration n’est nécessaire. Responses API est recommandée pour les nouveaux projets, surtout pour les scénarios nécessitant des flux d’appel d’outils complexes ou des appels à haute fréquence (qui peuvent pleinement tirer parti du cache pour réduire les coûts). Voir le guide d’appel de fonctions.