Construisez sur Geb. L'arabe d'abord, compatible OpenAI.

L'API de Geb donne à votre application le même modèle que celui qui répond dans Geb AI, par l'interface de complétions de chat que les bibliothèques clientes d'OpenAI parlent déjà. Pointez un SDK OpenAI vers https://api.gebai.ca/v2, utilisez une clé Geb, et cela fonctionne.

Geb appelle cette API API v2, et ses chemins d'URL commencent par /v2. Les clients existants qui appellent encore /v1 continuent de fonctionner : /v1/... est un alias qui atteint exactement les mêmes gestionnaires, avec le même comportement, les mêmes en-têtes, les mêmes erreurs et les mêmes quotas, et un appel ne compte qu'une fois, quel que soit le préfixe utilisé. Le nouveau code doit utiliser /v2.

Ce que vous obtenez

• Complétions de chat sur POST /v2/chat/completions, en réponse complète ou en streaming par événements envoyés par le serveur.
• Des réponses solides en arabe et en plusieurs langues. Geb répond dans la langue du dernier message de votre utilisateur, parmi 23 langues. L'arabe est une langue à part entière, pas une couche de traduction.
• Vos propres fonctions grâce au champ standard tools (appel de fonctions).
• Les outils intégrés de Geb, comme la recherche web, la météo, les générateurs de documents et de feuilles de calcul, lorsque vous les activez en les nommant.
• Sortie structurée avec response_format (json_object et json_schema).
• Entrée d'images dans les messages de l'utilisateur.
• Contrôle du raisonnement avec des niveaux d'effort.
• Conversations enregistrées que vous pouvez poursuivre par identifiant, séparées de toute mémoire du compte.
• Règles de réponse (geb_acceptance) : déclarez des plages de mots, des expressions interdites et des exigences d'ancrage dans des sources, et Geb vérifie et affine la réponse avant de la renvoyer.
• Aucune facturation au jeton. Votre forfait inclut un nombre d'appels par période de facturation (voir la section 10). Les jetons ne sont pas comptés.

Ce qu'elle n'est pas

• Pas un proxy OpenAI. Chaque réponse vient du modèle propre de Geb. Votre requête n'est jamais transmise au modèle d'un autre fournisseur.
• Sans mémoire. Les appels API ne lisent jamais la mémoire de votre compte Geb et n'y écrivent jamais. Un appel est construit à partir de votre seule requête (plus un fil de conversation enregistré si vous en demandez un, voir la section 5.5).
• Uniquement des complétions de chat. Il n'existe pas de points de terminaison pour les embeddings, l'audio, la génération d'images, les fichiers, le traitement par lots, l'ajustement fin (fine-tuning), Assistants ou Responses.
• Un seul choix. n, logprobs et l'ancien champ functions sont rejetés.
• Certains champs d'échantillonnage sont acceptés et ignorés. stop, user, seed, temperature, top_p, presence_penalty, frequency_penalty, logit_bias, min_p, top_k et repetition_penalty ne provoquent jamais d'erreur, et ils n'ont aucun effet aujourd'hui.
• Non appelable depuis un navigateur sur le site d'un tiers. L'API ne répond aux requêtes préalables cross-origin que pour les sites de Geb. Appelez-la depuis votre serveur, pas depuis du JavaScript côté client. Ne mettez jamais une clé dans une page web ou une application mobile.

1. Obtenez une clé (section 3). Elle ressemble à geb_live_ suivi de 43 caractères.
2. Placez-la dans une variable d'environnement. Ne la collez jamais dans le code source.
3. Faites un appel.

Ce que vous recevez en retour

model est l'identifiant du modèle qui a répondu, tel que le liste GET /v2/models. usage.prompt_tokens inclut les instructions de base propres à Geb, qui ouvrent chaque prompt.

Si vous avez reçu une 401, vérifiez la clé et l'en-tête Authorization (section 4). Si vous avez reçu une 429, lisez la section 10.

Les clés sont créées par un compte Geb connecté, dans l'application web de Geb.

