API Keural

Appelez les modèles enregistrés dans Keural au format OpenAI Chat Completions.

L'URL de base a la forme https://<domaine public de votre API>/llm/v1. Le domaine public de l'API varie selon l'environnement : renseignez-vous auprès de votre administrateur.

Les chemins pour les embeddings, la génération d'images, la voix et l'API Responses ne sont pas pris en charge. Une requête envoyée vers ces chemins renvoie 404.

Déroulement de l'utilisationCopier le lien vers la section

PrérequisCopier le lien vers la section

Émettre une clé d'APICopier le lien vers la section

1. Dans le menu de compte, ouvrez Paramètres → API. Dans les applications de bureau et mobiles, l'option se trouve dans le groupe Outils.
2. Dans l'onglet API keys, choisissez l'espace de travail auquel appartient la clé (personnel ou organisation) et le Model ID.
3. Si besoin, définissez une New key expiration (optional, Korea time). Si vous laissez ce champ vide, la clé reste valable jusqu'à sa révocation.
4. Cliquez sur Issue key, puis copiez la clé avec Copy key et conservez-la en lieu sûr. La clé complète n'est affichée qu'à cette étape et ne peut plus être revue après la fermeture de l'écran.

• La clé est liée à l'espace de travail choisi et à un seul modèle. L'utilisation est attribuée à la personne qui a émis la clé.
• Chaque combinaison espace de travail et modèle ne peut avoir qu'une seule clé utilisable. Pour en obtenir une nouvelle, réémettez (Rotate) ou révoquez (Revoke) la clé existante.
• Si vous perdez la clé, réémettez-la ; l'ancienne clé cesse alors immédiatement de fonctionner.
• Si le message indiquant qu'aucun modèle n'est disponible s'affiche, vérifiez avec votre administrateur la visibilité des modèles, votre forfait et l'autorisation API de l'organisation.

Autorisation API des membres de l'organisationCopier le lien vers la section

Réservé aux propriétaires et administrateurs de l'organisation. Pour qu'un membre puisse émettre des clés dans un espace de travail d'organisation, l'administrateur doit d'abord l'autoriser. Par défaut, tous les membres sont bloqués.

Gestion de l'organisation → Organization API comprend les trois sections suivantes. Si le menu n'apparaît pas, la fonction API est désactivée ou votre compte n'a pas les droits d'administration de l'organisation.

Lorsqu'un membre quitte l'organisation ou en est retiré, les clés qu'il avait reçues dans l'organisation sont automatiquement révoquées.

Connecter un clientCopier le lien vers la section

Saisissez les trois valeurs suivantes dans les applications compatibles avec OpenAI API (clients de chat, extensions d'IDE, outils d'automatisation, etc.).

1. Dans les paramètres de l'application, ajoutez une connexion compatible OpenAI (Connection).
2. Saisissez la Base URL et l'API Key, puis enregistrez.
3. Choisissez un modèle dans la liste. La liste n'affiche que le modèle connecté à la clé.
4. Envoyez un message court pour vérifier la réponse.

Les requêtes sont les suivantes.

Première requêteCopier le lien vers la section

export KEURAL_API_KEY='votre_clé_émise'
export KEURAL_BASE_URL='https://<votre-domaine-api>/llm/v1'
export MODEL_ID='ID_du_modèle_sur_l_écran_d_émission'

curl "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Bonjour.\"}]}"

Le model du corps de la requête doit correspondre au modèle connecté à la clé. S'il y a un préfixe de chemin, comme provider/ID_du_modèle, la comparaison porte sur ce qui suit le dernier /. Si elles ne correspondent pas, l'API renvoie 403. La réponse contient toujours dans model l'ID du modèle de la clé.

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["KEURAL_API_KEY"],
    base_url=os.environ["KEURAL_BASE_URL"],
)
res = client.chat.completions.create(
    model=os.environ["MODEL_ID"],
    messages=[{"role": "user", "content": "Bonjour."}],
)
print(res.choices[0].message.content)

Champs de requête acceptésCopier le lien vers la section

L'API n'accepte que ces 18 champs de premier niveau. Si vous en envoyez d'autres, la réponse est 400. Les champs facultatifs dont la valeur est null sont traités comme non envoyés.

MessagesCopier le lien vers la section

