API de traduction de texte

Cette API traduit du texte sous forme de tâches mises en file d’attente, avec une seule langue cible par tâche. Envoyez le texte, conservez l’identifiant de tâche renvoyé et consultez la tâche jusqu’à la fin du traitement. Envoyez chaque requête en HTTPS avec les identifiants de votre compte, soit les identifiants HTTP Basic présentés dans les exemples, soit un jeton API, comme indiqué dans Authentification. Conservez les identifiants sur votre serveur.

Points de terminaison

Les deux serveurs API, https://api.multi.tel et le serveur de compatibilité https://api.multitel.net, partagent, au niveau du compte, les tâches, les clés d’idempotence, les limites et la facturation. L’enveloppe des réponses diffère : utilisez donc toujours le même serveur avec un analyseur adapté.

Sur api.multi.tel, chaque chemin est également disponible avec le préfixe /v1/translate à la place de /v3/translate. Sur api.multitel.net, utilisez les chemins /v3/translate.

La réponse d’information sur le service indique enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages et ratesNanosPerCharacter. cpuLanguages répertorie les codes de langue de base acceptés pour la traduction standard. ratesNanosPerCharacter donne le prix configuré par point de code source pour chaque moteur, en milliardièmes de dollar américain : une valeur de 5000 correspond à $5 par million de points de code. La réponse n’indique pas si la traduction améliorée est actuellement disponible ; une estimation améliorée renvoie 503 lorsqu’elle ne l’est pas. Sa consultation est gratuite.

Traduire du texte

Envoyez du JSON avec Content-Type: application/json à POST https://api.multi.tel/v3/translate. Chaque tâche a une seule langue cible : soumettez donc une tâche distincte pour chaque cible.

Les codes de locale sont des balises BCP 47 de 2 à 63 lettres, chiffres et traits d’union. Ils sont convertis en forme canonique : en-us est ainsi enregistré sous en-US. Les balises non valides, ainsi que und, mul ou zxx, renvoient 400 invalid_translation_language. La disponibilité standard est vérifiée par langue de base ; nb et nn sont comptés comme no. Une cible régionale telle que fr-CA est acceptée et enregistrée, mais le résultat standard suit la langue de base et ne reflète pas nécessairement la région.

Sur ce serveur, limitez le corps de la requête à 128 KiB. Envoyez le texte en UTF-8 plutôt que d’échapper chaque caractère non ASCII avec une séquence \u, ce qui peut faire dépasser la limite à une requête de 20,000 caractères.

Le corps accepte uniquement ces quatre champs. Toute autre propriété est rejetée avec 400 invalid_translation_request, y compris idempotency_key, les identifiants de propriétaire, les indicateurs de traitement gratuit et les tableaux de segments.

Idempotence et réutilisation

Chaque soumission nécessite un en-tête Idempotency-Key de 1 à 190 caractères. Utilisez des lettres ASCII, des chiffres, -, _, . et :, sans espaces au début ni à la fin ; une clé absente ou d’au moins 191 caractères est rejetée avec 400. Les clés sont limitées à votre compte et à la traduction, sur les deux serveurs et pour tous les identifiants de votre compte.

• La même clé avec le même texte, les mêmes langues sous forme canonique et le même moteur renvoie la tâche existante avec HTTP 200 et duplicate: true, sans nouvelle facturation.
• La même clé avec un texte, des langues ou un moteur différents renvoie 409 idempotency_conflict. La même clé renvoie aussi 409 si la version du traitement a changé depuis la création de sa tâche. Dans ce cas, consultez la tâche d’origine par son identifiant au lieu de la soumettre à nouveau.
• Une nouvelle clé avec le même texte, les mêmes langues sous forme canonique et le même moteur renvoie la tâche existante avec HTTP 200 et duplicate: true, sans nouvelle facturation du traitement, si une tâche ayant ce contenu et la version de traitement actuelle est en file d’attente, en cours, terminée ou en attente de paiement. Une tâche réutilisée en attente de paiement doit toujours être réglée. Les tâches en échec ne sont pas réutilisées : une nouvelle tâche est créée et facturée lorsqu’elle se termine.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: translation-example-001" \
  --data '{"text":"Please move my appointment to Tuesday at 3 PM, not 11 AM.","source_language":"en","target_language":"es","engine":"cpu"}' \
  -o translation-job.json \
  https://api.multi.tel/v3/translate

node -p 'JSON.parse(require("node:fs").readFileSync("translation-job.json","utf8")).data.id'

Une nouvelle tâche renvoie HTTP 202. Le texte de l’exemple contient 57 points de code ; à $5 par million de points de code, il coûte donc $0.000285. Voici une réponse abrégée (l’identifiant est un exemple) :

{
  "status": "success",
  "data": {
    "id": "8b2e4c71-5d3a-4f09-a6e2-1c7f9d3b5a28",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "engine": "cpu",
    "sourceLocale": "en",
    "targetLocale": "es",
    "sourceCharacters": 57,
    "costUsd": "0.000285000",
    "costIsEstimate": true,
    "pricePerMillionCharactersUsd": "5.000000000",
    "progress": null
  }
}

Une soumission peut aussi renvoyer 402 insufficient_balance si le solde prépayé ne couvre pas la tâche et vos autres tâches en cours, et 429 translation_queue_full si votre compte ou le service a trop de tâches en cours. Elle renvoie 503 dans les cas suivants :

• paid_translation_not_enabled lorsque la traduction payante est désactivée.
• translation_unavailable pour une requête améliorée lorsque la traduction améliorée est indisponible.
• translation_pricing_unavailable lorsque le moteur choisi n’a pas de tarif configuré.

