David-Li0406/skill-openai-api-complet

API OpenAI - Guide Complet

Version : Prête pour la production ✅ Package : [email protected] Dernière mise à jour : 2026-02-27

---

Statut

✅ Prêt pour la production :

• ✅ API Chat Completions (GPT-5, GPT-4o, GPT-4 Turbo)
• ✅ API Embeddings (text-embedding-3-small, text-embedding-3-large)
• ✅ API Images (Génération DALL-E 3 + édition GPT-Image-1)
• ✅ API Audio (Transcription Whisper + TTS avec 11 voix)
• ✅ API Moderation (11 catégories de sécurité)
• ✅ Modèles de streaming (SSE)
• ✅ Appel de fonctions / Outils
• ✅ Sorties structurées (schémas JSON)
• ✅ Vision (GPT-4o)
• ✅ Approches SDK Node.js et fetch

---

Table des Matières

1. Démarrage Rapide
2. API Chat Completions
3. Modèles de la Série GPT-5
4. Modèles de Streaming
5. Appel de Fonctions
6. Sorties Structurées
7. Vision (GPT-4o)
8. API Embeddings
9. API Images
10. API Audio
11. API Moderation
12. Gestion des Erreurs
13. Limites de Débit
14. Bonnes Pratiques de Production
15. Relation avec openai-responses

---

Démarrage Rapide

Installation

npm install [email protected]

Configuration de l'Environnement

export OPENAI_API_KEY="sk-..."

Ou créez un fichier .env :

OPENAI_API_KEY=sk-...

Première Chat Completion (SDK Node.js)

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const completion = await openai.chat.completions.create({
  model: 'gpt-5',
  messages: [
    { role: 'user', content: 'Quelles sont les trois lois de la robotique ?' }
  ],
});

console.log(completion.choices[0].message.content);

Première Chat Completion (Fetch - Cloudflare Workers)

const response = await fetch('https://api.openai.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${env.OPENAI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-5',
    messages: [
      { role: 'user', content: 'Quelles sont les trois lois de la robotique ?' }
    ],
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);

---

API Chat Completions

Point de terminaison : POST /v1/chat/completions

L'API Chat Completions est l'interface principale pour interagir avec les modèles de langage d'OpenAI. Elle prend en charge l'IA conversationnelle, la génération de texte, l'appel de fonctions, les sorties structurées et les capacités de vision.

Modèles Pris en Charge

Série GPT-5 (Sortie août 2025)

• gpt-5 : Modèle de raisonnement complet avec des capacités avancées
• gpt-5-mini : Alternative rentable avec de bonnes performances
• gpt-5-nano : Variante la plus petite/rapide pour les tâches simples

Série GPT-4o

• gpt-4o : Modèle multimodal avec capacités de vision
• gpt-4-turbo : Variante rapide de GPT-4

Série GPT-4

• gpt-4 : Modèle GPT-4 original

Structure de Requête de Base

{
  model: string,              // Modèle à utiliser (ex. "gpt-5")
  messages: Message[],        // Historique de la conversation
  reasoning_effort?: string,  // GPT-5 uniquement : "minimal" | "low" | "medium" | "high"
  verbosity?: string,         // GPT-5 uniquement : "low" | "medium" | "high"
  temperature?: number,       // NON supporté par GPT-5
  max_tokens?: number,        // Nombre maximum de tokens à générer
  stream?: boolean,           // Activer le streaming
  tools?: Tool[],             // Outils d'appel de fonctions
}

Structure de Réponse

{
  id: string,                 // ID de completion unique
  object: "chat.completion",
  created: number,            // Timestamp Unix
  model: string,              // Modèle utilisé
  choices: [{
    index: number,
    message: {
      role: "assistant",
      content: string,        // Texte généré
      tool_calls?: ToolCall[] // Si appel de fonction
    },
    finish_reason: string     // "stop" | "length" | "tool_calls"
  }],
  usage: {
    prompt_tokens: number,
    completion_tokens: number,
    total_tokens: number
  }
}

Rôles des Messages et Conversations Multi-tours

Trois rôles : system (comportement), user (entrée), assistant (réponses du modèle).

Important : L'API est sans état - envoyez l'historique complet de la conversation à chaque requête. Pour les conversations avec état, utilisez le skill openai-responses.

---

Modèles de la Série GPT-5

Les modèles GPT-5 (sortie août 2025) introduisent des contrôles de raisonnement et de verbosité :

GPT-5.1 (Sortie le 13 novembre 2025)

