Génère la réponse d'un modèle à une conversation. L'endpoint suit l'API OpenAI Chat Completions : requêtes et réponses ont la même forme qu'avec OpenAI, quel que soit le fournisseur du modèle.
Exemple
curl https://promptix.tn/api/v1/chat/completions \ -H "Authorization: Bearer $PROMPTIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "openai/gpt-6-luna", "messages": [ { "role": "system", "content": "You are a concise assistant." }, { "role": "user", "content": "Give me three names for a café in Sidi Bou Said." } ] }'Corps de la requête
Envoyez du JSON avec Content-Type: application/json et votre clé dans l'en-tête Authorization. Seuls model et messages sont obligatoires.
{ "model": "anthropic/claude-sonnet-5", "messages": [ { "role": "system", "content": "You answer in French, in two sentences at most." }, { "role": "user", "content": "What is an API gateway?" } ], "temperature": 0.3, "max_tokens": 300}| Paramètre | Type | Description |
|---|---|---|
modelObligatoirestring | string | Identifiant du modèle dans le catalogue, par exemple openai/gpt-6-luna ou anthropic/claude-sonnet-5. |
messagesObligatoirearray | array | La conversation jusqu'ici. Chaque message a un role (system, user, assistant ou tool) et un content (une chaîne, ou un tableau de parties pour les modèles multimodaux). |
streamFacultatifboolean | boolean | Renvoie la réponse sous forme d'événements server-sent. false par défaut. Voir Streaming. |
max_tokensFacultatifinteger | integer | Nombre maximal de tokens à générer. Définissez-le pour plafonner le coût d’une requête. Les modèles de raisonnement décomptent leurs tokens de réflexion de ce budget et peuvent renvoyer un content vide avec finish_reason: "length" s’il est trop petit : prévoyez plus large ou utilisez max_completion_tokens. |
temperatureFacultatifnumber | number | Température d’échantillonnage entre 0 et 2. Plus elle est basse, plus la sortie est déterministe. Ignorée par les modèles de raisonnement. |
top_pFacultatifnumber | number | Échantillonnage nucleus, entre 0 et 1. Modifiez ce paramètre ou la température, pas les deux. Ignoré par les modèles de raisonnement. |
frequency_penaltyFacultatifnumber | number | Entre -2 et 2. Les valeurs positives découragent la répétition des mêmes tokens. |
presence_penaltyFacultatifnumber | number | Entre -2 et 2. Les valeurs positives encouragent l’abord de nouveaux sujets. |
stopFacultatifstring | string[] | string | string[] | Jusqu’à quatre séquences qui arrêtent la génération. Non pris en charge par les modèles de raisonnement. |
seedFacultatifinteger | integer | Échantillonnage reproductible, dans la mesure du possible, sur les modèles qui le permettent. |
response_formatFacultatifobject | object | { "type": "json_object" } pour une sortie JSON, ou json_schema pour une sortie structurée sur les modèles compatibles. |
toolsFacultatifarray | array | Fonctions que le modèle peut appeler, au format d’outils OpenAI. |
tool_choiceFacultatifstring | object | string | object | auto, none, required, ou une fonction précise. |
Autres paramètres
Promptix vérifie model (une chaîne non vide) et messages (un tableau) et transmet tous les autres champs tels quels : vous pouvez donc envoyer n'importe quel paramètre compatible OpenAI. Leur prise en charge dépend du modèle : la fiche du modèle dans le catalogue liste les paramètres acceptés, et ceux qui ne le sont pas peuvent être ignorés. Le champ usage est réservé : Promptix le définit lui-même pour mesurer le coût.
Modèles de raisonnement
Les modèles qui réfléchissent avant de répondre (famille GPT-6 Luna, série o d'OpenAI, Claude et Gemini en mode réflexion) ignorent temperature, top_p et stop, et consomment une partie de max_tokens en tokens de raisonnement invisibles. Un budget trop serré se termine donc par finish_reason: "length" avec un contenu null. Utilisez max_completion_tokens avec une marge confortable, ou choisissez un modèle classique comme anthropic/claude-sonnet-5 ou google/gemini-3.8-flash quand vous avez besoin des réglages d'échantillonnage et des séquences d'arrêt. Sur openai/gpt-6-luna en particulier, gardez max_tokens à 100 ou plus, ou envoyez reasoning_effort: "low", sinon les réponses courtes peuvent revenir vides. La fiche du modèle dans le catalogue liste ce que chaque modèle prend en charge.
Réponse
Une requête sans streaming renvoie un objet JSON unique :
{ "id": "gen-1758880023-kQ3vX8mZpL2nR7tW", "object": "chat.completion", "created": 1758880023, "model": "openai/gpt-6-luna", "provider": "OpenAI", "choices": [ { "index": 0, "finish_reason": "stop", "message": { "role": "assistant", "content": "1. Café Bleu Jasmin\n2. Dar Nour\n3. Les Terrasses du Cap" } } ], "usage": { "prompt_tokens": 31, "completion_tokens": 22, "total_tokens": 53 }}| Champ | Description |
|---|---|
id | Identifiant de génération (gen-…). Utilisez-le avec GET /generation pour obtenir le coût en TND. |
object | chat.completion |
created | Horodatage Unix en secondes. |
model | Le modèle qui a produit la réponse. |
provider | Le fournisseur qui a traité la requête. |
choices[].message | Le message de l'assistant : role, content et, si le modèle appelle des outils, tool_calls. |
choices[].finish_reason | stop, length (max_tokens atteint, tokens de raisonnement compris sur les modèles de raisonnement), tool_calls ou content_filter. |
usage | prompt_tokens, completion_tokens et total_tokens. Ce sont les tokens qui vous sont facturés. |
La réponse peut contenir des champs supplémentaires venant du fournisseur (par exemple native_finish_reason ou des détails de usage). Ignorez ceux dont vous n'avez pas besoin. Le montant débité de votre solde ne figure pas dans la réponse : consultez-le avec GET /generation. usage.prompt_tokens_details.cached_tokens indique la part du prompt lue depuis le cache du fournisseur : voir Cache de prompt pour payer moins sur les prompts répétés.
Autres exemples
Conversation à plusieurs tours
L'API est sans état : renvoyez toute la conversation à chaque fois, y compris les réponses précédentes de l'assistant. Chaque token envoyé est facturé comme token d'entrée : raccourcissez ou résumez les longs historiques.
{ "model": "openai/gpt-6-luna", "messages": [ { "role": "system", "content": "You are a support assistant for an online shop in Tunis." }, { "role": "user", "content": "Do you deliver to Sfax?" }, { "role": "assistant", "content": "Yes, delivery to Sfax takes 2 to 3 working days." }, { "role": "user", "content": "And how much does it cost?" } ]}Sortie JSON
Demandez du JSON avec response_format et décrivez les clés attendues dans le message système.
{ "model": "openai/gpt-6-luna", "response_format": { "type": "json_object" }, "messages": [ { "role": "system", "content": "Extract the fields and reply with JSON: {\"city\": string, \"amount_tnd\": number}" }, { "role": "user", "content": "Invoice from Sousse, total due 245.500 dinars." } ]}Appel d'outils
Déclarez des fonctions dans tools. Quand le modèle décide d'en appeler une, la réponse contient finish_reason: "tool_calls" :
{ "model": "openai/gpt-6-luna", "messages": [{ "role": "user", "content": "What is the weather in Bizerte?" }], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "Current weather for a Tunisian city", "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] } } } ], "tool_choice": "auto"}{ "choices": [ { "index": 0, "finish_reason": "tool_calls", "message": { "role": "assistant", "content": null, "tool_calls": [ { "id": "call_7f3a", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\":\"Bizerte\"}" } } ] } } ]}Exécutez la fonction dans votre code, puis renvoyez son résultat dans un message tool avec le tool_call_id correspondant. Renvoyez aussi le même tableau tools (omis ci-dessous pour plus de lisibilité) :
{ "model": "openai/gpt-6-luna", "messages": [ { "role": "user", "content": "What is the weather in Bizerte?" }, { "role": "assistant", "content": null, "tool_calls": [ { "id": "call_7f3a", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\":\"Bizerte\"}" } } ] }, { "role": "tool", "tool_call_id": "call_7f3a", "content": "{\"temp_c\": 24, \"sky\": \"clear\"}" } ]}Images
Les modèles qui acceptent des images reçoivent un tableau de parties de contenu. Vérifiez les modalités d'entrée du modèle dans le catalogue.
{ "model": "openai/gpt-6-luna", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What is written on this sign?" }, { "type": "image_url", "image_url": { "url": "https://example.com/sign.jpg" } } ] } ]}Limites
- Votre solde doit être d'au moins 0,100 TND au démarrage de la requête, sinon vous recevez
402. - Une clé dont le plafond mensuel est atteint reçoit
402avec le codekey_monthly_limit. - Une requête, streaming compris, peut durer jusqu'à 300 secondes.
- La taille de contexte dépend du modèle et figure dans le catalogue. Un prompt trop long est refusé par le fournisseur avec un code
400ou413.
Voir Erreurs et limites pour tous les codes.