Aide-mémoire API OpenAI

La Responses API est l’interface principale pour les nouveaux travaux. Chat Completions est hérité — elle fonctionne toujours, mais c’est dans la Responses API que vivent l’état de conversation, le mode background, les reasoning items et la surface d’outils intégrés, alors développez sur elle. Tout ce qui figure ici reflète la surface de septembre 2026 décrite dans les pistes OpenAI ; revérifiez les formes auprès de developers.openai.com/api/docs.

Requête minimale

from openai import OpenAI

client = OpenAI()  # lit OPENAI_API_KEY

resp = client.responses.create(
    model="gpt-5.6-terra",
    input="Donne trois risques du verrouillage fournisseur.",
    reasoning={"effort": "medium"},
)
print(resp.output_text)

import OpenAI from 'openai';

const client = new OpenAI(); // lit OPENAI_API_KEY

const resp = await client.responses.create({
  model: 'gpt-5.6-terra',
  input: 'Donne trois risques du verrouillage fournisseur.',
  reasoning: { effort: 'medium' },
});
console.log(resp.output_text);

input accepte une chaîne ou un tableau d’items typés (messages, sorties d’outils, fichiers). output_text est un agrégat de commodité ; le contenu de référence se trouve dans le tableau output d’items.

Champs de requête

Forme de la réponse

{
  "id": "resp_01",
  "object": "response",
  "model": "gpt-5.6-terra",
  "status": "completed",
  "output": [
    { "type": "reasoning", "id": "rs_01", "summary": [] },
    { "type": "message", "role": "assistant",
      "content": [{ "type": "output_text", "text": "The notice period is 60 days." }] }
  ],
  "usage": {
    "input_tokens": 1200,
    "input_tokens_details": { "cached_tokens": 1024 },
    "output_tokens": 42,
    "output_tokens_details": { "reasoning_tokens": 18 },
    "total_tokens": 1242
  }
}

status — branchez dessus

output_tokens_details.reasoning_tokens sont facturés comme de la sortie — un effort élevé y dépense de l’argent réel.

État de conversation

Deux façons de porter l’état ; ne les mélangez pas pour le même thread.

first = client.responses.create(model="gpt-5.6-terra", input="Je m'appelle Dana.", store=True)
second = client.responses.create(
    model="gpt-5.6-terra",
    input="Quel est mon nom ?",
    previous_response_id=first.id,
)

Streaming

Les server-sent events émettent des événements sémantiques, pas des deltas de tokens bruts — branchez sur le type de l’événement.

stream = client.responses.create(
    model="gpt-5.6-terra", input="Écris un haïku sur la latence.", stream=True,
)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        print("\n", event.response.usage)

const stream = await client.responses.create({
  model: 'gpt-5.6-terra', input: 'Écris un haïku sur la latence.', stream: true,
});
for await (const event of stream) {
  if (event.type === 'response.output_text.delta') process.stdout.write(event.delta);
  else if (event.type === 'response.completed') console.log('\n', event.response.usage);
}

Types d’événements courants : response.created, response.output_item.added, response.output_text.delta, response.function_call_arguments.delta, response.output_item.done, response.completed, response.error. Les arguments d’appel d’outil arrivent en fragments — mettez-les en tampon et ne les analysez qu’au done.

Mode background

Pour les jobs longs, démarrez avec background: true, récupérez un id immédiatement, puis interrogez ou abonnez-vous à un webhook.

job = client.responses.create(model="gpt-6-astra", input=big_task, background=True)
# plus tard
resp = client.responses.retrieve(job.id)
while resp.status in ("queued", "in_progress"):
    time.sleep(2)
    resp = client.responses.retrieve(job.id)

Le mode background s’associe aux webhooks pour ne pas maintenir une connexion ouverte pendant des minutes. C’est l’analogue, au niveau de l’API, des sessions durables de l’Agents API pour du travail long ponctuel.

Sorties structurées

schema = {
  "type": "object",
  "properties": {
    "vendor": {"type": "string"},
    "total": {"type": "number"},
    "currency": {"type": "string", "enum": ["USD", "EUR", "GBP"]},
  },
  "required": ["vendor", "total", "currency"],
  "additionalProperties": False,
}
resp = client.responses.create(
    model="gpt-5.6-terra",
    input="Extract the invoice: Acme, 1240.50 USD.",
    text={"format": {"type": "json_schema", "name": "invoice", "schema": schema, "strict": True}},
)

strict: true contraint la génération au schéma. Validez tout de même en aval et réessayez en réinjectant l’erreur précise — une sortie structurée garantit la forme, pas l’exactitude métier.

Function calling