Dernier modèle avec des améliorations majeures :

• gpt-5.1 : Raisonnement adaptatif qui fait varier dynamiquement le temps de réflexion
• Mise en cache étendue des prompts sur 24 heures : Requêtes de suivi plus rapides à moindre coût
• Nouveaux outils développeur : apply_patch (édition de code), shell (exécution de commandes)

CHANGEMENT IMPORTANT : GPT-5.1 utilise par défaut reasoning_effort: 'none' (contrairement à GPT-5 qui utilise 'medium'). Mettez à jour votre code lors de la migration !

Paramètre reasoning_effort

Contrôle la profondeur de réflexion (disponible sur GPT-5 et GPT-5.1) :

• "none" : Aucun raisonnement (le plus rapide, latence la plus faible) - Valeur par défaut de GPT-5.1
• "minimal" : Réponses rapides, réflexion minimale
• "low" : Raisonnement de base
• "medium" : Raisonnement équilibré - Valeur par défaut de GPT-5
• "high" : Raisonnement profond pour les problèmes complexes

// GPT-5.1 sans raisonnement (rapide)
const completion = await openai.chat.completions.create({
  model: 'gpt-5.1',
  messages: [{ role: 'user', content: 'Requête simple' }],
  // reasoning_effort: 'none' est la valeur implicite par défaut pour GPT-5.1
});

// GPT-5.1 avec raisonnement élevé (tâches complexes)
const completion = await openai.chat.completions.create({
  model: 'gpt-5.1',
  messages: [{ role: 'user', content: 'Résolvez ce problème mathématique complexe...' }],
  reasoning_effort: 'high',
});

Paramètre verbosity

Contrôle le niveau de détail de la sortie (GPT-5/GPT-5.1) :

• "low" : Concis
• "medium" : Équilibré (par défaut)
• "high" : Verbeux

Limitations de GPT-5

NON Supporté :

• ❌ Paramètres temperature, top_p, logprobs
• ❌ Chaîne de pensée avec état entre les tours

Alternatives : Utilisez GPT-4o pour temperature/top_p, ou le skill openai-responses pour le raisonnement avec état

---

Modèles de Streaming

Activez avec stream: true pour une livraison token par token.

SDK Node.js

const stream = await openai.chat.completions.create({
  model: 'gpt-5.1',
  messages: [{ role: 'user', content: 'Écris un poème' }],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content || '';
  process.stdout.write(content);
}

Fetch (Cloudflare Workers)

const response = await fetch('https://api.openai.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${env.OPENAI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-5.1',
    messages: [{ role: 'user', content: 'Écris un poème' }],
    stream: true,
  }),
});

const reader = response.body?.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader!.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n').filter(line => line.trim() !== '');

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = line.slice(6);
      if (data === '[DONE]') break;

      try {
        const json = JSON.parse(data);
        const content = json.choices[0]?.delta?.content || '';
        console.log(content);
      } catch (e) {
        // Ignorer les JSON invalides
      }
    }
  }
}

Format Server-Sent Events (SSE) :

data: {"id":"chatcmpl-xyz","choices":[{"delta":{"content":"Bonjour"}}]}
data: [DONE]

Points Clés**: Gérez les chunks incomplets, le signal [DONE] et les JSON invalides avec élégance.

---

Appel de Fonctions

Définissez des outils avec un schéma JSON, le modèle les invoque en fonction du contexte.

Définition de l'Outil et Requête

const tools = [{
  type: 'function',
  function: {
    name: 'get_weather',
    description: 'Obtenir la météo actuelle pour un lieu',
    parameters: {
      type: 'object',
      properties: {
        location: { type: 'string', description: 'Nom de la ville' },
        unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
      },
      required: ['location']
    }
  }
}];

const completion = await openai.chat.completions.create({
  model: 'gpt-5.1',
  messages: [{ role: 'user', content: 'Quel temps fait-il à SF ?' }],
  tools: tools,
});

Gérer les Appels d'Outils

const message = completion.choices[0].message;

if (message.tool_calls) {
  for (const toolCall of message.tool_calls) {
    const args = JSON.parse(toolCall.function.arguments);
    const result = await executeFunction(toolCall.function.name, args);

    // Envoyer le résultat au modèle
    await openai.chat.completions.create({
      model: 'gpt-5.1',
      messages: [
        ...messages,
        message,
        {
          role: 'tool',
          tool_call_id: toolCall.id,
          content: JSON.stringify(result)
        }
      ],
      tools: tools,
    });
  }
}