1. Créez votre compte ou connectez-vous sur https://gebai.ca.
2. Ouvrez Profil, puis Clés API (https://gebai.ca/profile/api-keys).
3. Choisissez Créer une clé API. Donnez-lui un nom et, si vous le souhaitez, une durée de validité en jours (de 1 à 365).
4. Copiez la clé immédiatement. Elle n'est affichée qu'une seule fois et ne peut pas être récupérée ensuite. Geb n'en conserve qu'un hachage.

Obtenir votre clé API

À savoir :

• Un compte peut détenir jusqu'à 10 clés actives. Révoquez-en une pour libérer une place.
• Révoquez une clé à tout moment depuis la même page. Une clé révoquée ou expirée répond 401 dès la requête suivante.
• Chaque clé appartient au compte qui l'a créée. Les appels, le quota et les limites de débit sont comptés par compte, toutes clés confondues.
• Le seul périmètre de clé est chat:write, qui couvre tous les points de terminaison de ce guide.
• Tous les forfaits peuvent utiliser l'API, Gratuit compris : un compte Gratuit peut créer des clés et effectuer 500 appels par période de facturation. Le nombre d'appels inclus dans chaque forfait est indiqué à la section 10.

Gardez les clés sur votre serveur. Utilisez une clé par application ou par environnement, afin de pouvoir en révoquer une sans toucher aux autres.

Envoyez la clé comme jeton porteur (bearer) à chaque requête.

Une requête sans clé, avec un en-tête mal formé, avec un autre schéma (par exemple Basic), ou avec une clé inconnue, révoquée ou expirée, reçoit toujours la même réponse :

Une 403 permission_error signifie que la clé est valide mais que le compte n'a pas le droit d'utiliser l'API (par exemple, le compte est suspendu).

Tous les points de terminaison se trouvent sous https://api.gebai.ca, utilisent JSON et exigent la clé porteuse. Le préfixe canonique est /v2. Les mêmes chemins avec le préfixe /v1 sont un alias pour les clients existants et se comportent de façon identique. Lorsqu'une réponse ou une erreur nomme un chemin, elle nomme le préfixe que vous avez utilisé.

Les corps de requête peuvent être compressés en gzip ou deflate (Content-Encoding: gzip). Le corps de requête maximal est de 32 MiB après décompression.

5.1 Lister les modèles

La réponse est une liste au format OpenAI. Chaque modèle porte des informations en direct sur ce que l'API peut faire à l'instant :

• context_window est le nombre de jetons que le modèle peut contenir dans une seule requête. Il vaut null lorsque Geb ne peut pas le mesurer pour le moment.
• capabilities.vision et "image" dans modalities.input sont en direct : ils ne valent true que si une requête avec image serait acceptée à l'instant.
• geb_tools est la liste exacte des noms d'outils intégrés qu'une requête peut nommer (section 7.2).
• Les valeurs ci-dessus sont données à titre d'illustration. Lisez les valeurs réelles dans votre propre appel.

Aujourd'hui, l'API sert un seul modèle Geb. Le champ model d'une complétion est accepté pour la compatibilité avec OpenAI (n'importe quelle chaîne convient) et ne sélectionne pas un modèle plutôt qu'un autre. La réponse indique l'identifiant du modèle qui a réellement répondu.

5.2 Créer une complétion de chat

POST /v2/chat/completions

Acceptés mais ignorés (aucune erreur, aucun effet) : stop, user, seed, temperature, top_p, presence_penalty, frequency_penalty, logit_bias, min_p, top_k, repetition_penalty.

Rejetés avec 400 : n, logprobs, functions. geb_memory: true est également rejeté (memory_unavailable), car les appels API n'ont pas de mémoire.

Les champs inconnus sont des erreurs. Une propriété que Geb ne connaît pas, par exemple max_completion_tokens ou store, renvoie 400 avec un message tel que property store should not exist. Utilisez max_tokens. Si votre bibliothèque cliente ajoute des champs d'elle-même, supprimez-les.

Le corps JSON doit être du JSON valide. Les virgules finales, les commentaires, NaN et les autres erreurs de syntaxe sont rejetés avec 400 invalid_json_body. Une clé qui apparaît deux fois dans un même objet n'est pas une erreur : comme dans tout analyseur JSON standard, la dernière valeur l'emporte. N'envoyez pas de clés en double volontairement.

Les instructions propres à Geb ouvrent chaque prompt. Geb répond en tant que Geb, et ses règles de sécurité ne peuvent pas être contournées. Votre message system vient ensuite et cadre la conversation. Ces instructions sont comptées dans usage.prompt_tokens.

