Audio & Transcription

L'API Audio & Transcription d'AlphaEdge vous permet de transcrire des fichiers audio en texte. Cette fonctionnalité est optimisée pour offrir des performances élevées et une grande précision.

Cette page vous guide à travers l'utilisation de l'API Audio & Transcription, depuis les bases jusqu'aux cas d'usage avancés.

URL d’appel, hôte et documentation

Utilisez la base URL publique de la passerelle, par ex. https://api-endpoints.alphaedge-ai.com. N’appelez pas la gateway par une adresse IP seule si un nom d’hôte public est requis (sinon 403). La documentation utilisateur est sur https://api-docs.alphaedge-ai.com/ ; la passerelle n’expose pas Swagger / OpenAPI interactif en ligne.

Slug et catalogue

La transcription publique n’expose que le slug alpha-audio-v1 pour cette capacité. GET /models renvoie model_slug et type (audio | ocr) pour chaque entrée du catalogue.

Routes exposées (transcription)

• POST /models/{model_slug}/transcript — multipart identique ; réponse 200 synchrone ou 202 si la durée audio dépasse le seuil configurable (TRANSCRIPT_AUTO_JOB_THRESHOLD_SECONDS, défaut 60 s).
• POST /models/{model_slug}/transcript/sync — même formulaire ; réponse toujours synchrone 200 si succès (pas de 202 par ce chemin).
• POST /models/{model_slug}/transcript/jobs — file d’attente asynchrone (multipart identique), réponse 202 avec job_id et status_url.
• GET /models/{model_slug}/transcript/jobs/{job_id} — état du job (queued, running, succeeded, failed).

Voici un exemple minimal pour commencer avec l'API Audio & Transcription :

Exemple basique

import requests

url = "https://api-endpoints.alphaedge-ai.com/models/alpha-audio-v1/transcript"
headers = {"X-API-Key": "TA_CLE"}

with open("/chemin/audio.wav", "rb") as f:
    files = {"audio": ("audio.wav", f, "audio/wav")}
    data = {
        "enable_diarization": "true",
    }
    r = requests.post(url, headers=headers, files=files, data=data, timeout=300)

print(r.status_code)
print(r.json())

curl https://api-endpoints.alphaedge-ai.com/models/alpha-audio-v1/transcript \
  -H "X-API-Key: TA_CLE" \
  -F "audio=@/chemin/audio.wav" \
  -F "enable_diarization=false"

import fs from "node:fs";

const form = new FormData();
form.append("audio", new Blob([fs.readFileSync("/chemin/audio.wav")]), "audio.wav");
form.append("enable_diarization", "true");

const res = await fetch("https://api-endpoints.alphaedge-ai.com/models/alpha-audio-v1/transcript", {
  method: "POST",
  headers: { "X-API-Key": "TA_CLE" },
  body: form
});

console.log(res.status, await res.json());

Voici les paramètres disponibles pour l'API Audio & Transcription :

Le slug du modèle est uniquement dans l’URL (/models/{slug}/transcript). En multipart, le champ fichier doit s’appeler audio (pas file). Les booléens optionnels utilisent les noms enable_diarization et enable_postcorrect.

La post-correction (enable_postcorrect) peut être désactivée temporairement sur certains déploiements ; le nom exact du champ reste enable_postcorrect.

Ne définissez pas Content-Type manuellement pour le multipart : laissez curl -F, requests (files=…) ou fetch(FormData) établir multipart/form-data et le boundary.

L'API Audio & Transcription d'AlphaEdge prend en charge une large variété de formats audio pour la transcription. Voici la liste complète des formats supportés :

Formats audio compressés

• MP3 (.mp3) - Format le plus courant, compression avec perte
• AAC (.aac, .m4a) - Format Apple, bonne qualité à faible bitrate
• OGG Vorbis (.ogg) - Format open source, compression efficace
• OPUS (.opus) - Format optimisé pour la voix, excellent pour les appels
• WMA (.wma) - Windows Media Audio

Formats audio non compressés

• WAV (.wav) - Format PCM non compressé, qualité maximale
• FLAC (.flac) - Compression sans perte, haute qualité
• AIFF (.aiff, .aif) - Format Apple non compressé

Formats audio streaming

• WebM Audio (.webm) - Format web moderne
• M4A (.m4a) - Format conteneur Apple

Spécifications techniques

• Fréquence d'échantillonnage : 8 kHz à 48 kHz (recommandé : 16 kHz ou 44.1 kHz)
• Profondeur de bits : 16 bits ou 24 bits
• Canaux : Mono, stéréo, ou multi-canaux (conversion automatique en mono)
• Durée maximale : 25 minutes par fichier
• Taille maximale : 25 MB par fichier

Formats vidéo (extraction audio)

L'API peut également extraire et transcrire l'audio depuis des fichiers vidéo :

• MP4 (.mp4) - Vidéo avec piste audio
• AVI (.avi) - Format vidéo conteneur
• MOV (.mov) - Format QuickTime
• MKV (.mkv) - Format conteneur open source
• WebM (.webm) - Format web vidéo

Recommandations

• Pour la voix : MP3 à 128 kbps ou WAV 16 kHz mono offrent un bon compromis qualité/taille
• Pour la musique avec paroles : WAV ou FLAC pour préserver la qualité
• Pour les appels téléphoniques : OPUS ou MP3 à 64 kbps mono
• Évitez les fichiers audio de très faible qualité (< 16 kHz) pour de meilleurs résultats
• Pour les fichiers longs (> 25 min), divisez-les en segments

Réponse synchrone HTTP 200 — schéma TranscriptResponse (champs utiles côté client) :

