Jobs de transcription et de traduction

Remplacez SERVICE ci-dessous par speech_to_text ou translate, et JOB_ID par l’UUID reçu. Toutes les opérations nécessitent les identifiants de votre compte, comme indiqué dans Authentification, et sont limitées au compte propriétaire. Un job peut être lu depuis les deux hôtes API, mais chacun utilise sa propre enveloppe de réponse : utilisez donc toujours le même hôte.

Sur api.multitel.net, les échecs d’authentification (401) sont renvoyés avant l’application de cette enveloppe et peuvent avoir un corps différent. Vérifiez le statut HTTP avant d’analyser la réponse.

Authentification

Chaque requête doit contenir les identifiants de votre compte. Les jobs, clés d’idempotence, limites, données d’utilisation et frais appartiennent au compte propriétaire des identifiants. Ils sont partagés entre tous les identifiants de ce compte sur les deux hôtes, quels que soient ceux utilisés pour envoyer la requête.

• HTTP Basic (Authorization: Basic, ou curl --user). Les identifiants acceptés sont ceux d’un compte API de type mot de passe, d’un sous-compte ou de votre compte principal. Nous recommandons un compte API dédié. Le nom d’utilisateur ne peut pas contenir de deux-points, et ni le nom d’utilisateur ni le mot de passe ne peuvent être vides.
• Jeton Bearer (Authorization: Bearer YOUR_TOKEN). Accepté pour un compte API de type jeton. Ces comptes doivent avoir une restriction IP et les requêtes doivent provenir d’une adresse autorisée. Les deux hôtes API acceptent les adresses IPv4 et les plages CIDR configurées pour le compte. Un jeton ne peut pas être envoyé comme mot de passe Basic. Vérifiez que votre jeton fonctionne sur l’hôte utilisé.

API_TOKEN="your-api-token"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.multi.tel/v3/speech_to_text

Si un compte API est limité par adresse IP, envoyez les requêtes depuis une adresse autorisée. Des identifiants absents ou invalides renvoient 401. Sur api.multitel.net, des identifiants valides mais non utilisables pour ces services, par exemple ceux d’un compte de type jeton envoyés en Basic, renvoient 403 unsupported_transcription_principal ou unsupported_translation_principal. Des échecs d’authentification répétés depuis une même adresse sur api.multitel.net peuvent entraîner le blocage de cette adresse. Corrigez les identifiants avant de réessayer.

Vérifier la fin du traitement

Envoyez une requête GET /v3/SERVICE/JOB_ID. Nous recommandons de ne pas interroger le service plus d’une fois toutes les 3 secondes. L’enveloppe extérieure décrit la requête ; consultez le champ status du job pour savoir si le traitement est terminé.