Modèle de boucle**: Continuez à appeler l'API jusqu'à ce qu'il n'y ait plus de tool_calls dans la réponse.

---

Sorties Structurées

Les sorties structurées vous permettent d'appliquer une validation de schéma JSON sur les réponses du modèle.

Utilisation d'un Schéma JSON

const completion = await openai.chat.completions.create({
  model: 'gpt-4o', // Remarque : Les sorties structurées sont mieux supportées sur GPT-4o
  messages: [
    { role: 'user', content: 'Génère un profil de personne' }
  ],
  response_format: {
    type: 'json_schema',
    json_schema: {
      name: 'person_profile',
      strict: true,
      schema: {
        type: 'object',
        properties: {
          name: { type: 'string' },
          age: { type: 'number' },
          skills: {
            type: 'array',
            items: { type: 'string' }
          }
        },
        required: ['name', 'age', 'skills'],
        additionalProperties: false
      }
    }
  }
});

const person = JSON.parse(completion.choices[0].message.content);
// { name: "Alice", age: 28, skills: ["TypeScript", "React"] }

Mode JSON (Simple)

Pour les cas d'utilisation plus simples sans validation stricte du schéma :

const completion = await openai.chat.completions.create({
  model: 'gpt-5',
  messages: [
    { role: 'user', content: 'Liste 3 langages de programmation au format JSON' }
  ],
  response_format: { type: 'json_object' }
});

const data = JSON.parse(completion.choices[0].message.content);

Important : Lorsque vous utilisez response_format, incluez "JSON" dans votre prompt pour guider le modèle.

---

Vision (GPT-4o)

GPT-4o prend en charge la compréhension d'images en plus du texte.

Image via URL

const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Qu'y a-t-il dans cette image ?' },
        {
          type: 'image_url',
          image_url: {
            url: 'https://example.com/image.jpg'
          }
        }
      ]
    }
  ]
});

Image via Base64

import fs from 'fs';

const imageBuffer = fs.readFileSync('./image.jpg');
const base64Image = imageBuffer.toString('base64');

const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Décris cette image en détail' },
        {
          type: 'image_url',
          image_url: {
            url: `data:image/jpeg;base64,${base64Image}`
          }
        }
      ]
    }
  ]
});

Images Multiples

const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Compare ces deux images' },
        { type: 'image_url', image_url: { url: 'https://example.com/image1.jpg' } },
        { type: 'image_url', image_url: { url: 'https://example.com/image2.jpg' } }
      ]
    }
  ]
});

---

API Embeddings

Point de terminaison : POST /v1/embeddings

Convertissez du texte en vecteurs pour la recherche sémantique et le RAG.

Modèles

• text-embedding-3-large : 3072 dimensions (personnalisables : 256-3072), la plus haute qualité
• text-embedding-3-small : 1536 dimensions (personnalisables : 256-1536), rentable, recommandé

Requête de Base

const embedding = await openai.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'La nourriture était délicieuse.',
});
// Retourne : { data: [{ embedding: [0.002, -0.009, ...] }] }

Dimensions Personnalisées (Spécifique à OpenAI)

const embedding = await openai.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'Texte d\'exemple',
  dimensions: 256, // Réduit de la valeur par défaut 1536
});

Avantages : Réduction de stockage de 4 à 12 fois, recherche plus rapide, perte de qualité minimale.

Traitement par Lots

const embeddings = await openai.embeddings.create({
  model: 'text-embedding-3-small',
  input: ['Premier doc', 'Deuxième doc', 'Troisième doc'],
});

Limites : 8192 tokens/entrée, 300k tokens au total sur le lot, 2048 taille de tableau maximum.

Points Clés : Utilisez des dimensions personnalisées pour l'efficacité, traitez par lots jusqu'à 2048 documents, mettez en cache les embeddings (déterministes).

---

API Images

Génération d'Images (DALL-E 3)

Point de terminaison : POST /v1/images/generations

const image = await openai.images.generate({
  model: 'dall-e-3',
  prompt: 'Un chat siamois blanc aux yeux bleus frappants',
  size: '1024x1024', // Aussi : 1024x1536, 1536x1024, 1024x1792, 1792x1024
  quality: 'standard', // ou 'hd'
  style: 'vivid', // ou 'natural'
});

console.log(image.data[0].url);
console.log(image.data[0].revised_prompt); // DALL-E 3 peut réviser pour des raisons de sécurité

Spécificités de DALL-E 3 :

