Référence API

API Transcription

Transcrivez des fichiers audio en texte.Quatre endpoints, choisis en répondant à deux questions : voulez-vous le résultat dans la réponse, ou en file d'attente ? Et upload en ligne ou upload présigné ?Synchrone, en ligne : POST /transcribe. Uploadez via multipart/form-data (plafonné à 8 Mio), obtenez la transcription dans la réponse.Asynchrone, en ligne : POST /transcribe/async. Même upload, mais la tâche s'exécute en arrière-plan. Sondez GET /transcribe/{job_id} ou passez un webhook_url pour être notifié à la fin. Les tâches en file d'attente peuvent être annulées avec DELETE /transcribe/{job_id}.Synchrone, présigné : POST /transcribe/by-upload. Appelez d'abord `POST /uploads/presign` pour générer une URL d'upload, PUT votre fichier directement vers cette URL, puis appelez cet endpoint avec l'ID d'upload. La transcription revient dans la réponse. Même limite ASR de 8 Mio.Asynchrone, présigné : POST /transcribe/async/by-upload. Le flux d'upload présigné ci-dessus, exécuté en tâche d'arrière-plan avec webhook optionnel.Formats acceptés : WAV, FLAC et Ogg/Opus.

URL de base: https://api.aethexai.com/api/v1
Endpoints: 6
Portées: transcribe:use

POST/transcribe

Transcrivez un fichier audio de manière synchrone.

Transcrire l'audio

Téléverse un fichier audio via multipart/form-data et retourne la transcription de manière synchrone. Le corps de la requête est plafonné à 8 Mio ; les uploads plus volumineux retournent 413. Les fichiers vides retournent 400. Les appels sont mesurés sur votre compte et déduits des crédits lorsque la transcription se termine avec succès.

Corps de la requête

filebinaryrequis
Fichier audio téléversé en multipart/form-data. Formats acceptés : WAV, FLAC, Ogg/Opus. Maximum 8 Mio. Les autres types de fichiers sont rejetés.
languagestringoptionnel
Indication de langue (ex. english, french). Omettez pour laisser le modèle détecter la langue.
group_idstring (uuid)optionnel
UUID facultatif corrélant plusieurs envois découpés d'un même enregistrement. Envoyez la même valeur avec chaque morceau ; les tableaux de bord agrègent les morceaux en une seule transcription.
group_totalintegeroptionnel
Nombre attendu de morceaux du groupe, 1–10000 (nécessite group_id). Permet aux tableaux de bord de marquer comme partiel un groupe dont tous les morceaux ne sont pas arrivés.

Erreurs

400Fichier vide

Le fichier téléchargé est vide (zéro octet).

Téléchargez un fichier audio non vide.

401Non autorisé

Clé API manquante ou invalide.

Ajoutez X-API-Key: VOTRE_CLÉ à vos en-têtes de requête.

403Interdit

Votre clé API ne possède pas la portée transcribe:use.

Émettez une nouvelle clé avec la portée transcribe:use.

413Charge utile trop volumineuse

Le fichier téléchargé dépasse la limite de 8 Mio.

Compressez ou raccourcissez l'audio pour qu'il tienne sous 8 Mio avant de réessayer. Le flux d'upload présigné a la même limite.

422Entité non traitable

Champ file manquant ou format audio non pris en charge.

Attachez un champ file avec un format audio pris en charge (WAV, FLAC, Ogg/Opus).

503Service indisponible

Le service ASR est temporairement indisponible.

Réessayez après quelques secondes ; le service devrait se rétablir automatiquement.

Requête

json

curl -X POST https://api.aethexai.com/api/v1/transcribe \
  -H "X-API-Key: YOUR_KEY" \
  -F "[email protected];type=audio/wav" \
  -F "language=english"

Réponse 200

json

{
  "id": "8f2b1c4a-9d3e-4f12-9a8c-3b7e1d5f6c2a",
  "text": "Hello, I would like to check the status of my order.",
  "language": "english",
  "duration_seconds": 3.42,
  "segments": [],
  "status": "completed",
  "processing_time_ms": 812,
  "created_at": "2026-05-08T10:00:00Z"
}

POST/transcribe/async

Mettez en file d'attente une tâche de transcription et recevez les résultats via webhook.

Transcrire l'audio (asynchrone)

Accepte un fichier audio, le stocke et traite la transcription en arrière-plan. Le résultat est envoyé à webhook_url à la fin du traitement. Interrogez GET /transcribe/:job_id comme solution de repli si aucun webhook n'est configuré.Champ webhook_status. webhook_status vaut null quand aucun webhook_url n'a été fourni — c'est la valeur stable pour les clients qui n'utilisent que le polling. Les valeurs non nulles (pending, delivered, failed, unsafe) n'apparaissent que lorsqu'un webhook est enregistré. unsafe est retourné si l'URL du webhook est rejetée par la politique SSRF (p. ex. destination réseau privé).

