Chat completions

Génère une réponse conversationnelle à partir d'une liste de messages. Endpoint principal de la plateforme, compatible avec le format openai.chat.completions.create. Supporte le streaming SSE.

Endpoint#endpoint

Paramètres requête#params

Contenus multimodaux

Le champ content d'un message peut être un tableau de parts. Trois types sont acceptés, tous en ligne : text, image_url et input_audio. Tout autre type (input_image, image_embeds, prompt_embeds…) est refusé en 400 invalid_request.

• text — champ text (chaîne) obligatoire.
• image_url — image_url.url doit être une data URL base64 (data:image/png|jpeg|webp|gif;base64,…). Les URL http(s) distantes sont refusées : le backend d'inférence les téléchargerait depuis son propre réseau. Encodez l'image côté client. detail optionnel : auto, low ou high.
• input_audio — input_audio.data en base64 (jamais une URL) et input_audio.format à wav ou mp3.

Le poids total du corps reste soumis à la limite de taille de la plateforme (413 payload_too_large) : une image base64 pèse ~33 % de plus que le binaire.

Paliers d'effort

Le paramètre effort contrôle l'effort de raisonnement chain-of-thought de 3gk-llm (modèle à raisonnement). Le client choisit un palier — le budget de tokens raisonnement est figé côté gateway et ne peut pas être réglé directement. Le raisonnement est opt-in : sans effort ni reasoning_effort, le palier appliqué est off (défaut configurable côté admin).

Vous pouvez aussi utiliser le paramètre standard OpenAI reasoning_effort (minimal | low | medium | high) pour réactiver le raisonnement sans le champ propriétaire effort : minimal est mappé sur low. Si les deux sont fournis, effort prime.

Plafond de sortie

La plateforme borne le budget de réponse de chaque requête. Ce plafond vaut aujourd'hui 4 096 tokens ; il est administrable et peut évoluer, ne le codez pas en dur.

• Un max_tokens (ou max_completion_tokens) supérieur au plafond est ramené au plafond, sans erreur : la requête est servie, mais la réponse s'arrêtera sur finish_reason: "length" bien avant la valeur demandée.
• Une valeur inférieure ou égale au plafond est appliquée telle quelle.
• Si vous n'envoyez ni l'un ni l'autre, le plafond est imposé comme budget de réponse.
• Le plafond s'applique par choix de complétion : avec n > 1, la sortie totale peut atteindre plafond × n.

Réconciliation max_tokens

Côté backend, max_tokens plafonne le total raisonnement + réponse. Pour vous éviter de soustraire vous-même le budget de raisonnement, la gateway traite votre max_tokens comme le budget de réponse uniquement et ajoute le budget de raisonnement avant de relayer :

• Si max_tokens absent : le plafond de sortie est imposé (cf. ci-dessous).
• Pour effort: off : pas d'ajout, on relaie votre valeur une fois plafonnée, et le raisonnement est désactivé en amont (enable_thinking=false).
• max_completion_tokens (alias OpenAI récent) prime sur max_tokens si les deux sont fournis.
• Cette réconciliation s'applique uniquement aux modèles qui supportent le thinking (c'est le cas de 3gk-llm). Pour les autres, votre max_tokens passe inchangé.

Exemples#exemples

from openai import OpenAI

client = OpenAI(
    base_url="https://ai.3gks.cloud/v1",
    api_key="sk-3gk-7XQp4kL8…",
)

response = client.chat.completions.create(
    model="3gk-llm",
    messages=[
        {"role": "system", "content": "Tu es un assistant pour courtier en assurance."},
        {"role": "user", "content": "Résume ce contrat : …"},
    ],
    temperature=0.3,
    max_tokens=512,
)

print(response.choices[0].message.content)

Format de réponse#response

Réponse JSON conforme à l'API OpenAI. L'identifiant id est préfixé 3gk-cmpl- suivi de 24 caractères aléatoires — utilisez-le pour corréler avec les logs admin en cas de support.

{
  "id": "3gk-cmpl-7XQp4kL8mNfRtQzVa2bC3dE4",
  "object": "chat.completion",
  "created": 1715761712,
  "model": "3gk-llm",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Le contrat couvre la responsabilité civile…"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 412,
    "completion_tokens": 248,
    "total_tokens": 660
  }
}

Sur les paliers low / medium / high, le champ choices[].message.reasoning et usage.completion_tokens_details.reasoning_tokens sont également retournés. En effort: off, ces champs sont strippés.

Codes de réponse#status

Pour le détail du format d'erreur et des stratégies de retry, voir Codes d'erreur.

Routage & fallback#routing

Les requêtes chat.completions sont routées par défaut vers nos instances vLLM locales (GPU hébergés en France). Si l'administrateur a configuré un mode fallback ou auto et que les instances vLLM sont indisponibles, le trafic bascule vers Scaleway Generative APIs (Paris, FR). Aucune donnée ne sort du territoire français.