• Supporte uniquement n: 1 (une image par requête)
• Peut réviser les prompts pour des raisons de sécurité/qualité (vérifiez revised_prompt)
• Les URL expirent en 1 heure (utilisez response_format: 'b64_json' pour obtenir les données brutes)

Édition d'Images (GPT-Image-1)

const edit = await openai.images.edit({
  model: 'gpt-image-1',
  image: fs.createReadStream('./cat.png'),
  prompt: 'Ajoute un chapeau de fête au chat',
  mask: fs.createReadStream('./mask.png'), // Zone à éditer (optionnel)
});

Modèles : gpt-image-1

Points Clés : 1 image par requête, visionnage ou masque partiel, préférez la sortie b64_json pour la persistance.

---

API Audio

Transcription (Whisper)

Point de terminaison : POST /v1/audio/transcriptions

import fs from 'fs';

const transcription = await openai.audio.transcriptions.create({
  model: 'whisper-1',
  file: fs.createReadStream('./audio.mp3'),
  language: 'fr', // Optionnel (code ISO 639-1)
  response_format: 'text', // 'text', 'srt', 'vtt', 'json'
  timestamp_granularities: ['segment'], // Pour horodatage
});
console.log(transcription);

Formats supportés : flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm

Limites : Taille de fichier jusqu'à 25 Mo

Prix : 0,006 $/minute (Whisper)

Synthèse Vocale (TTS)

Point de terminaison : POST /v1/audio/speech

const speech = await openai.audio.speech.create({
  model: 'tts-1', // ou 'tts-1-hd' (qualité supérieure)
  voice: 'alloy', // alloy, echo, fable, onyx, nova, shimmer, ash, ballad, coral, sage, verse
  input: 'Bonjour, comment puis-je vous aider aujourd\'hui ?',
  speed: 1.0, // 0.25 à 4.0
  response_format: 'mp3', // mp3, opus, aac, flac, pcm, wav
});

const buffer = Buffer.from(await speech.arrayBuffer());
fs.writeFileSync('./speech.mp3', buffer);

8 Voix : alloy, echo, fable, onyx, nova, shimmer

3 Voix Supplémentaires (octobre 2025) : ash, ballad, coral, sage, verse

Prix : 0,015 $/1 000 caractères (tts-1), 0,030 $/1 000 caractères (tts-1-hd)

---

API Moderation

Point de terminaison : POST /v1/moderations

Vérifiez le contenu par rapport à 11 catégories de sécurité.

Requête de Base

const moderation = await openai.moderations.create({
  model: 'omni-moderation-latest', // Recommandé
  input: 'Je veux faire du mal à quelqu\'un',
});

console.log(moderation.results[0].flagged); // true
console.log(moderation.results[0].categories);
// {
//   harassment: true,
//   harassment/threatening: true,
//   violence: true,
//   violence/graphic: false,
//   ... etc
// }

11 Catégories de Sécurité

Catégorie	Description
harassment	Contenu harcelant
harassment/threatening	Harcèlement menaçant
hate	Discours haineux
hate/threatening	Discours haineux menaçant
illicit	Contenu illicite
illicit/violent	Contenu illicite violent
self-harm	Automutilation
self-harm/instructions	Instructions d'automutilation
sexual	Contenu sexuel
sexual/minors	Contenu sexuel impliquant des mineurs
violence	Violence
violence/graphic	Violence graphique

Traitement par Lots

const moderation = await openai.moderations.create({
  input: ['Contenu A', 'Contenu B'],
});

for (const result of moderation.results) {
  console.log(result.flagged);
}

Points Clés : Utilisez comme outil de sécurité/filtrage, traitez par lots pour l'efficacité, incluez dans les flux de modération de contenu.

---

Gestion des Erreurs

Erreurs Courantes et Solutions

Code	Erreur	Cause	Solution
401	Invalid Authentication	Clé API manquante/invalide	Vérifiez OPENAI_API_KEY
429	Rate Limit Reached	Trop de requêtes	Implémentez backoff exponentiel
500	Server Error	Problème serveur OpenAI	Réessayez après délai
400	Bad Request	Corps de requête invalide	Validez la structure JSON
404	Not Found	Point de terminaison/modèle inexistant	Vérifiez l'URL/nom du modèle
413	Request Too Large	Payload trop volumineux	Réduisez la taille d'entrée
422	Unprocessable Entity	Paramètres incompatibles	Ex. temperature avec GPT-5