Corps de la requête

filebinaryrequis
Fichier audio à transcrire (multipart/form-data).
languagestringoptionnel
Indication de langue (ex. english, french).
webhook_urlstringoptionnel
URL pour recevoir un POST quand la transcription est terminée. Facultatif — interrogez GET /transcribe/:job_id si omis.

Erreurs

400Fichier vide

Le fichier téléchargé est vide (zéro octet).

Téléchargez un fichier audio non vide.

401Non autorisé

Clé API manquante ou invalide.

Incluez un en-tête X-API-Key valide.

403Interdit

Votre clé API ne possède pas la portée transcribe:use.

Utilisez une clé avec la portée transcribe:use.

413Charge utile trop volumineuse

Le fichier téléchargé dépasse la limite de 8 Mio.

Compressez ou raccourcissez l'audio pour qu'il tienne sous 8 Mio avant de réessayer. Le flux d'upload présigné a la même limite.

422Entité non traitable

Champ file manquant ou format audio non pris en charge.

Attachez un champ file avec un format audio pris en charge.

422URL de webhook invalide

webhook_url est présent mais n'est pas une URL HTTPS valide.

Passez une URL https:// valide ou omettez webhook_url.

422Malware détecté

Le fichier téléchargé a été signalé par le scanner de malware.

Téléchargez un fichier audio propre.

503Service indisponible

Le service ASR est temporairement indisponible.

Réessayez après quelques secondes ; le service ASR devrait se rétablir automatiquement.

Requête

json

curl -X POST https://api.aethexai.com/api/v1/transcribe/async \
  -H "X-API-Key: YOUR_KEY" \
  -F "file=@long_recording.wav;type=audio/wav" \
  -F "language=english"

Réponse 200

json

{
  "id": "a1c4e7d2-5b9f-4e83-8c1a-7e0b9d4f2a16",
  "status": "pending",
  "text": "",
  "language": "english",
  "duration_seconds": null,
  "processing_time_ms": null,
  "error_message": null,
  "webhook_status": null,
  "webhook_last_error": null,
  "webhook_last_attempt_at": null,
  "webhook_delivered_at": null,
  "created_at": "2026-05-08T10:05:00Z",
  "updated_at": "2026-05-08T10:05:00Z"
}

POST/transcribe/by-upload

Transcrivez de manière synchrone un fichier déjà en stockage objet.

Transcrire par ID de téléchargement

Transcrit un fichier audio précédemment téléchargé via POST /uploads/presign. Utile lorsque vous avez déjà stocké le fichier et souhaitez éviter de le re-télécharger.

Corps de la requête

upload_idstringrequis
Jeton de téléchargement signé retourné par POST /uploads/presign. Chaîne opaque, 8 à 8192 caractères.
languagestringoptionnel
Indication de langue (ex. english, french).

Erreurs

401Non autorisé

Clé API manquante ou invalide.

Incluez un en-tête X-API-Key valide.

403Interdit

Votre clé API ne possède pas la portée transcribe:use.

Utilisez une clé avec la portée transcribe:use.

422ID de téléchargement invalide

upload_id n'est pas un jeton de téléchargement signé valide.

Utilisez l'upload_id retourné par POST /uploads/presign.

422Téléchargement introuvable

L'upload_id est valide mais le fichier a déjà été consommé ou a expiré.

Demandez un nouveau jeton de téléchargement via POST /uploads/presign et re-téléchargez le fichier.

503Service indisponible

Le service ASR est temporairement indisponible.

Réessayez après quelques secondes.

Requête

json

curl -X POST https://api.aethexai.com/api/v1/transcribe/by-upload \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "language": "english"
  }'

Réponse 200

json

{
  "id": "8f2b1c4a-9d3e-4f12-9a8c-3b7e1d5f6c2a",
  "text": "Hello, I would like to check the status of my order.",
  "language": "english",
  "duration_seconds": 3.42,
  "segments": [],
  "status": "completed",
  "processing_time_ms": 812,
  "created_at": "2026-05-08T10:00:00Z"
}

POST/transcribe/async/by-upload

Mettez en file d'attente une tâche de transcription depuis un fichier précédemment téléchargé.

Transcription asynchrone par ID de téléchargement

Variante asynchrone de POST /transcribe/by-upload. Met en file d'attente une tâche de transcription en arrière-plan depuis un fichier déjà en stockage objet, puis envoie les résultats à webhook_url à la fin.

Corps de la requête

upload_idstringrequis
Jeton de téléchargement signé retourné par POST /uploads/presign. Chaîne opaque, 8 à 8192 caractères.
languagestringoptionnel
Indication de langue (ex. english, french).
webhook_urlstringoptionnel
URL pour recevoir un POST quand la transcription est terminée. Facultatif.

