Créer une Complétion de Chat avec Reconnaissance d'Image (Streaming) Base64

Description de l'API : Étant donné un prompt, le modèle renverra une ou plusieurs complétions prédites, et peut également renvoyer les probabilités des tokens alternatifs à chaque position. Cette API est principalement utilisée pour créer des complétions de conversation intégrant la reconnaissance d'image (via Base64) et des prompts textuels.

Référence Officielle : Documentation de l'API OpenAI

Détails de l'API

Méthode de requête : POST
URL de la requête : https://api.codingplanx.ai/v1/chat/completions
Format des données : application/json

En-têtes de la Requête (Request Headers)

Nom du paramètre	Requis	Type	Valeur d'exemple	Description
Content-Type	Oui	string	`application/json`	Format des données envoyées
Accept	Oui	string	`application/json`	Format des données acceptées
Authorization	Non	string	`Bearer {{VOTRE_CLE_API}}`	Jeton d'authentification (Token)

Corps de la Requête (Request Body)

Nom du champ	Type	Requis	Description
model	string	Oui	L'ID du modèle à utiliser (ex. : `gpt-4o-mini`).
messages	array	Oui	Liste des messages composant la conversation jusqu'à présent. Contient `role` et `content`. Pour la reconnaissance d'image, `content` peut être un tableau contenant du texte et une `image_url` (Base64).
tools	array	Oui	Liste d'outils que le modèle peut appeler. Actuellement, seules les fonctions sont prises en charge comme outils. Utilisé pour fournir une liste de fonctions pour lesquelles le modèle peut générer des entrées JSON.
tool_choice	object	Oui	Contrôle quelle fonction le modèle appelle. `none` signifie aucun appel ; `auto` signifie sélection automatique ; on peut aussi forcer l'appel d'une fonction spécifique.
temperature	integer	Non	Température d'échantillonnage, comprise entre 0 et 2. Des valeurs plus élevées (ex. : 0.8) rendent la sortie plus aléatoire, tandis que des valeurs plus basses (ex. : 0.2) la rendent plus déterministe. Il est recommandé de ne pas modifier en même temps que `top_p`.
top_p	integer	Non	Paramètre d'échantillonnage de noyau (nucleus sampling). 0.1 signifie que seuls les tokens composant les 10 % de masse de probabilité supérieure sont considérés. Il est recommandé de ne pas modifier en même temps que `temperature`.
n	integer	Non	Nombre de choix de complétion de chat à générer pour chaque message d'entrée. La valeur par défaut est 1.
stream	boolean	Non	Interrupteur de sortie en streaming. La valeur par défaut est `false`. Si défini sur `true`, des fragments de message seront envoyés sous forme d'événements envoyés par le serveur (SSE) et se termineront par l'indicateur `data: [DONE]`.
stop	string	Non	Séquences (jusqu'à 4) où l'API arrêtera de générer d'autres tokens. La valeur par défaut est null.
max_tokens	integer	Non	Le nombre maximum de tokens à générer dans la complétion de chat. La valeur par défaut est inf (infini).
presence_penalty	number	Non	Pénalité de présence (-2.0 à 2.0). Les valeurs positives pénalisent les nouveaux tokens en fonction de leur présence ou non dans le texte généré jusqu'à présent, augmentant ainsi la probabilité que le modèle aborde de nouveaux sujets.
frequency_penalty	number	Non	Pénalité de fréquence (-2.0 à 2.0). Les valeurs positives pénalisent les nouveaux tokens en fonction de leur fréquence d'apparition dans le texte généré jusqu'à présent, réduisant ainsi la probabilité que le modèle répète le même contenu. La valeur par défaut est 0.
logit_bias	object	Non	Modifie la probabilité que les tokens spécifiés apparaissent dans la complétion. Accepte un objet JSON mappant les ID de tokens à une valeur de biais (-100 à 100).
user	string	Non	Un identifiant unique représentant votre utilisateur final, ce qui aide à surveiller et à détecter les abus.
response_format	object	Non	Spécifie le format que le modèle doit générer. Passer `{ "type": "json_object" }` active le mode JSON. Lors de son utilisation, vous devez explicitement demander au modèle de générer du JSON dans le prompt.
seen	integer	Non	Fonctionnalité Bêta. Graine (seed) d'échantillonnage déterministe. Les requêtes répétées avec la même graine et les mêmes paramètres devraient renvoyer le même résultat (le déterminisme absolu n'est pas garanti).

