API compatible OpenAI
Endpoints /v1, chat completions, en-têtes, codes d’erreur, streaming et cache.
La passerelle expose des endpoints compatibles OpenAI sous l’URL de base /v1. Les clients OpenAI peuvent pointer vers la passerelle plutôt que vers le fournisseur.
Endpoints#
| Méthode et chemin | Fonction |
|---|---|
| POST /v1/chat/completions | Chat completions OpenAI, natif ou via facade vers des backends Anthropic. |
| POST /v1/responses | Relay Responses API pour SDK récents, adapté au chat dans le même pipeline. |
| POST /v1/embeddings | Embeddings OpenAI routés vers le fournisseur configuré. |
| GET /v1/models | Liste des modèles enregistrés. |
Les alias de route habituels sont acceptés pour connecter outils et SDK existants.
Endpoint Gateway (images, audio, fichiers, fine-tuning, lots)#
D’autres interfaces compatibles OpenAI peuvent être activées en plus de chat, messages et embeddings. Elles sont désactivées par défaut ; endpoint désactivé renvoie 404 endpoint_disabled. Configurez dans Settings -> Endpoint Gateway :
| Surface | Contrôle | Comportement |
|---|---|---|
| /v1/images/generations, edits, variations | images | Inspecte, masque et compresse le prompt JSON comme chat ; inspecte métadonnées et utilise un cache soumis à l’inspection. |
| /v1/audio/speech | audio | Inspecte l’entrée comme prompt de chat et la relaie. |
| /v1/audio/transcriptions, translations | passthrough | Relay multipart gouverné, injection de clé et audit. |
| /v1/files | files | Décode et inspecte fichiers texte ; bloque les téléversements non conformes, laisse passer les binaires. |
| /v1/fine_tuning/jobs, /v1/batches | passthrough | Relay gouverné avec injection de clé et audit. |
Les pixels et formes d’onde ne sont pas analysés, uniquement le texte associé. Le journal des transactions indique le type d’endpoint.
En-têtes#
| En-tête | Fonction |
|---|---|
| Authorization: Bearer [key] | Authentification client et/ou clé upstream selon la configuration. |
| X-Agent-ID | Identité d’agent pour suivi, routage, risque et portée du cache. |
| X-User-Id | Identité utilisateur ; les claims sub du token authentifié sont préférées. |
| x-aifw-cache-refresh | Ignore la recherche cache, mais autorise l’écriture. |
Requête standard#
POST /v1/chat/completions
{
"model": "gpt-4o",
"messages": [
{ "role": "system", "content": "You are a helpful assistant." },
{ "role": "user", "content": "Hello!" }
],
"stream": false
}| Champ | Notes |
|---|---|
| model | Facultatif ; le modèle par défaut est utilisé s’il est omis. |
| messages | Messages standard ; tool_calls/tool transmis octet pour octet. |
| stream | true applique le mode buffered ou live effectif. |
Codes d’erreur#
Les requêtes bloquées ou refusées renvoient HTTP 400 et une erreur structurée :
{
"error": {
"message": "The transaction was intercepted and blocked by corporate AI security policy.",
"type": "guardrail_violation",
"code": "prompt_injection_detected",
"details": { "policy_id": "BUILTIN-JAILBREAK", "timestamp": "2025-01-15T10:00:00Z" }
}
}| Code | Signification |
|---|---|
| guardrail_violation | Blocage d’une règle intégrée/personnalisée ; détails avec ID de politique. |
| prompt_injection_detected | Règle jailbreak/injection correspondante. |
| semantic_rule_violation:rule | Score sémantique au-dessus du seuil block. |
| model_disabled | Modèle enregistré mais désactivé. |
| model_not_registered | Mode strict activé, modèle absent du registre. |
| backend_not_configured | URL backend absente pour le modèle choisi. |
| default_policy_block | Aucune règle correspond et l’action implicite est block. |
Les réponses bloquées comprennent X-Gateway-Security: Violated. Authentification invalide : 401 ; route inconnue : 404.
Streaming#
Avec stream: true, les réponses utilisent server-sent events et se terminent par data: [DONE].
- buffered (défaut) : réponse complète inspectée avant livraison ; violation = 400 avant transmission.
- stream : tokens transmis en direct ; violation en cours = arrêt SSE avec guardrail_violation. Les tokens déjà envoyés ne peuvent être retirés.
Cache#
Avec une portée configurée, les réponses peuvent provenir du completion cache. Les hits sont journalisés et le body est réinspecté à la relecture.