API Structural Diff

Démarrage rapide

Aucun SDK nécessaire. Envoyez une requête POST avec vos deux tableaux de lignes de transcription et recevez un diff complet en JSON. L'API est en phase de dégustation — demandez une clé API pour commencer.

1. Vérifiez que le service est actif :

curl https://structural-diff-engine.onrender.com/v1/health

2. Lancez une comparaison :

curl -X POST https://structural-diff-engine.onrender.com/v1/diff \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "original": [
      { "speaker": "Alice", "start_time": 0, "end_time": 1, "transcript": "Hello world" },
      { "speaker": "Bob",   "start_time": 1, "end_time": 3, "transcript": "Good morning everyone" }
    ],
    "reworked": [
      { "speaker": "Alice", "start_time": 0, "end_time": 1, "transcript": "Hello there" },
      { "speaker": "Bob",   "start_time": 1, "end_time": 2, "transcript": "Good morning" },
      { "speaker": "Bob",   "start_time": 2, "end_time": 3, "transcript": "everyone" }
    ]
  }'

URL de base

Tous les points de terminaison sont préfixés par /v1.

https://structural-diff-engine.onrender.com

Authentification

Incluez votre clé API dans l'en-tête de requête x-api-key à chaque appel vers /v1/diff.

curl -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -X POST https://structural-diff-engine.onrender.com/v1/diff -d '{...}'

Limites de débit

Deux niveaux indépendants sont appliqués par clé API, avec repli sur l'IP en l'absence de clé. Dépasser l'un ou l'autre renvoie 429 Too Many Requests.

Points de terminaison

GET /v1/health

Sonde de disponibilité légère. Aucune authentification requise. Renvoie la version du service et le temps de fonctionnement.

{ "status": "ok", "version": "1.0.0", "uptime": 42, "timestamp": "..." }

POST /v1/diff

Comparez deux tableaux de lignes de transcription. Renvoie des résultats au niveau des lignes avec des scores de qualité. Charge utile max : 5 Mo · Lignes max : 30 000.

Corps de la requête

Champs de l'objet ligne

Tous les champs sont optionnels sauf transcript. Les champs inconnus sont transmis sans modification.

Structure de la réponse

Toutes les réponses réussies utilisent cette enveloppe :

{
  "status": "success",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-04-08T21:00:00.000Z",
  "data": {
    "results": [
      {
        "status": "MODIFIED",
        "originalRow": { "transcript": "Hello world", ... },
        "reworkedRow": { "transcript": "Hello there", ... },
        "notes": "transcript changed"
      },
      {
        "status": "SPLIT",
        "originalRow": { "transcript": "Good morning everyone", ... },
        "reworkedRows": [ { "transcript": "Good morning" }, { "transcript": "everyone" } ],
        "notes": "split into 2 rows"
      }
    ],
    "scores": { "overallCER": 0.12, "overallWER": 0.18, "SegER": 0.33, "transcriptCER": 0.12, "transcriptWER": 0.18, "SER": 0.05, "transcriptSER": 0.04, "SACR": null },
    "composite": { "grade": 3.8, "label": "Good", "percent": "12.3" },
    "meta": { "originalRows": 2, "reworkedRows": 3, "headers": [...] }
  }
}

Statuts de diff

Scores

Note composite

Méta de la réponse

Options de configuration

Passez un objet config dans le corps de la requête pour remplacer les valeurs par défaut de l'algorithme. Tous les champs sont optionnels.

Mappage des colonnes

Lorsque original / reworked sont des tableaux 2D (tableaux de tableaux) plutôt que des objets, fournissez headers et/ou columnMapping pour indiquer au moteur quel index correspond à chaque champ.

{
  "original":      [[0, 1, "Alice", "Hello world"]],
  "headers":       ["start_time", "end_time", "speaker", "transcript"],
  "columnMapping": { "transcript": 3, "speaker": 2, "start_time": 0, "end_time": 1 }
}

Référence des erreurs

Toutes les erreurs utilisent une enveloppe uniforme :

{
  "status": "error",
  "requestId": "550e8400-...",
  "timestamp": "2026-04-08T21:00:00.000Z",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [{ "field": "original", "message": "\"original\" is required" }]
  }
}

Traçage des requêtes

Fournissez un en-tête x-request-id pour corréler les requêtes dans votre système. Caractères alphanumériques, tirets et traits de soulignement uniquement, max 64 caractères. La valeur est renvoyée dans les en-têtes de réponse.

curl -H "x-request-id: job-2026-01-batch-3" \
  -H "x-api-key: YOUR_KEY" \
  -X POST https://structural-diff-engine.onrender.com/v1/diff -d '{...}'

Obtenir un accès API

L'API est disponible pour les agences et équipes en phase de dégustation. Les clés sont provisionnées individuellement. Contactez-nous pour recevoir votre clé et commencer l'intégration.