Erreurs

401Non autorisé

Clé API manquante ou invalide.

Incluez un en-tête X-API-Key valide.

403Interdit

Votre clé API ne possède pas la portée transcribe:use.

Utilisez une clé avec la portée transcribe:use.

422ID de téléchargement invalide

upload_id n'est pas un jeton de téléchargement signé valide.

Utilisez l'upload_id retourné par POST /uploads/presign.

422Téléchargement introuvable

L'upload_id est valide mais le fichier a déjà été consommé ou a expiré.

Demandez un nouveau jeton de téléchargement via POST /uploads/presign et re-téléchargez le fichier.

422URL de webhook invalide

webhook_url est présent mais n'est pas une URL HTTPS valide.

Passez une URL https:// valide ou omettez webhook_url.

503Service indisponible

Le service ASR est temporairement indisponible.

Réessayez après quelques secondes ; le service devrait se rétablir automatiquement.

Requête

json

curl -X POST https://api.aethexai.com/api/v1/transcribe/async/by-upload \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "language": "english",
    "webhook_url": "https://hooks.your-domain.example/webhooks/transcription"
  }'

Réponse 200

json

{
  "id": "a1c4e7d2-5b9f-4e83-8c1a-7e0b9d4f2a16",
  "status": "pending",
  "text": "",
  "language": "english",
  "duration_seconds": null,
  "processing_time_ms": null,
  "error_message": null,
  "webhook_status": "pending",
  "webhook_last_error": null,
  "webhook_last_attempt_at": null,
  "webhook_delivered_at": null,
  "created_at": "2026-05-08T10:05:00Z",
  "updated_at": "2026-05-08T10:05:00Z"
}

GET/transcribe/:job_id

Interrogez le statut d'une tâche de transcription asynchrone.

Obtenir une tâche de transcription

Retourne l'état actuel (pending, processing, completed ou failed) et le texte de la transcription une fois le traitement terminé.

Chemin & Requête

job_idstringrequis
UUID de la tâche de transcription, retourné par POST /transcribe/async.

Erreurs

401Non autorisé

Clé API manquante ou invalide.

Incluez un en-tête X-API-Key valide.

403Interdit

Votre clé API ne possède pas la portée transcribe:use.

Utilisez une clé avec la portée transcribe:use.

404Tâche introuvable

Aucune tâche avec cet ID n'existe.

Confirmez l'id depuis POST /transcribe/async ou POST /transcribe/async/by-upload.

422ID de tâche invalide

job_id n'est pas un UUID valide.

Passez l'UUID retourné par POST /transcribe/async.

Requête

json

curl https://api.aethexai.com/api/v1/transcribe/a1c4e7d2-5b9f-4e83-8c1a-7e0b9d4f2a16 \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "id": "a1c4e7d2-5b9f-4e83-8c1a-7e0b9d4f2a16",
  "status": "completed",
  "text": "Full transcription text appears here once processing completes.",
  "language": "english",
  "duration_seconds": 12.4,
  "processing_time_ms": 1432,
  "error_message": null,
  "webhook_status": "delivered",
  "webhook_last_error": null,
  "webhook_last_attempt_at": "2026-05-08T10:05:14Z",
  "webhook_delivered_at": "2026-05-08T10:05:14Z",
  "created_at": "2026-05-08T10:05:00Z",
  "updated_at": "2026-05-08T10:05:14Z"
}

DELETE/transcribe/:job_id

Annulez une tâche de transcription en attente ou en cours.

Annuler une tâche de transcription

Annule une tâche qui n'est pas encore terminée. Retourne la tâche avec status: cancelled. Les tâches déjà terminées ou annulées retournent 409.

Chemin & Requête

job_idstringrequis
UUID de la tâche de transcription à annuler.

Erreurs

401Non autorisé

Clé API manquante ou invalide.

Incluez un en-tête X-API-Key valide.

403Interdit

Votre clé API ne possède pas la portée transcribe:use.

Utilisez une clé avec la portée transcribe:use.

404Tâche introuvable

Aucune tâche avec cet ID n'existe.

Confirmez l'id depuis POST /transcribe/async.

409Conflit

La tâche est déjà terminée ou annulée.

Seules les tâches en attente ou en cours de traitement peuvent être annulées.

422ID de tâche invalide

job_id n'est pas un UUID valide.

Passez l'UUID retourné par POST /transcribe/async.

Requête

json

curl -X DELETE https://api.aethexai.com/api/v1/transcribe/a1c4e7d2-5b9f-4e83-8c1a-7e0b9d4f2a16 \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "id": "a1c4e7d2-5b9f-4e83-8c1a-7e0b9d4f2a16",
  "status": "cancelled"
}