API de traduction de documents | Document-Translator.com

Démarrage rapide

Connectez-vous et créez une clé API. Conservez la clé dans la configuration secrète de votre serveur. Les traductions via l’API nécessitent des crédits prépayés ; l’allocation gratuite du navigateur ne s’applique pas.
Extrayez le texte du document dans votre client, attribuez un identifiant stable à chaque segment et demandez un devis. Conservez le document d’origine localement pour pouvoir le reconstituer.
Démarrez avec l’ID du devis, une clé d’idempotence stable et la même charge utile. Interrogez le statut jusqu’à ce que le résultat soit prêt, récupérez les segments traduits et reconstituez votre document.

L’API de traduction accepte du texte extrait et renvoie des segments traduits. Reconstituez le fichier terminé dans votre application, puis enregistrez éventuellement ce fichier traduit pour le télécharger ultérieurement. Ne téléversez pas le fichier original.

Créer un devis

POST /api/v1/quotes
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "version": "document-ir/1",
  "format": "txt",
  "fingerprint": "<64-character SHA-256 of the source file>",
  "sourceLanguage": "auto",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hello, world."
    }
  ]
}

La réponse comprend l’ID du devis, le nombre de mots source, le coût exact en crédits et l’expiration. Les devis sont valables dix minutes. Demander un devis ne réserve pas de crédits et n’enregistre pas le texte du document.

Lancer la traduction

POST /api/v1/translations
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "quoteId": "<quote id>",
  "idempotencyKey": "<stable key, 16–80 letters, digits, underscores or hyphens>",
  "payload": {
    "version": "document-ir/1",
    "format": "txt",
    "fingerprint": "<the same source fingerprint>",
    "sourceLanguage": "auto",
    "targetLanguage": "Spanish",
    "segments": [
      {
        "id": "s0",
        "text": "Hello, world."
      }
    ]
  }
}

Renvoyez au démarrage la charge utile d’origine ayant fait l’objet du devis. Le serveur vérifie son propriétaire et son hachage canonique avant d’enregistrer le texte ou de réserver des crédits. L’ordre des clés de l’objet JSON n’a pas d’importance ; toute modification du texte, de l’ordre des segments, du format, de l’empreinte ou des langues nécessite un nouveau devis.

Créer un flux de travail de traduction de documents

Extrayez le texte et reconstruisez les fichiers téléchargés dans votre application. Envoyez la charge utile affichée ci-dessus, puis utilisez les ID de segment renvoyés pour réinsérer chaque traduction dans son document.

// Run this on your server. Keep your API key private.
const response = await fetch(
  'https://document-translator.com/api/v1/quotes',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  }
);
if (!response.ok) throw new Error('Quote request failed');
const quote = await response.json();
// Show the price before starting with the same payload.

Le DOCX conserve les structures d’origine prises en charge. L’export PDF redistribue le texte et ne reproduit pas exactement la mise en page. Les PDF numérisés ou protégés par mot de passe ne sont pas pris en charge. Vérifiez les traductions importantes et leur mise en forme avant utilisation.

Crédits de traduction et clés API

Chaque document API utilise un crédit du compte, dans les limites de téléversement. Les crédits sont réservés au démarrage et débités lorsqu’une traduction complète et validée est prête. Les crédits bonus d’inscription fonctionnent avec l’API ; l’offre gratuite quotidienne est disponible uniquement sur le site.

Créez jusqu’à cinq clés API actives par compte. Les clés ne sont affichées qu’une seule fois, sont stockées sous forme de hachages et peuvent être révoquées dans le compte. Une clé active peut accéder aux traductions payantes de ce compte, y compris celles créées avec une autre clé du même compte. Les clés ne permettent ni de se connecter ni d’effectuer des paiements.

Nouvelles tentatives et requêtes interrompues

Après une requête de démarrage dont l’issue est incertaine, réutilisez le même identifiant de devis, le même contenu et la même clé d’idempotence. Les nouvelles tentatives identiques renvoient la tâche existante sans facturation supplémentaire. Un contenu modifié ou une clé réutilisée pour un autre devis renvoie le code 409. Les métadonnées des tâches et d’idempotence sont conservées pendant sept jours après la fin de la tâche.

