API de traduction de documents

node --env-file=.env translate-text.mjs input.txt Spanish translated.txt
node --env-file=.env translate-text.mjs input.txt Spanish translated.txt --start

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

{
  "version": "document-ir/8",
  "format": "txt",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "sourceLanguage": "auto",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hello, world."
    }
  ]
}

POST /api/v1/quotes?output=best-effort-v1

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

{
  "quoteId": "<quote id>",
  "idempotencyKey": "my-document-0001",
  "payload": {
    "version": "document-ir/8",
    "format": "txt",
    "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
    "sourceLanguage": "auto",
    "targetLanguage": "Spanish",
    "segments": [
      {
        "id": "s0",
        "text": "Hello, world."
      }
    ]
  }
}

GET /api/v1/translations/JOB_ID/result
Authorization: Bearer doctr_...

{
  "version": "document-ir/8",
  "jobId": "<job id>",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hola, mundo."
    }
  ],
  "mock": false
}

Un devis avec cURL

Enregistrez le JSON du devis ci-dessus sous le nom payload.json et définissez DOCUMENT_TRANSLATOR_API_KEY dans votre terminal. Cette commande demande uniquement un devis. Pour démarrer, envoyez le JSON de démarrage avec l’ID de devis renvoyé et la charge utile identique au point de terminaison de traductions.

curl https://document-translator.com/api/v1/quotes \
  -H "Authorization: Bearer $DOCUMENT_TRANSLATOR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @payload.json

Dans PowerShell, utilisez curl.exe et $env:DOCUMENT_TRANSLATOR_API_KEY ; écrivez la commande sur une seule ligne au lieu d’utiliser les barres obliques inverses de continuation affichées ci-dessus.

Crédits de traduction et clés API

Chaque document envoyé à l’API réserve un crédit du compte, dans la limite des plafonds. Les traitements stricts ne sont facturés qu’une fois validés et prêts ; les traitements échoués ou annulés avant leur achèvement libèrent la réservation. Avec un résultat au mieux, de petites lacunes peuvent utiliser le crédit convenu, tandis que les lacunes importantes ou les erreurs critiques libèrent celui-ci. Consultez outcome.creditOutcome et outcome.completion au lieu de supposer que chaque résultat prêt a été facturé.

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

GET /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID
DELETE /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID

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 100 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 100 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.

queued → processing → ready
                   ↘ failed / cancelled / expired

{"jobs":[{"id":"<job id>","state":"processing","completedChunks":1,"totalChunks":2}]}

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, pptx, xlsx, 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.

PUT /api/v1/translations/{id}/files/docx
X-Download-Kind: reading-copy
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Length: {bytes}

{binary DOCX body}

GET /api/v1/translations/{id}

{"savedFormats":["docx"],"savedDownloads":[{"format":"docx","kind":"reading-copy"}]}

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.

PUT /api/v1/translations/{id}/manifest
Content-Type: application/json
Content-Length: {bytes, maximum 2 MiB}

{"version":1,"parserVersion":"document-ir/8","fingerprint":"{original SHA-256}","ocr":[]}

PUT /api/v1/translations/{id}/source
Content-Type: application/octet-stream
Content-Length: {bytes, maximum 25 MiB}
X-Parser-Version: document-ir/8
X-Source-SHA256: {original SHA-256}

{unchanged original bytes}

GET /api/v1/translations/{id}
// sourceBackup is available only after both saves
GET /api/v1/translations/{id}/manifest
GET /api/v1/translations/{id}/source

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é.

n8n, Make et Zapier

Utilisez une étape de requête HTTP avec un identifiant Bearer secret. Extrayez d’abord le texte, envoyez la charge utile JSON au point de terminaison de devis avec POST, puis envoyez l’ID du devis, la charge utile et une clé d’idempotence stable de 16 à 80 caractères au point de terminaison de traductions. Ajoutez un délai, puis vérifiez l’état avec GET jusqu’à ce que le traitement soit prêt ; récupérez le résultat et reconstruisez ou enregistrez le texte traduit. Enregistrez l’ID du devis et la clé de nouvelle tentative dans votre workflow. Aucun connecteur dédié ni téléversement multipartite n’est nécessaire.

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, les PDF à 300 pages et les fichiers PowerPoint à 300 diapositives. Il s’agit de limites appliquées aux fichiers source, vérifiées avant le début de la traduction.
• Jusqu’à 100 documents en attente ou en cours de traitement par compte. Les clés API partagent un quota de 120 devis par minute et de cinq nouveaux lancements ou nouvelles tentatives par tranche de dix secondes et par compte. Respectez l’en-tête Retry-After pour les réponses 429 et utilisez un délai exponentiel plafonné en cas d’échec temporaire ; augmenter la fréquence des vérifications n’accélère pas le traitement.
• Le mode strict rejette les segments traduits manquants, en double ou mal formés avant toute facturation. Le mode au mieux conserve les traductions validées et peut laisser le texte d’origine dans les sections non résolues ; outcome et issues décrivent le résultat. Aucun filigrane ni mention du service n’est ajouté au contenu des documents.

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.

Nous conservons une copie privée de votre document original jusqu’à 24 heures après la fin de la traduction pour vous permettre de récupérer vos téléchargements. Vous pouvez la supprimer plus tôt en supprimant la traduction. Seul le texte extrait est envoyé à notre fournisseur de traduction. Détails de confidentialité