En cas de réponse 429 ou 503, réessayez plus tard avec la même clé.

Choisir la qualité

Les textes longs sont traités en petits morceaux, puis réassemblés. Les sauts de ligne et les espacements peuvent changer, et une phrase peut perdre du contexte à la frontière entre deux portions traitées. Conservez le texte original et vérifiez le résultat assemblé. La traduction standard utilise la langue de base d’une balise régionale : accepter et enregistrer une balise ne garantit pas une formulation régionale.

La traduction standard s’exécute sur des processus de traitement CPU. La traduction améliorée envoie le texte au service d’IA externe configuré. Son résultat doit lui aussi être vérifié : le service ne garantit pas qu’un moteur soit plus précis pour toutes les paires de langues ou tous les types de texte.

La traduction standard est une ébauche dont la qualité et le temps de traitement varient selon la paire de langues. La traduction améliorée est destinée aux textes pour lesquels le contexte compte, mais les noms, nombres, négations et engagements importants doivent toujours être vérifiés. Aucune des deux options ne corrige les erreurs déjà présentes dans une transcription originale : conservez donc l’original pour comparaison.

Utilisez GET /v3/translate sur le même serveur API pour vérifier la disponibilité actuelle, les langues standard prises en charge et les tarifs configurés. Une requête standard dont la langue de base source ou cible ne figure pas dans cpuLanguages renvoie 422 translation_language_pair_unavailable. Lorsque source_language est fourni et a la même langue de base que la cible, la requête renvoie 409 translation_same_language au lieu de créer une tâche. La traduction améliorée est activée séparément : lorsqu’elle est indisponible, les soumissions et estimations améliorées renvoient 503.

Estimer d’abord

Sur api.multi.tel, envoyez le même corps JSON à POST /v3/translate/estimate. Aucune clé d’idempotence n’est nécessaire. Une estimation applique les mêmes validations, y compris les contrôles 422 et 409, mais ne crée pas de tâche, ne traduit pas le texte, ne réserve pas de fonds, ne vérifie pas votre solde et ne facture pas votre compte. Elle renvoie HTTP 200 avec estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd et costUsd sous data. Pour l’exemple ci-dessus, costUsd vaut 0.000285000 au tarif standard. Lorsque la traduction améliorée est indisponible, une estimation améliorée renvoie 503 service_unavailable. Les estimations utilisent le tarif actuellement configuré. Le tarif d’une tâche est fixé à sa création, et sa facturation utilise ce tarif.

Récupérer la traduction

Une nouvelle soumission renvoie HTTP 202 ; une tâche existante ou réutilisée renvoie HTTP 200. Conservez data.id et suivez le déroulement des tâches commun. L’objet de tâche contient les champs suivants :

• id, status, engine, sourceLocale et targetLocale.
• sourceCharacters, costUsd, costIsEstimate et pricePerMillionCharactersUsd.
• progress et createdAt.
• modelVersion, une chaîne opaque indiquant la version du traitement.
• duplicate dans les réponses réutilisant une tâche.
• failureCode pour les tâches en échec : translation_failed, translation_timeout, input_failed ou worker_lease_lost.

Une tâche en échec affiche un costUsd de zéro.

Une tâche terminée contient data.result avec sourceLocale (vide si aucune langue source n’a été fournie), targetLocale, le texte traduit dans text (textes des segments réunis par des sauts de ligne), et segments. Pour le texte soumis par cette API, segments contient une seule entrée avec le texte traduit dans text et la langue cible dans language. Les résultats des tâches en attente de paiement restent bloqués jusqu’au règlement.

Utiliser api.multitel.net

Le point de terminaison de compatibilité POST https://api.multitel.net/v3/translate accepte les mêmes champs JSON et le même en-tête Idempotency-Key. Si l’en-tête est absent, il accepte aussi une chaîne idempotency_key dans le corps JSON. Tout autre champ supplémentaire est rejeté avec 400 unsupported_translation_option. Sur ce serveur, le corps brut peut atteindre 256,000 octets, et un texte de plus de 20,000 points de code renvoie 413 translation_too_large au lieu de 400. Un champ source_language vide est traité comme omis. Une réponse 429 inclut Retry-After: 15. Ce serveur renvoie aussi les erreurs suivantes :

• 400 json_body_required si le corps est absent, s’il ne s’agit pas de JSON valide ou s’il s’agit d’un scalaire JSON. Envoyez un objet JSON.
• 400 invalid_translation_options lorsque text, target_language ou engine est absent, vide ou n’est pas une chaîne, ou si source_language n’est pas une chaîne.
• 400 invalid_translation_text pour un texte composé uniquement d’espaces blancs.
• 400 invalid_translation_engine pour un moteur inconnu.
• 400 idempotency_key_required pour une clé absente, vide ou trop longue, ou un idempotency_key qui n’est pas une chaîne.
• 400 invalid_job pour un identifiant de tâche mal formé.

Les réponses du service de traduction de ce serveur utilisent l’enveloppe {"status":{"code":HTTP_STATUS},"response":{...}}, où status est un objet. Lisez l’identifiant de tâche dans response.id et le résultat terminé dans response.result. Les erreurs placent le code dans response.code, sans message ni identifiant de requête. Les échecs d’authentification (401) sont renvoyés par le contrôle général de connexion du serveur et peuvent avoir un corps différent : vérifiez donc le statut HTTP avant l’analyse. Les tâches sont partagées avec le serveur principal, mais utilisez le même serveur pour l’interrogation périodique, le règlement et l’utilisation afin que votre analyseur corresponde à l’enveloppe. Ce serveur accepte aussi les mêmes champs JSON à /v3/translate/estimate sans clé d’idempotence, et son estimation se trouve sous response.