Une tâche échouée pouvant être reprise peut être relancée tant que son texte source reste disponible. La relance conserve son identifiant et réutilise les segments déjà terminés. Les tâches autorisent au maximum trois tentatives de traitement. En cas d’échec du téléchargement, vous pouvez réessayer le point de terminaison du résultat sans lancer une nouvelle traduction.

Interrogation et téléchargements

GET /api/v1/translations/JOB_ID
GET /api/v1/translations?ids=JOB_ID_1,JOB_ID_2
GET /api/v1/translations/JOB_ID/result
PUT /api/v1/translations/JOB_ID/files/txt
GET /api/v1/translations/JOB_ID/files/txt
POST /api/v1/translations/JOB_ID/retry
DELETE /api/v1/translations/JOB_ID

La vérification de l’état par lot accepte au maximum dix identifiants et renvoie { jobs: [...] }, contenant uniquement les tâches autorisées et non supprimées. Interrogez l’état environ toutes les cinq secondes pendant le traitement et toutes les quinze secondes pendant la mise en file d’attente. Faites tourner équitablement les lots si vous récupérez plus de dix tâches. Suspendez les interrogations dans les onglets masqués et arrêtez-les lorsque l’état devient définitif ou en cas d’erreur d’autorisation permanente.

Lorsque l’état indique « ready », récupérez le résultat avec la même autorisation de compte. Il contient la correspondance des segments traduits pour reconstituer le document localement. Les résultats sont accessibles pendant 24 heures après leur achèvement ; les entrées non traitées avec succès expirent une heure après leur création. Les résultats expirés renvoient 410. Les tâches supprimées ou inaccessibles renvoient 404.

Enregistrez un fichier terminé avec PUT en envoyant son contenu binaire, Content-Length et le Content-Type correspondant. Les extensions prises en charge sont docx, pdf, txt et md, avec un seul fichier enregistré par format et une limite de sortie de 50 MB. Répéter un enregistrement réussi conserve le fichier existant. GET télécharge le fichier enregistré ; savedFormats dans l’état du travail répertorie les formats disponibles. L’enregistrement et le téléchargement utilisent les mêmes vérifications de propriété du travail, ne coûtent aucun crédit supplémentaire et ne prolongent jamais le délai de 24 heures.

DELETE annule les tâches en cours ou supprime le texte disponible et les fichiers enregistrés. Supprimer un résultat terminé ne donne pas lieu à un remboursement et ne prolonge pas sa période de téléchargement. Cette version ne propose pas de webhooks de fin de traitement.

Solde et historique du compte

GET /api/v1/translations?before=NEXT_CURSOR&limit=5
GET /api/v1/translations?active=1&before=NEXT_CURSOR
GET /api/account/balance

L’historique est limité au propriétaire actuel et utilise le curseur de pagination renvoyé. Le point de terminaison du solde utilise la session du compte dans le navigateur et renvoie uniquement les informations essentielles sur la connexion et le solde. Lors d’un Checkout en attente, interrogez-le toutes les cinq secondes, dix fois au maximum. Mettez en pause lorsque la page est masquée et arrêtez dès que le crédit est ajouté ou que le compte est déconnecté.

Limites et erreurs

Jusqu’à 50 000 mots source, 400 000 caractères extraits et 12 000 segments de texte par document. Le navigateur limite également les fichiers d’origine à 25 MB et les PDF à 100 pages.
Jusqu’à 100 documents en attente ou en cours de traitement par compte. Les lancements et les nouvelles tentatives partagent les mêmes limites de débit. Respectez l’en-tête Retry-After pour les réponses 429 et utilisez un délai de reprise borné en cas d’échecs temporaires.
Les segments traduits manquants, dupliqués ou mal formés échouent à la validation avant publication et facturation. Les crédits réservés pour les tâches échouées ou annulées avant leur achèvement sont restitués.

Les erreurs comprennent un message et un code. 400 indique une entrée non valide, 401 une autorisation non valide, 402 des crédits insuffisants, 404 une tâche indisponible, 409 un conflit de devis ou d’état, 410 une expiration, 429 une limite de débit ou de capacité, et 503 un service indisponible.

Les documents originaux restent sur votre appareil. Le texte extrait est traité par notre prestataire de traduction, et les fichiers traduits enregistrés sont stockés de manière privée pour le téléchargement. Le stockage temporaire est nettoyé selon un calendrier ; les règles de conservation du prestataire s’appliquent également. Détails de confidentialité