{
  "model_slug": "alpha-audio-v1",
  "text": "…",
  "inference_seconds": 1.2,
  "enable_diarization": false,
  "audio_duration_seconds": 45.3,
  "audio_filename": "audio.wav"
}

Le champ interne gateway_wall_ms n’est pas renvoyé dans le JSON client.

Sur POST .../transcript uniquement, une réponse HTTP 202 est renvoyée lorsque la durée audio atteint ou dépasse le seuil configuré (TRANSCRIPT_AUTO_JOB_THRESHOLD_SECONDS, défaut 60 secondes). Corps typique (TranscriptJobSubmitResponse) :

{
  "job_id": "abc123",
  "status": "queued",
  "status_url": "/models/alpha-audio-v1/transcript/jobs/abc123"
}

Le champ status_url est un chemin relatif : concaténez-le à la même base URL que pour vos appels (ex. https://api-endpoints.alphaedge-ai.com). Enchaînez des GET jusqu’à obtenir succeeded ou failed.

Réponse GET /models/{model_slug}/transcript/jobs/{job_id} — TranscriptJobStatusResponse (extrait) :

{
  "job_id": "abc123",
  "status": "succeeded",
  "created_at": "2026-04-27T10:00:00Z",
  "updated_at": "2026-04-27T10:00:05Z",
  "result": {
    "model_slug": "alpha-audio-v1",
    "text": "…",
    "inference_seconds": 1.2,
    "enable_diarization": false,
    "audio_duration_seconds": 45.3,
    "audio_filename": "audio.wav"
  },
  "error": null
}

Transcription synchrone forcée (/transcript/sync)

Même formulaire multipart que /transcript ; la réponse reste synchrone HTTP 200 en cas de succès (pas de 202 sur ce chemin).

import requests

BASE = "https://api-endpoints.alphaedge-ai.com"
url = f"{BASE}/models/alpha-audio-v1/transcript/sync"
headers = {"X-API-Key": "TA_CLE"}

with open("/chemin/audio.wav", "rb") as f:
    files = {"audio": ("audio.wav", f, "audio/wav")}
    data = {"enable_diarization": "true"}
    r = requests.post(url, headers=headers, files=files, data=data, timeout=300)

print(r.status_code)
print(r.json())

File d’attente (/transcript/jobs) et suivi

Soumission asynchrone puis polling du job (status_url relative ou construction manuelle du GET) :

import time
import requests

BASE = "https://api-endpoints.alphaedge-ai.com"
headers = {"X-API-Key": "TA_CLE"}

with open("/chemin/audio.wav", "rb") as f:
    files = {"audio": ("audio.wav", f, "audio/wav")}
    r = requests.post(
        f"{BASE}/models/alpha-audio-v1/transcript/jobs",
        headers=headers,
        files=files,
        timeout=300,
    )
body = r.json()
job_url = BASE + body["status_url"]

while True:
    st = requests.get(job_url, headers=headers, timeout=60).json()
    if st["status"] in ("succeeded", "failed"):
        print(st)
        break
    time.sleep(2)

Gestion des erreurs

Voici comment gérer les erreurs de manière appropriée :

import requests

url = "https://api-endpoints.alphaedge-ai.com/models/alpha-audio-v1/transcript"
headers = {"X-API-Key": "TA_CLE"}

with open("/chemin/audio.wav", "rb") as f:
    files = {"audio": ("audio.wav", f, "audio/wav")}
    data = {
        "enable_diarization": "true",
    }
    r = requests.post(url, headers=headers, files=files, data=data, timeout=300)

print(r.status_code)
print(r.json())

import fs from "node:fs";

const form = new FormData();
form.append("audio", new Blob([fs.readFileSync("/chemin/audio.wav")]), "audio.wav");
form.append("enable_diarization", "true");

const res = await fetch("https://api-endpoints.alphaedge-ai.com/models/alpha-audio-v1/transcript", {
  method: "POST",
  headers: { "X-API-Key": "TA_CLE" },
  body: form
});

console.log(res.status, await res.json());

Voici quelques cas d'usage courants pour l'API Audio & Transcription :

1. Transcription de réunions

Transcrivez automatiquement les réunions pour archivage et recherche.

2. Sous-titrage de vidéos

Générez des sous-titres automatiques pour vos contenus vidéo.

3. Transcription de podcasts

Créez des transcriptions pour améliorer l'accessibilité et le référencement.

Limitations

• Taille de fichier : Les fichiers ne doivent pas dépasser 25 MB
• Formats supportés : MP3, WAV, M4A, FLAC, AAC, OGG, OPUS, WMA, AIFF, WebM, et formats vidéo (MP4, AVI, MOV, MKV, WebM)
• Durée maximale : 25 minutes par fichier
• Rate limiting : 60 requêtes par minute par défaut (peut être augmenté selon votre plan)

Bonnes pratiques

• Utilisez des fichiers audio de bonne qualité (minimum 16 kHz) pour de meilleurs résultats
• Pour les fichiers longs, divisez-les en segments de 25 minutes maximum
• Gérez les erreurs de manière appropriée avec des try/except
• Implémentez un système de retry pour gérer les erreurs temporaires
• Cachez les résultats lorsque c'est possible pour réduire les coûts
• Surveillez votre utilisation pour éviter de dépasser vos limites

Pour voir tous les modèles audio & transcription disponibles avec leurs spécifications détaillées, consultez la page Nos modèles et filtrez par type.

Référence résumée pour l’intégration (codes typiques renvoyés par la passerelle) :

Pour une liste détaillée des codes d’erreur, voir aussi Codes d’erreur.