API_USER="your-api-username"
API_PASSWORD="your-api-password"
SERVICE="speech_to_text"
HOST="https://api.multi.tel"
JOB_ID=$(node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id')

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/$JOB_ID"

Sur api.multitel.net, définissez HOST sur https://api.multitel.net et lisez .response.id au lieu de .data.id.

Réessayer sans risque les requêtes au résultat incertain

Si une soumission expire ou renvoie 429 ou un statut 5xx, renvoyez les mêmes données avec la même clé d’idempotence. Une réponse de l’un ou l’autre hôte peut être perdue ou remplacée par une erreur après l’acceptation du travail ; renvoyer la même clé restitue le job s’il existe. Réutiliser une clé avec des données différentes renvoie 409 idempotency_conflict. Certaines erreurs se répètent à chaque tentative, par exemple 503 lorsqu’un service payant est désactivé ou 500 pour un fichier audio illisible. Arrêtez après quelques tentatives.

Changer de clé a des effets différents selon le service.

• Pour la transcription audio, une nouvelle clé crée un nouveau job, facturé séparément si le traitement réussit. La clé initiale continue de restituer le job initial, même après une mise à jour du traitement.
• Pour la traduction, une nouvelle clé avec un contenu identique restitue sans nouveaux frais un job correspondant en attente, en cours, terminé ou en attente de paiement. Elle crée un nouveau travail si le job précédent a échoué ou si la version de traitement a changé. Une nouvelle tentative de traduction avec la clé initiale renvoie 409 après un changement de version de traitement ; conservez donc l’ID du job initial et consultez-le directement.

Débloquer un résultat après avoir crédité le compte

Pour un job au statut awaiting_payment, créditez le compte afin que votre solde couvre au moins la valeur costUsd du job, arrondie au multiple supérieur de $0.00001, puis envoyez POST /v3/SERVICE/JOB_ID/settle. Les débits se font par pas entiers de $0.00001 et incluent le reliquat reporté des jobs précédents du même service. Le montant débité peut donc dépasser costUsd de moins de $0.00001. Sur api.multi.tel, envoyez le JSON {} ou un corps vide ; toute propriété dans le corps est rejetée avec 400. api.multitel.net ignore le corps. Le règlement débloque le résultat enregistré sans relancer la transcription ou la traduction. La réponse contient le job ; vérifiez que son statut est completed. Si le solde est toujours insuffisant, le job reste au statut awaiting_payment et la réponse reste HTTP 200.

Pour la transcription audio, régler un job déjà terminé le restitue avec duplicate: true, et régler un job en attente, en cours ou échoué renvoie 409 transcription_not_awaiting_payment. Pour la traduction, régler un job dans tout autre statut le restitue sans changement. Le règlement est disponible uniquement lorsque le traitement payant est activé (sinon 503). Les jobs en attente de paiement comptent dans le coût réservé : pour les comptes prépayés, ils peuvent donc bloquer les nouvelles soumissions payantes avec 402 jusqu’à leur règlement.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -X POST -H "Content-Type: application/json" --data '{}' \
  "$HOST/v3/$SERVICE/$JOB_ID/settle"

Consulter l’utilisation

Utilisez GET /v3/SERVICE/usage. Les paramètres facultatifs from et to sont des dates UTC au format YYYY-MM-DD, et les deux dates limites sont incluses. S’ils sont omis, from vaut par défaut la date située 30 jours avant aujourd’hui et to vaut la date d’aujourd’hui (UTC). to ne doit pas être antérieure à from, et les dates peuvent être espacées de 366 jours au maximum (jusqu’à 367 dates incluses). Des dates calendaires invalides ou une plage inversée ou plus longue renvoient 400, tout comme les autres paramètres de requête sur api.multi.tel.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/usage?from=2026-10-01&to=2026-10-31"

La réponse contient mode, currency (USD), from, to et days, une liste triée de la plus récente à la plus ancienne.

• Les entrées de transcription audio sont regroupées par date et par source. Elles contiennent date, source (api, ou hpbx pour les enregistrements Hosted PBX), files, audioSeconds, billedSeconds, accruedUsd et debitedUsd.
• Les entrées de traduction sont regroupées par date, source et moteur. Elles contiennent date, source, engine, jobs, sourceCharacters, accruedUsd et debitedUsd.

accruedUsd est le coût exact avec neuf décimales, et debitedUsd le montant débité, avec cinq décimales. L’utilisation est enregistrée à la date UTC du règlement de chaque job ; les jobs en attente, en cours, échoués et en attente de paiement n’y figurent donc pas.

Limites

Chaque compte peut avoir au maximum 50 jobs de transcription audio et de traduction non terminés au total : en attente, en cours ou en attente de paiement, y compris les traitements d’enregistrements Hosted PBX. Lorsque cette limite ou la capacité globale du service est atteinte, les soumissions renvoient 429 transcription_queue_full ou translation_queue_full. api.multi.tel limite également chaque adresse IP cliente à 300 requêtes par minute, toutes requêtes vers cet hôte confondues. Cette limite renvoie 429 avec des en-têtes de limitation de débit et un corps en texte brut, au lieu de l’enveloppe d’erreur JSON.

Gérer les erreurs de requête

Sur l’hôte principal, les échecs renvoient un statut d’erreur HTTP et un JSON contenant status: "error", code, message et requestId. Chaque réponse comporte également un en-tête X-Request-ID. Vous pouvez fournir votre propre valeur ; les valeurs de plus de 128 caractères sont tronquées. L’hôte de compatibilité renvoie uniquement le code d’erreur dans response.code. Enregistrez l’ID de requête, lorsqu’il est disponible, et le code d’erreur, mais ne consignez pas les fichiers audio, textes ou identifiants dans les journaux.

Statuts courants :

Suivez le code d’erreur renvoyé plutôt que de supposer que tous les échecs de validation ont le même statut.

Pour 429 ou 503, attendez et réessayez avec des délais croissants et la même clé de soumission ; respectez Retry-After lorsqu’il est présent. Pour des données d’entrée ou des identifiants invalides, corrigez d’abord la cause. N’envoyez pas continuellement de nouvelles clés tant que les jobs précédents sont en attente.