tools = [{
  "type": "function",
  "name": "get_order",
  "description": "Look up one order by ID. Returns status and ETA.",
  "parameters": {
    "type": "object",
    "properties": {"order_id": {"type": "string"}},
    "required": ["order_id"], "additionalProperties": False,
  },
  "strict": True,
}]

resp = client.responses.create(model="gpt-5.6-terra", input="Where is ORD-12345?", tools=tools)
# resp.output contient un item function_call ; exécutez-le, puis renvoyez la sortie :
followup = client.responses.create(
    model="gpt-5.6-terra",
    previous_response_id=resp.id,
    input=[{"type": "function_call_output", "call_id": call_id,
            "output": '{"status":"shipped","eta":"2026-09-17"}'}],
)

La boucle : le modèle émet un item function_call → vous l’exécutez → vous renvoyez un item function_call_output (référençant previous_response_id ou en renvoyant l’état) → répétez jusqu’à un simple message.

Reasoning effort

client.responses.create(model="gpt-5.6-luna", input=simple_transform, reasoning={"effort": "none"})
client.responses.create(model="gpt-6-astra", input=hard_problem, reasoning={"effort": "xhigh"})

Utilisez l’effort le plus bas qui donne le résultat. Les tokens de raisonnement sont facturés comme de la sortie. Il n’y a pas de correspondance exacte d’effort GPT-5.5 → 5.6 — reréglez par modèle. Voir la gamme de modèles.

Entrées de fichiers

f = client.files.create(file=open("contract.pdf", "rb"), purpose="user_data")
resp = client.responses.create(
    model="gpt-5.6-terra",
    input=[{"role": "user", "content": [
        {"type": "input_file", "file_id": f.id},
        {"type": "input_text", "text": "Summarise the termination clause."},
    ]}],
)

Les images utilisent input_image avec un file_id ou une URL. Téléversez une fois et référencez par id à travers de nombreux appels plutôt que de re-téléverser.

Compaction et comptage de tokens

• Compaction résume les tours plus anciens côté serveur afin qu’une longue session reste dans la fenêtre de contexte tout en préservant le fil narratif. C’est le levier côté API contre la croissance non bornée du contexte ; l’Agents API applique automatiquement la synthèse de contexte au sein d’une session.
• Comptage de tokens — inspectez usage.input_tokens, usage.output_tokens, input_tokens_details.cached_tokens (hits de cache) et output_tokens_details.reasoning_tokens (raisonnement facturé) sur chaque réponse pour garder le coût honnête.

Outils intégrés

Fonctionnalités de qualité et de coût

Confirmez les hits de cache via usage.input_tokens_details.cached_tokens ; le caching réduit davantage le coût que la pression sur les rate limits.

Codes d’erreur et politique de réessai

Utilisez un backoff exponentiel avec jitter, respectez retry-after, journalisez l’id de requête depuis les en-têtes de réponse, et passez une clé d’idempotence sur les requêtes à effet de bord afin qu’un réessai n’agisse pas deux fois.

import time, random
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI()
RETRYABLE = {429, 500, 503}

def call_with_retry(**params):
    for attempt in range(6):
        try:
            return client.responses.create(**params)
        except RateLimitError as e:
            wait = float(e.response.headers.get("retry-after", 0)) or min(60, 2 ** attempt)
            time.sleep(wait + random.uniform(0, 0.5))
        except APIStatusError as e:
            if e.status_code in RETRYABLE:
                time.sleep(min(60, 2 ** attempt) + random.uniform(0, 0.5))
            else:
                raise
    raise RuntimeError("exhausted retries")

Limites de débit et de dépense

• Rate limits — s’appliquent aux requêtes et aux tokens par minute ; vous atteignez celle qui contraint en premier. Surveillez les en-têtes de réponse de rate limit et régulez avant un 429 plutôt qu’après.
• Spend limits — plafonnent le coût par période au niveau org/projet ; les atteindre renvoie une erreur, pas un arrêt silencieux.
• Gérez les deux depuis le dashboard ; imposez des budgets au niveau projet afin qu’un job emballé ne puisse épuiser l’org.

Faits clés à mémoriser

• La Responses API est primaire ; Chat Completions est hérité pour les nouveaux travaux.
• État de conversation : store: true + previous_response_id (côté serveur) ou renvoyer input (côté client) — pas les deux.
• Le streaming émet des événements sémantiques ; branchez sur le type d’événement, mettez en tampon les fragments d’args d’outil.
• La sortie structurée garantit la forme (strict: true), pas l’exactitude métier — validez et réessayez tout de même.
• Ne réessayez que 429/5xx avec backoff et retry-after ; corrigez les 4xx. Utilisez des clés d’idempotence sur les appels à effet de bord.
• L’entrée mise en cache, Batch, Flex, Fast mode et predicted outputs sont les leviers de coût/latence.