Exemple de Requête

{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Qu'y a-t-il dans cette image ? Veuillez la décrire en détail."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAiEAAAIhCAYAAACYF2qHAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAgAElEQVR4nOy9ebxtWVXf+x1zrrX2Pud2VRQUjUVf0glIYvOJLdJ8iCagIor... (Chaîne base64 trop longue omise ici)"
          }
        }
      ]
    }
  ]
}

Corps de la Réponse (Response Body)

Nom du champ	Type	Description
id	string	Identifiant unique de la complétion de chat.
object	string	Type d'objet, généralement `chat.completion` (ou `chat.completion.chunk` dans le cas du streaming).
created	integer	Horodatage Unix du moment de la création.
choices	array	Liste des choix de complétion.
└─ index	integer	Index du choix dans la liste.
└─ message	object	Objet du message généré par le modèle, contenant `role` et `content`.
└─ finish_reason	string	Raison pour laquelle le modèle a cessé de générer (par exemple : `stop` pour un arrêt normal, `length` pour avoir atteint la limite de `max_tokens`).
usage	object	Statistiques de consommation des jetons (Tokens) pour cette requête.
└─ prompt_tokens	integer	Nombre de tokens consommés par le prompt (y compris les tokens calculés à partir de l'image).
└─ completion_tokens	integer	Nombre de tokens consommés par le contenu généré.
└─ total_tokens	integer	Nombre total de tokens consommés pour cette requête.

Exemple de Réponse (Succès 200 OK)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\r
\r
Hello there, how may I assist you today?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

Foire Aux Questions (FAQs)

Q1 : Comment activer la sortie en streaming (Streaming) ? R : Définissez le paramètre stream sur true dans le corps de la requête. Une fois activé, l'API n'attendra plus que la réponse entière soit générée avant de la renvoyer. Au lieu de cela, elle renverra des blocs de données au format data: {...} mot à mot / phrase par phrase via des Server-Sent Events (SSE), jusqu'à la réception de l'indicateur data: [DONE] signalant la fin de la génération.

Q2 : Quelles sont les exigences pour l'encodage Base64 des images ? R : La chaîne Base64 de l'image doit inclure le préfixe de type MIME correct, tel que data:image/png;base64, ou data:image/jpeg;base64,. Il est recommandé de compresser correctement les dimensions de l'image avant de la convertir en Base64 afin de réduire la latence de transmission réseau et de diminuer la consommation des prompt_tokens (les images trop grandes peuvent consommer énormément de Tokens et même dépasser la limite de la fenêtre de contexte).

Q3 : Pourquoi la réponse du modèle a-elle été tronquée ? R : Veuillez vérifier la valeur de choices[0].finish_reason dans le corps de la réponse. Si elle est de length, cela signifie que le texte généré a atteint la limite de max_tokens que vous avez définie, ou que l'ensemble de la conversation a dépassé la limite de la fenêtre de contexte maximale du modèle. Vous pouvez résoudre ce problème en augmentant la valeur de max_tokens.

Q4 : Comment forcer le modèle à générer des données au format JSON ? R : Tout d'abord, vous devez définir "response_format": { "type": "json_object" } dans le corps de la requête. Remarque importante : en plus de définir ce paramètre, vous devez explicitement demander au modèle, en langage naturel, de générer du JSON dans le prompt système (system prompt) ou le prompt utilisateur au sein de messages (par exemple : "Veuillez formater le résultat en JSON"). Si vous ne le faites pas, le modèle risque de générer des espaces vides à l'infini jusqu'à épuiser les Tokens.

Q5 : Que faire si je rencontre une erreur 401 Unauthorized ? R : Veuillez vérifier si le paramètre Authorization dans l'en-tête de la requête contient correctement votre clé API. Le format doit strictement être Bearer VOTRE_CLE_API (faites attention à l'espace obligatoire entre Bearer et la clé).