• Un message tool ne répond qu'une seule fois à chaque id des tool_calls précédents.
• Les parties image (image_url) ne sont incluses que dans les messages user des modèles qui acceptent les images. Utilisez une adresse http ou https, ou une data URI base64 au format PNG, JPEG, GIF ou WebP. detail peut valoir auto, low ou high.

CorpsCopier le lien vers la section

Si les règles du corps ne sont pas respectées, la réponse est 400 et param vaut body.

StreamingCopier le lien vers la section

Si la requête contient "stream": true, la réponse est envoyée en SSE. Chaque fragment est envoyé sous forme d'événement data: ..., et la fin est signalée par data: [DONE]. Avec "stream_options": {"include_usage": true}, un fragment supplémentaire contenant l'utilisation des jetons est envoyé juste avant [DONE].

Avec include_usage, tous les fragments contiennent usage: null, et le dernier fragment d'utilisation a un tableau choices vide. Les réponses sans streaming ne contiennent usage que lorsque les jetons d'entrée et de sortie ont été confirmés.

L'id de la réponse a la forme chatcmpl-<x-request-id>. Toutes les réponses contiennent l'en-tête x-request-id.

Si une erreur survient pendant le streaming, un événement data: contenant le JSON de l'erreur est envoyé, puis la connexion se ferme sans [DONE]. Si un fragment dépasse 1 MiB ou si la réponse dépasse 16 MiB, la connexion se termine avec 503.

curl -N "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Bonjour.\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true}}"

Limites d'utilisationCopier le lien vers la section

Les requêtes sont limitées par utilisateur, organisation et modèle : nombre de requêtes simultanées, requêtes par minute (RPM) et jetons par minute (TPM). Les valeurs réelles varient selon l'environnement.

Les jetons par minute sont déduits dès la réception de la requête. L'entrée compte 1 jeton pour 4 caractères en anglais, et les autres caractères comptent 1 jeton par caractère ; chaque image compte 2 000 jetons. La sortie est déduite selon max_tokens (4 096 au maximum) : si vous limitez la sortie au strict nécessaire, vous gagnez de la marge dans la limite.

Gestion des clésCopier le lien vers la section

Dans l'onglet API keys de Paramètres → API, consultez l'état des clés (valide, expirée ou révoquée), puis réémettez-les ou révoquez-les.

Les clés sont des chaînes de 51 caractères commençant par krl_llm_. Chaque espace d'émission ne peut avoir qu'une seule clé ; si elle existe déjà, elle est réémise au lieu d'en créer une nouvelle. La date d'expiration ne peut être fixée qu'à partir d'aujourd'hui.

Consulter l'utilisationCopier le lien vers la section

Les requêtes envoyées par l'API et les jetons consommés se consultent à deux endroits.

Conditions de consultationCopier le lien vers la section

Définissez les conditions, puis cliquez sur Rechercher. Pour inclure une requête récente, cliquez sur Actualiser.

Valeurs affichées à l'écranCopier le lien vers la section

• Période de consultation appliquée : la période réellement consultée. Si l'heure de début ou de fin était vide, ou si la période dépassait 90 jours, la période ajustée par le serveur s'affiche.
• Nombre de requêtes et totaux de jetons d'entrée · jetons de sortie · jetons totaux : seules les valeurs confirmées sont additionnées. Les jetons non encore confirmés s'affichent comme Non confirmé.
• Liste des requêtes : chaque requête occupe une ligne avec l'heure, le Model ID, le statut et les jetons d'entrée, de sortie et totaux. 20 lignes sont affichées par page ; utilisez Précédent et Suivant pour naviguer.

En cliquant sur Détails de la requête d'une ligne, les valeurs suivantes s'affichent.

Les requêtes en streaming enregistrent l'utilisation sans stream_options.include_usage. Si une requête est interrompue en cours de route, elle peut rester Partiellement confirmée ou Non confirmée.

Format des erreursCopier le lien vers la section

Les erreurs sont renvoyées au format compatible OpenAI.

{
  "error": {
    "message": "Description de l'erreur lisible par une personne",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}

type dépend du code d'état, et code précise la cause.

Résolution des problèmesCopier le lien vers la section

Si le problème persiste, contactez votre administrateur en lui transmettant les informations suivantes. N'envoyez ni le texte de la clé ni le contenu des prompts.

• Heure de survenue
• ID du modèle utilisé
• Nom et version de l'application cliente
• Valeur de x-request-id dans l'en-tête de réponse
• Message d'erreur affiché à l'écran