Ressources · Contrats de sortie

Contrats de sortie unifiés

Une spécification de contrat de production qui maintient la stabilité des réponses entre les fournisseurs de texte, voix, image et vidéo.

Retour à la documentation Aller au contrat canonique

Contrat de réponse canonique

{
  "success": true,
  "content": "Primary human-readable output",
  "provider": "openai",
  "usage": {
    "input_tokens": 120,
    "output_tokens": 64
  },
  "metadata": {
    "model": "gpt-x",
    "latency_ms": 540,
    "trace_id": "trc_123"
  },
  "images": [],
  "files": [],
  "videos": []
}

Principes de conception

Une enveloppe unique pour toutes les modalités et tous les fournisseurs.
Les noms de champs restent stables entre les versions d'exécution.
Les détails propres au fournisseur résident dans les métadonnées, pas dans la structure de haut niveau.
Les sorties d'une modalité manquante renvoient des tableaux vides, pas des changements de structure.
Le champ success est obligatoire pour un traitement client déterministe.

Référence des champs

success: résultat booléen de l'opération.
content: sortie principale lisible par un humain.
provider: identifiant normalisé du fournisseur.
usage: objet de comptabilisation normalisé.
metadata: diagnostics et contexte d'exécution.
images/files/videos: tableaux de sortie par modalité.
error: objet d'erreur structuré lorsque success=false.

Exemples multi-fournisseurs

Réponse normalisée de type OpenAI

{
  "success": true,
  "content": "Generated response",
  "provider": "openai",
  "usage": { "input_tokens": 90, "output_tokens": 52 },
  "metadata": { "latency_ms": 480 },
  "images": [],
  "files": [],
  "videos": []
}

Réponse normalisée de type Replicate

{
  "success": true,
  "content": "Image generation completed",
  "provider": "replicate",
  "usage": { "input_tokens": 0, "output_tokens": 0 },
  "metadata": { "duration_ms": 2300 },
  "images": [{ "url": "https://..." }],
  "files": [],
  "videos": []
}

Règles de compatibilité client

La logique de rendu côté frontend doit dépendre de la forme de l'enveloppe, et non des détails internes du fournisseur.
Les clients doivent tolérer des clés metadata inconnues pour assurer la compatibilité ascendante.
Les tableaux vides sont des sorties valides pour les modalités non applicables.
L'analyse doit privilégier les vérifications explicites des champs plutôt que le branchement selon le fournisseur.

Error Contract

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request payload",
    "details": {}
  },
  "provider": "system",
  "metadata": {
    "trace_id": "trc_123"
  }
}

Les charges d'erreur doivent inclure un code lisible par machine et un message lisible par un humain.
Les identifiants de trace doivent être propagés pour le diagnostic.
Les réponses success=false ne doivent jamais réutiliser les champs qui sont uniquement présents dans les payloads de succès.
Le statut HTTP et le code d'erreur structuré doivent rester cohérents.