Langue de la réponse. Geb répond dans la langue du dernier message de votre utilisateur et suit un changement de langue en cours de conversation. Une instruction explicite telle que « répondez en français » l'emporte. Un message qui ne décide de rien (« ok », du code) conserve la langue du dernier message clair. Le code, les commandes et les arguments d'outils restent dans leur langue naturelle. Pour l'arabe, votre message system détermine le registre : demandez « arabe standard moderne » ou « arabe égyptien ». À défaut, les livrables écrits et les traductions sont en arabe standard moderne, et la conversation est en arabe égyptien. Une demande de traduction ne renvoie que la traduction.

Réponse. Une complétion normale ressemble à la réponse du démarrage rapide. finish_reason vaut stop (terminée), length (coupée à votre max_tokens, ou écourtée, voir la section 6.4), tool_calls (votre fonction est en cours d'appel) ou content_filter. Vérifiez-le toujours avant d'analyser du JSON dans une réponse.

5.3 Sortie structurée

• Les réponses json_schema sont conformes au schéma. Envoyez "strict": true pour que Geb vérifie d'abord votre schéma : chaque objet exige alors additionalProperties: false et chaque propriété doit figurer dans required, et un schéma qui ne peut pas satisfaire cette exigence est rejeté avec 400, en nommant le chemin fautif. Sans champ strict, Geb utilise votre schéma tel quel et ne le rejette pas : un schéma qui enfreint les règles strictes n'est donc pas une erreur, mais ses réponses ne sont contraintes que dans la mesure où le schéma l'est.
• Vérifiez finish_reason. S'il vaut length, le JSON est incomplet. Un corps JSON coupé n'est jamais signalé comme stop.
• Un appel response_format en streaming est retenu jusqu'à ce que Geb ait vérifié la réponse, puis livré (section 6.3). Des signaux de présence maintiennent la connexion ouverte entre-temps.
• Les outils intégrés de Geb ne s'exécutent pas lors d'un appel response_format.

5.4 Entrée d'images

Les messages de l'utilisateur peuvent contenir des images sous forme de parties de contenu OpenAI. Les images sont envoyées au modèle de vision propre à Geb.

• Sources : URL https:// (récupérées par Geb) ou URI data:image/{png,jpeg,webp,gif};base64,.... Les URL http:// et les autres schémas sont rejetés.
• Formats : PNG, JPEG, WebP, GIF (première image). Les octets doivent correspondre au type déclaré.
• Limites : au plus 16 images par requête, 20 MB par image, 64 MB de données d'image décodées par requête. Envoyez les grandes images sous forme d'URL : le corps entier de la requête est plafonné à 32 MiB.
• Les URL qui pointent vers des adresses privées ou internes sont refusées (image_url_forbidden).
• Les images d'une requête sont présentées avec le dernier message de l'utilisateur, dans l'ordre. Un message contenant uniquement des images est valide. Les parties autres que text et image_url (audio, fichiers) sont rejetées.
• Si le modèle de vision est indisponible à ce moment-là, vous recevez 503 vision_unavailable, jamais une supposition à partir du texte seul. GET /v2/models indique capabilities.vision: false dans le même état.

5.5 Conversations

Vous pouvez envoyer tout l'historique à chaque requête, comme avec n'importe quelle API de chat. Geb peut aussi enregistrer le fil pour vous.

• Envoyez "conversation_id": "new". L'identifiant revient dans la réponse (conversation_id) et dans le dernier fragment du flux.
• Envoyez cet identifiant lors des appels suivants pour poursuivre la conversation.
• Si votre requête contient un message assistant ou tool, vous avez envoyé l'historique : vos messages sont utilisés exactement tels quels. Si elle ne contient que des messages system et user, Geb ajoute le fil enregistré au prompt, en commençant par les tours les plus récents, autant que la fenêtre de contexte le permet. Le nouveau tour est enregistré dans les deux cas.
• Un fil enregistré n'est pas la mémoire du compte. Le chat ne la lit jamais, et aucun autre compte ne peut la lire.

Un identifiant qui n'est pas le vôtre répond 404. Ces trois routes comptent comme des appels API dans votre quota, comme une complétion ; un appel qui échoue n'en consomme pas.

5.6 Règles de réponse (`geb_acceptance`)

Pour un travail où la réponse doit satisfaire une liste de contrôle, déclarez les règles. Geb rédige, vérifie, affine ce qui échoue, et renvoie la meilleure version avec un rapport. Les vérifications de règles ne sont pas facturées : l'appel reste un seul appel.

• Types de règles : word_range, forbidden_phrases, no_repeated_paragraphs, cited_ids_named, min_named_sources, claims_grounded, no_copy_from, phrases_require_source. Un path est un pointeur JSON (JSON Pointer) dans la réponse ; pour une réponse en texte brut, utilisez "" ou /**.
• La réponse porte x_geb_acceptance: {"passed": true, "rounds": 1}, ou passed: false avec une liste failures.
• on_fail: "error_422" transforme un échec final en 422 geb_acceptance_failed.
• Un contrat invalide donne 400 invalid_geb_acceptance, où param nomme la règle et rule_index sa position.
• Un flux avec geb_acceptance est retenu jusqu'à la fin des vérifications (section 6.3).

5.7 En-têtes présents dans chaque réponse

Définissez "stream": true. La réponse est de type text/event-stream : des événements envoyés par le serveur, chacun étant une ligne data: <json> suivie d'une ligne vide.

6.1 Ordre des trames

1. Une ligne de commentaire de remplissage au début (les commentaires commencent par :), qui vide les tampons des proxys. Ignorez-la.
2. Un premier chat.completion.chunk dont le delta porte role: "assistant".
3. Des fragments de contenu, chacun avec du texte dans delta.content.
4. Un dernier fragment avec delta: {} et un finish_reason. Il porte aussi conversation_id lorsque vous utilisez des conversations.
5. Si vous définissez stream_options.include_usage : un fragment de plus avec "choices": [] et un objet usage.
6. data: [DONE].

Les fragments dont le tableau choices est vide sont des métadonnées (utilisation, et extensions de Geb telles que x_geb_acceptance et x_geb_partial). Un analyseur strict doit les ignorer lors de la lecture du texte. Geb ne diffuse jamais en streaming le texte de son raisonnement.

6.2 Signaux de maintien de connexion

Pendant que Geb réfléchit ou vérifie une réponse, la connexion reste ouverte et Geb écrit une ligne de commentaire, : heartbeat, environ toutes les 15 secondes. Les commentaires sont ignorés par tous les analyseurs SSE. Si vous écrivez votre propre analyseur, ignorez toute ligne qui commence par :.

Les en-têtes de réponse d'un flux incluent x-request-id, vos en-têtes X-Quota-* (section 10) et les en-têtes de raisonnement (section 8). Si vous fermez la connexion, Geb cesse de générer.

6.3 Flux retenus

Avec response_format ou geb_acceptance, Geb vérifie la réponse avant de l'envoyer. Le flux s'ouvre avec le commentaire : geb is checking the reply before sending it, puis seulement des lignes : heartbeat, puis le contenu vérifié. Si vous avez besoin des jetons au fur et à mesure de leur génération, n'envoyez aucun de ces deux champs.

6.4 Comment un flux se termine

Un flux se termine toujours par data: [DONE], de l'une des trois manières suivantes.

1. Complet. Un dernier fragment avec finish_reason valant stop (ou tool_calls), puis [DONE].
2. Réponse partielle. Si la génération se bloque ou échoue après l'envoi d'une partie du texte, Geb termine le flux avec ce qu'il a envoyé : un fragment de métadonnées {"choices":[],"x_geb_partial":{"reason":"stalled","code":"geb_dispatch_stalled","complete":false,"chars":123}}, puis un dernier fragment avec finish_reason: "length", puis [DONE]. Traitez-le comme une réponse incomplète. reason vaut stalled, edge_deadline, deadline ou upstream_error. Les réponses partielles ne sont proposées que pour les appels en texte brut ; un appel avec tools ou response_format reçoit à la place la trame d'erreur ci-dessous.
3. Erreur dans le flux. Si rien d'exploitable n'a été produit, une trame data: {"error": {...}} suivie de data: [DONE]. Le statut HTTP était déjà 200, l'erreur ne peut donc pas être un statut HTTP. Les SDK officiels d'OpenAI lèvent une erreur lorsqu'ils voient cette trame.

Un flux qui se ferme sans [DONE] signifie que la connexion a été perdue. Traitez-le comme un échec et faites une nouvelle tentative (utilisez une Idempotency-Key, section 9.3).

Les problèmes que Geb peut détecter avant de commencer, comme une mauvaise clé, une erreur de validation ou un quota épuisé, reviennent sous la forme de véritables statuts d'erreur HTTP, et non de 200.

6.5 Analyser un flux sans SDK

6.6 Longs appels sans streaming

Un appel sans streaming qui s'exécute encore après environ 70 secondes reçoit ses en-têtes 200 plus tôt, suivis d'un seul caractère espace environ toutes les 25 secondes jusqu'à l'arrivée du corps JSON. Un espace en tête est du JSON valide : JSON.parse, fetch().json(), Python requests et les SDK OpenAI lisent donc le corps sans modification. La réponse porte x-geb-keepalive: on lorsque cela s'est produit.

Si un appel échoue après l'envoi de ces en-têtes, le statut reste 200 et le corps est l'objet d'erreur ; lorsque x-geb-keepalive: on est présent, vérifiez donc la présence d'une clé error au niveau supérieur. Envoyez l'en-tête de requête x-geb-keepalive: off pour refuser ce mécanisme et obtenir à la place une 504 geb_edge_deadline au bout d'environ 95 secondes.

Pour les générations longues, utilisez le streaming. Une réponse en streaming n'a pas de limite de durée totale tant qu'elle progresse.

Il existe deux types d'outils différents. Ils sont indépendants et peuvent être envoyés ensemble.

Si vous envoyez les deux, le modèle voit vos fonctions, les appels qu'il renvoie sont à exécuter par vous, et l'exécuteur d'outils propre à Geb ne s'exécute pas pour ce tour.

7.1 Vos fonctions (`tools`)

Vous décrivez vos fonctions, Geb décide quand en appeler une, et vous l'exécutez puis renvoyez le résultat. C'est le protocole standard d'OpenAI : les SDK fonctionnent donc sans modification.

Le modèle répond avec finish_reason: "tool_calls" et message.content valant null :

Exécutez la fonction, puis envoyez une deuxième requête contenant votre historique, le tour de l'assistant exactement tel que reçu, et un message tool par appel :

Règles :

• tools[].type doit valoir "function". function.name correspond à ^[a-zA-Z0-9_-]{1,64}$ et doit être unique. function.parameters est un objet JSON Schema. Au plus 128 outils, et au plus 128 KiB sérialisés.
• function.arguments est une chaîne encodée en JSON, dans les deux sens. Dans un message tool, content doit être une chaîne : sérialisez vous-même votre résultat.
• Répondez à chaque appel. Si un tour de l'assistant a émis trois appels, envoyez trois messages tool avant la complétion suivante. Sinon, vous obtenez 400 unanswered_tool_call qui nomme les identifiants manquants. C'est délibéré : sans réponse, un modèle peut inventer les résultats manquants.
• tool_choice : omis ou "auto" laisse le modèle décider, "none" interdit les appels, "required" exige au moins un appel, et {"type":"function","function":{"name":"..."}} n'autorise que cette fonction. Avec "required" ou une fonction nommée, si le modèle répond en prose au lieu d'appeler, Geb le relance une fois avant de répondre. Cela coûte un passage de modèle supplémentaire en latence, et non un second appel décompté de votre quota. Si le modèle répond encore en prose, vous recevez cette prose avec finish_reason: "stop" : vérifiez donc finish_reason avant de lire tool_calls. Avec un choix nommé, Geb filtre aussi la réponse sur cette fonction. Si vous avez besoin de la garantie la plus forte, utilisez "required" avec un catalogue d'une seule fonction. Sur un flux avec "required" ou une fonction nommée, le texte est retenu jusqu'à la fin du tour puis envoyé, de sorte qu'une réponse en prose arrive d'un seul bloc à la fin.
• Envoyez "parallel_tool_calls": false sauf si vous voulez plusieurs appels par tour. Vous obtenez ainsi exactement un appel propre par tour.
• Geb supprime les appels en double identiques octet pour octet et écarte un dernier appel coupé par length. Les arguments sont sinon transmis tels quels, y compris des arguments qui ne sont pas du JSON valide : validez-les donc avant de les utiliser.
• Le streaming fonctionne. Les appels d'outils arrivent sous forme de trames standard delta.tool_calls (une trame d'ouverture avec id et name, puis des fragments d'arguments, accumulés par index). Ils arrivent ensemble à la fin du tour, sans être entremêlés à la génération. Le résultat accumulé est identique à celui d'un flux OpenAI.
• Un aller-retour d'outil représente deux requêtes, et chacune compte comme un appel.

7.2 Outils intégrés de Geb (`geb_tools`)

Par défaut, un appel API est un simple appel au modèle : une génération, aucun outil, aucun effet de bord. Activez les outils avec geb_tools.

Les noms publics des outils (la liste en direct pour votre appel se trouve dans geb_tools sur GET /v2/models) :

• Un nom que Geb ne reconnaît pas, ou qui est désactivé, renvoie 400 invalid_geb_tools avec la liste des noms valides dans error.valid_geb_tools. Au plus 32 noms.
• Avec une liste, la restriction est appliquée deux fois : le modèle ne voit que les outils nommés, et tout appel à un autre outil n'est pas exécuté (le modèle reçoit une erreur d'outil et répond sans lui).
• Les trois outils build_* sont séparés volontairement. Nommer build_document n'autorise qu'un fichier Word.
• La construction de documents part de votre propre texte d'instruction, jamais de mots désignant un format de fichier dans un contenu que vous avez collé. Si la seule mention de « xlsx » ou de « slides » se trouve dans un bloc de code ou dans un long texte collé, Geb répond en texte.
• Les outils peuvent prendre plus de temps qu'une complétion simple. Les fichiers produits par les outils sont stockés sous votre compte et renvoyés sous forme de liens à durée limitée.
• La mémoire de votre compte, l'historique des chats, les connecteurs (Google, Microsoft, Dropbox, etc.) et les autres outils du compte ne sont pas disponibles via l'API.

Geb réfléchit toujours avant de répondre. Vous choisissez l'intensité. Geb ne renvoie pas le texte de son raisonnement ; vous recevez la réponse, et les jetons de réflexion sont inclus dans usage.completion_tokens.

8.1 Niveaux

GET /v2/models liste les niveaux (reasoning.efforts) et la valeur par défaut du serveur (reasoning.default_effort).

8.2 Ce que signifie « raisonnement désactivé »

La réflexion n'est jamais désactivée. Chaque variante « off » ("off", "none", false, "disabled", 0) laisse la réflexion active avec un budget de réflexion de zéro jeton : le modèle clôt aussitôt son raisonnement et commence la réponse. Vous obtenez une réponse normale, sans étape de raisonnement. Utilisez-le pour les requêtes simples et sensibles à la latence. Pour les problèmes difficiles, préférez medium ou high.

8.3 Comment le demander

Utilisez la forme que votre client envoie déjà. Aucune n'est jamais rejetée.

Correspondances : minimal devient low. xhigh, max et maximum deviennent ultra. Une valeur budget_tokens correspond au niveau le plus proche (jusqu'à 1024, low ; jusqu'à 2048, medium ; jusqu'à 4096, high ; au-delà, ultra). Un niveau inconnu (par exemple "turbo") utilise la valeur par défaut du serveur.

Si vous envoyez plusieurs formes qui se contredisent, la première de cette liste qui nomme un niveau l'emporte : reasoning, reasoning_effort, thinking, enable_thinking, chat_template_kwargs, extra_body. Une forme qui ne fait qu'activer la réflexion ne remplace jamais un niveau nommé ailleurs.

8.4 Ce qui revient

8.5 max_tokens et réflexion

max_tokens est le plafond de la réponse visible. La réflexion est budgétée séparément, en plus de celui-ci : un petit max_tokens n'affame donc pas le raisonnement, et Geb ne multiplie jamais votre nombre. Si la réponse atteint le plafond, elle est coupée à cet endroit et finish_reason vaut length. Lorsque vous ne définissez pas max_tokens, le budget de la réponse est déduit de la fenêtre de contexte. usage.completion_tokens inclut les jetons de réflexion.

9.1 L'enveloppe

Chaque réponse d'erreur d'une route /v2 (et de son alias /v1) est du JSON, dans un seul format :

• type est la classe de l'erreur. Branchez votre logique sur type et code, jamais sur la formulation de message.
• param nomme le champ fautif lorsqu'un champ est en cause, sinon null.
• code est un motif plus précis, lisible par une machine, ou null.
• request_id est toujours présent et est aussi envoyé dans l'en-tête de réponse x-request-id. Chaque réponse porte x-request-id, y compris les réponses réussies. Citez-le lorsque vous contactez le support. Envoyez votre propre x-request-id si vous le souhaitez ; Geb peut tout de même renvoyer son propre identifiant de trace.
• Certaines erreurs ajoutent retry_after_ms au niveau supérieur, à côté de error, et Retry-After comme en-tête (en secondes).
• Les échecs survenant après le début d'un flux arrivent dans le flux (section 6.4). Les échecs survenant après le début d'un long appel sans streaming arrivent sous forme de corps 200 avec une clé error (section 6.6).
• Une requête vers un chemin qui n'existe pas renvoie une 404 simple {"message", "error", "statusCode"}, et non cette enveloppe. Si vous la voyez, vérifiez l'URL.

9.2 Catalogue

Sur un flux, les mêmes erreurs arrivent sous forme de trame d'erreur dans le flux, plus geb_incomplete_stream (la génération s'est arrêtée avant d'être terminée ; réessayez).

9.3 Conseils pour les nouvelles tentatives

• Ne réessayez jamais 400, 401, 403, 404, 409 idempotency_key_reuse, 413, 415, 422. La requête doit changer.
• Réessayez après l'attente pour 429 rate_limit_exceeded et geb_concurrency_limit (utilisez Retry-After), et pour 503 server_busy.
• N'insistez pas sur 429 quota_exceeded. Lisez reset_at dans le corps ou X-Quota-Reset, et arrêtez-vous jusque-là.
• Réessayez immédiatement, une ou deux fois pour 502 empty_answer et 503 geb_instance_shutdown.
• Passez au streaming, puis réessayez pour 504.
• Ajoutez un délai exponentiel avec variation aléatoire (jitter) pour les autres 5xx, avec un plafond de quelques tentatives.
• Envoyez toujours une Idempotency-Key sur les appels que vous pourriez réessayer. C'est une chaîne quelconque d'au plus 255 caractères, unique pour chaque requête logique. Le premier appel s'exécute normalement. Une répétition avec la même clé et le même corps renvoie la réponse enregistrée (Idempotency-Replayed: true), sans nouvelle génération et sans consommer de quota, pendant 24 heures. La réponse rejouée a le même contenu, les mêmes champs et les mêmes valeurs que la première réponse ; l'ordre des clés à l'intérieur de l'objet JSON peut différer : comparez donc le JSON analysé, pas les octets. La même clé avec un corps différent donne 409 idempotency_key_reuse. Une répétition pendant que le premier appel est encore en cours donne 409 idempotent_request_in_progress : attendez, ne bouclez pas. Un flux qui a échoué en cours de route n'est pas enregistré, donc une nouvelle tentative s'exécute à nouveau. L'en-tête Idempotency-Status indique stored, replayed ou disabled.
• Réglez généreusement le délai d'expiration de votre client, ou utilisez le streaming. Les SDK OpenAI envoient leur délai d'expiration dans un en-tête, et Geb renvoie la meilleure réponse partielle (finish_reason: "length", x_geb_partial) plutôt que rien lorsque votre propre délai approche.

Chaque appel se termine par l'une de trois issues : la réponse, une réponse partielle marquée finish_reason: "length" avec x_geb_partial, ou une erreur structurée. Une réponse partielle sans streaming ressemble à ceci :

9.4 Une fonction d'aide pour les nouvelles tentatives

10.1 Quota mensuel d'appels

Tous les forfaits incluent l'API, Gratuit compris, avec un nombre d'appels API par période de facturation. Les jetons ne sont pas comptés et il n'y a aucune facturation au jeton.

• La période est la période de facturation de votre abonnement, ou le mois civil (UTC) si vous n'avez pas d'abonnement.
• Seuls les appels réussis comptent. Un appel qui échoue ne consomme pas de quota. Une réponse rejouée à partir d'une Idempotency-Key ne consomme pas de quota. Les routes de conversation comptent comme des appels. Un aller-retour d'outil compte pour deux appels.
• Au-delà du quota, l'API répond 429 quota_exceeded avec les détails :

Chaque réponse réussie indique votre position dans des en-têtes : X-Quota-Limit-Month, X-Quota-Remaining-Month et X-Quota-Reset. Une 429 de quota les porte aussi, avec Retry-After défini sur le nombre de secondes jusqu'à la réinitialisation.

10.2 Limites de débit

L'utilisation de l'API est mesurée par le nombre mensuel d'appels (section 10.1). La limite par minute n'existe que pour arrêter les rafales et les abus, elle est donc la même pour tous les forfaits. Elle est envoyée dans X-RateLimit-Limit. Une 429 de rafale porte Retry-After. Étalez les rafales, ou utilisez moins de requêtes en streaming, plus longues.

10.3 Limites des requêtes

10.4 Durée

Le streaming n'a pas de limite de durée totale tant que le modèle progresse. Un appel sans streaming est maintenu en vie au-delà du délai d'expiration en périphérie (section 6.6). Un appel qui ne progresse pas pendant trop longtemps se termine par une réponse partielle ou une 504 plutôt que de rester bloqué.

Les SDK Python et JavaScript d'OpenAI fonctionnent avec deux modifications : l'URL de base et la clé.

Ce qui fonctionne de la même façon : chat.completions.create (en réponse complète et en streaming), models.list et models.retrieve, l'appel de fonctions, response_format, stream_options.include_usage, les parties de contenu image, et les erreurs au format OpenAI avec Retry-After.

Différences à prévoir :

• Uniquement des complétions de chat. Les appels aux embeddings, à l'audio, aux images, aux fichiers, aux traitements par lots ou à l'API Responses n'existent pas.
• Les champs inconnus renvoient 400. Ne passez que les champs listés à la section 5.2. En particulier, utilisez max_tokens et non max_completion_tokens, et n'envoyez pas store ni metadata.
• Les champs propres à Geb (geb_tools, geb_acceptance, conversation_id, locale) passent par extra_body en Python (le SDK le fusionne dans le corps de la requête). En JavaScript, passez-les comme propriétés supplémentaires.
• Les champs d'échantillonnage sont ignorés. temperature, top_p, stop, seed et les pénalités sont acceptés et n'ont aucun effet.
• Un seul modèle. model ne sélectionne rien. Utilisez client.models.list() pour voir ce qui est servi.
• Niveaux de raisonnement. reasoning_effort accepte low, medium, high, et aussi ultra (envoyez-le via extra_body si la version de votre SDK type le champ).
• Utilisation côté serveur. N'appelez pas l'API depuis un navigateur sur votre propre domaine.
• Champs de réponse supplémentaires. Les réponses peuvent porter des champs propres à Geb tels que conversation_id et x_geb_*. Ils sont additifs.
• Nouvelles tentatives. Les SDK réessaient d'eux-mêmes sur 429 et 5xx. Ajoutez une Idempotency-Key via extra_headers pour qu'un appel réessayé ne soit ni exécuté ni compté deux fois :

• Aucune mémoire du compte. Les appels API ne lisent jamais la mémoire de votre compte Geb et n'y écrivent jamais. Cela vaut pour chaque clé et chaque forfait.
• Les conversations enregistrées n'existent que si vous utilisez conversation_id. Elles sont séparées de la mémoire, lisibles uniquement par votre compte, et supprimées lorsque vous supprimez la conversation.
• Journaux de l'API. Chaque appel est enregistré pour l'exploitation, le support et la prévention des abus : le contenu de la requête et de la réponse, le modèle, les paramètres, le nombre de jetons, la latence, le statut, votre agent utilisateur, l'identifiant de la clé et le pays de l'appelant. Les identifiants et secrets présents dans le contenu (clés, jetons, mots de passe, URL signées) sont masqués avant stockage. Les images en ligne sont stockées sous forme de taille et d'empreinte uniquement. Une copie de chaque appel est aussi visible par vous, et supprimable par vous, dans vos propres données de l'application Geb. Le journal d'exploitation est conservé pendant toute la vie du compte et supprimé lorsque le compte est supprimé. Les journaux de l'API ne sont jamais utilisés comme mémoire.
• Les fichiers d'outils et les fichiers générés sont stockés sous votre compte et renvoyés sous forme de liens à durée limitée.

N'envoyez pas de données que vous n'avez pas le droit d'envoyer à un service tiers. Si vous avez besoin d'un accord de traitement des données, contactez Geb avant le lancement.

Geb API v2. Servie sur https://api.gebai.ca/v2, avec /v1 conservé comme alias pour les clients existants. Révision 1.1 du guide, 28 octobre 2026.

Ce guide décrit le comportement de l'API en production à cette date. Les champs marqués comme ignorés pourront être pris en compte plus tard ; de nouveaux champs facultatifs peuvent apparaître dans les réponses. Traitez les champs de réponse inconnus comme additifs.

Lorsque vous avez besoin d'aide, indiquez le request_id du corps de l'erreur (ou l'en-tête x-request-id), l'heure de l'appel et la forme de la requête sans la clé. Contactez Geb via https://gebai.ca/contact.