Modèle de Backoff Exponentiel

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error instanceof OpenAI.APIError) {
        if (error.status === 429 || error.status >= 500) {
          if (i === maxRetries - 1) throw error;
          const delay = Math.pow(2, i) * 1000;
          console.log(`Nouvelle tentative après ${delay}ms...`);
          await new Promise(resolve => setTimeout(resolve, delay));
          continue;
        }
      }
      throw error;
    }
  }
  throw new Error('Échec après tentatives');
}

Pièges Courants par Catégorie d'API

Pour chaque catégorie d'API, voici les pièges les plus fréquents, regroupez-les par fonctionnalité de base :

Chat Completions

• tools mal formaté (structure incorrecte)
• response_format manquant lors de l'utilisation de sorties structurées
• Inclure un message système lors de l'utilisation de json_object

Embeddings

• Mélanger les modèles d'embedding (vecteurs de dimensions différentes)
• Division incorrecte des documents (perte de contexte)
• Oublier de valider la longueur du texte d'entrée

Audio & Images

• Fichiers audio trop volumineux (>25 Mo) → Divisez
• Oublier de spécifier response_format lors de l'exportation
• Req uêter avec plusieurs images simultanément (non pris en charge)

---

Limites de Débit

Seuils Actuels (à partir de 2026)

• GPT-4o : 10 000 000 TPM (tokens par minute) / 5 000 000 RPM (requêtes par minute)
• GPT-5/GPT-5.1 : Varie selon le niveau, vérifiez la console OpenAI
• text-embedding-3-small : 5 000 000 TPM / 10 000 RPM
• text-embedding-3-large : 5 000 000 TPM / 10 000 RPM (identique)
• DALL-E 3 : 5 images/heure (Tier 1) à 60 images/heure (grille tarifaire payante)
• Whisper : 50 Mo/min (basé sur la taille du fichier)
• TTS : 15 000 RPM (requêtes par minute)
• Moderation : 30 000 RPM (requêtes par minute)

Points Clés : TPM ≠ RPM, limite de modèle partagée avec tous les points de terminaison, les comptes multiclé n'augmentent pas les limites, demandez une augmentation manuellement via la console OpenAI. Surveillez via les en-têtes de réponse : x-ratelimit-limit-requests, x-ratelimit-remaining-tokens.

---

Bonnes Pratiques de Production

Optimisations Clés

1. Mise en cache des Embeddings : Les embeddings sont déterministes, mettez-les en cache pour éviter les appels redondants.
2. Traitement par Lots : Traitez les embeddings par lots jusqu'à 2 048 entrées maximum par appel.
3. Dimensions Personnalisées : Utilisez des dimensions d'embedding réduites (par exemple, 256 au lieu de 1536) pour des vitesses de recherche plus rapides et un stockage plus faible.
4. Réessais : Implémentez un backoff exponentiel avec gigue pour la gestion des limites de débit et des erreurs serveur.
5. Surveillance : Suivez l'utilisation des tokens, les taux d'erreur et la latence via la console OpenAI ou un outil externe.
6. Securité : Ne partagez jamais les clés API, faites toujours référence via des variables d'environnement.
7. File d'Attente : Utilisez une file d'attente ou un pool de promesses pour des limites d'API élevées.

Pièges Courants

• Consommation de Tokens Vérifiée : Vérifiez l'utilisation des tokens via response.usage.total_tokens pour éviter les dépassements de coûts.
• Délais d'Attente : Définissez des délais d'attente (par exemple, 30 s) pour les appels API longs.
• Version des Modèles : Utilisez des modèles spécifiques (ex. gpt-5.1) pour éviter les mises à jour .

---

Relation avec openai-responses

openai-responses est un skill distinct qui implémente l'API responses d'OpenAI — une abstraction de plus haut niveau gérant automatiquement l'historique des conversations (avec état), les suivis et les appels de fonctions de manière persistante. Il construit sur l'API Chat Completions présentée ici, mais ajoute une couche de gestion de session.

Quand utiliser ce skill (stateless) vs openai-responses (stateful) :

• Utilisez ce skill (API Chat Completions) lorsque vous avez besoin d'un contrôle total sur les messages envoyés, la configuration du modèle, et que vous gérez vous-même l'état.
• Utilisez openai-responses lorsque vous voulez une abstraction "agent-like" avec gestion automatique de l'historique, des rappels, et des capacités de recherche.

Les deux peuvent coexister dans un projet : utilisez openai-responses pour le chat avec état et ce skill pour les appels directs à l'API Embeddings, Images, Audio et Moderation.

---

Ce guide est régulièrement mis à jour pour refléter les dernières modifications de l'API OpenAI.