Guide d'accès à l'API de traduction de documents : utilisez Python pour traduire par lots Word et PDF, et utilisez Webhook pour recevoir les résultats

L'API de traduction de documents peut enchaîner le téléchargement, la création de tâches, la réception de rappels et le téléchargement de traductions dans un processus automatisé. Vous pouvez réaliser une traduction complète en seulement quatre étapes.

Si votre système traite quotidiennement des contrats, des instructions, des documents ou des rapports, le téléchargement, l'attente et le téléchargement manuels deviendront rapidement un goulot d'étranglement. Ce n'est qu'en confiant ces étapes au programme que le traitement par lots peut être stable.

L'API de traduction de documents d'OmniDoc (Zhiyi) enchaîne l'ensemble du processus : Télécharger des fichiers, créer des tâches, recevoir des notifications d'achèvement et télécharger des traductions. La traduction conserve la mise en page, les tableaux, les images et les formules du document original et peut produire des comparaisons bilingues ou uniquement la traduction.

Cet article convient aux développeurs qui doivent intégrer la traduction de documents dans leurs propres systèmes. Après avoir lu, vous serez en mesure de maîtriser le processus d'appel complet, les paramètres communs, les méthodes de nouvelle tentative idempotentes, les rappels Webhook et les règles de facturation, et d'être capable d'exécuter une tâche complète à l'aide de Python.

Comment accéder à l'API de traduction de documents ? Conclusion en une phrase

Vous pouvez intégrer la traduction de documents dans votre propre système en utilisant l'API pour télécharger, créer des tâches, recevoir des rappels et télécharger automatiquement des traductions au cours d'un processus en quatre étapes.

Tableau 0 Scénarios d'accès et pratiques recommandées

votre situation	Pratiques recommandées	raison
Besoin de traiter par lots des contrats, des spécifications, des documents ou des rapports	Utilisez l'API pour télécharger, créer des tâches et télécharger automatiquement des traductions selon le processus en quatre étapes	Éliminez le téléchargement, l'attente et le téléchargement manuels
Besoin d'une comparaison bilingue	output_mode est défini sur bilingue (par défaut)	À l'exception de PPTX, tous les autres formats prennent en charge la sortie bilingue
J'espère que la tâche sera traitée immédiatement après son achèvement	Configurez Webhook et remplissez la vérification de la signature secrète	Le système informera de manière proactive votre serveur lorsque la tâche sera terminée.
Le réseau est instable et je crains les soumissions répétées.	Apportez la clé d'idempotence lors de la création d'une tâche et vérifiez d'abord l'état lorsqu'elle expire.	Si vous disposez de la même clé et de la même demande, la tâche originale sera restituée et aucune déduction répétée ne sera effectuée.

Lisez les informations de base avant d'accéder

Les conventions de base de l'API sont les suivantes. Confirmez ce contenu avant de commencer à écrire du code.

Tableau 1 Conventions de base de l'API

projet	illustrer
URL de base	https://omnidoc.top/api/v1
Attestation	La clé API est placée dans l'en-tête de la requête X-API-Key et peut également être envoyée en tant qu'informations d'identification du porteur ; créé dans la console API
Format de demande	JSON, Type de contenu : application/json
Suivi des demandes	Enregistrez le X-Request-Id de chaque réponse et fournissez-le lorsque vous contactez le support.
Limitation de courant	Appuyez sur Réessayer-Après pour réessayer lorsque 429 est renvoyé

Quels fichiers sont pris en charge ?

Prend en charge Word (.docx), Excel (.xlsx), PowerPoint (.pptx), PDF, HTML, EPUB, Markdown avec texte, sous-titres SRT/ASS, images CSV, PNG/JPG et documents UniDoc (.udoc).

À l'exception du PPTX, tous les autres formats prennent en charge la sortie bilingue. Lorsque PPTX demande le bilinguisme, seule la traduction est renvoyée. Pour les méthodes de comparaison spécifiques, voir la comparaison principale ci-dessous.

Réaliser une traduction en quatre étapes

Demander le téléchargement : appelez POST /upload/presign, soumettez le nom et la taille du fichier et obtenez l'adresse de transfert direct, l'en-tête de téléchargement et finalize_token.
Télécharger et confirmer : utilisez l'en-tête de téléchargement renvoyé pour METTRE le fichier et n'apportez pas la clé API lors du téléchargement. Appelez ensuite POST /upload/finalize en échange de document.id.
Créer une tâche : appelez POST /jobs, soumettez document_id et target_lang, et il est recommandé d'apporter Idempotency-Key en même temps.
Récupérer les résultats : interrogez GET /jobs/{id}, ou abonnez-vous à la progression SSE ou configurez Webhook. Une fois la tâche terminée, utilisez GET /artifacts?job_id=... pour obtenir le produit et le télécharger.

Paramètres communs pour la création de tâches

Lors de la création d'une tâche, les deux champs les plus couramment utilisés sont document_id et target_lang. D'autres champs sont définis selon les besoins.

Tableau 2 Champs de requête POST /jobs

Champ	défaut	illustrer
document_id	—	ID du document confirmé (obligatoire)
target_lang	—	Code de la langue cible (obligatoire)
source_lang	Détection automatique	code de la langue source
engine	xr-397b	Configuration de traduction : xr-397b, deepseek, qwen, chatgpt, gemini, claude
output_mode	bilingual	comparaison bilingue bilingue, traduction unique
glossary_id	—	ID de glossaire, nom de marque unifié et mots professionnels
include_images	false	S'il faut traiter le texte de l'image dans le document
context_translation	false	Contexte amélioré, terminologie plus cohérente
style_preset	—	Style par défaut

Exemple Python : créez une tâche et attendez qu'elle soit terminée

L'extrait ci-dessous dépend uniquement des demandes. Pour le processus complet de téléchargement et de téléchargement, veuillez vous référer à la page Python de la documentation du développeur.

import time, uuid, requests

BASE = "https://omnidoc.top/api/v1"
HEADERS = {"X-API-Key": "sk_your_key"}

def create_job(document_id, target_lang="en", engine="xr-397b"):
    r = requests.post(f"{BASE}/jobs",
        headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
        json={"document_id": document_id, "target_lang": target_lang, "engine": engine},
        timeout=30)
    r.raise_for_status()
    return r.json()

def wait_for_job(job_id):
    while True:
        job = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=20).json()
        if job["status"] in ("completed", "failed"):
            return job
        time.sleep(5)

Traitement par lots et nouvelles tentatives : concurrence, file d'attente et idempotence

File d'attente automatique

Chaque compte peut traiter 5 fichiers simultanément. Les tâches qui dépassent la limite supérieure sont créées et mises en file d'attente comme d'habitude, et stage_message indiquera le nombre de tâches à venir.

Clés idempotentes

Si la clé d'idempotence est la même et que le corps de la demande est le même, la tâche d'origine sera renvoyée et ne sera pas créée ou facturée à plusieurs reprises. Lorsque vous rencontrez un délai d'attente réseau, vérifiez d'abord l'état de la tâche et ne la soumettez pas à nouveau avec une nouvelle clé.

Code d'erreur

403 : La configuration sélectionnée n'est pas autorisée pour la clé.
404 : La documentation ou le glossaire n'existe pas.
415 : Le format n'est pas pris en charge.
422 : Le fichier est vide ou les paramètres ne sont pas valides.

Webhook : avertissez votre serveur lorsque la tâche est terminée

Chaque utilisateur peut configurer 3 webhooks. Créez avec POST /webhooks, mettez à jour ou désactivez avec PATCH.

Lorsqu'une tâche de traduction de fichier se termine (indépendamment du succès ou de l'échec), le système envoie l'événement job.completed :

data.status est terminé ou a échoué.
data.char_count est le nombre de caractères de traduction.

Remplissez le secret lors de la création d'un Webhook, et chaque rappel ultérieur apportera la signature X-Webhook. Utilisez HMAC-SHA256 pour signer la demande originale afin de confirmer la source de rappel.

L'URL de rappel doit être accessible depuis le réseau public et HTTPS est recommandé.

Comment calculer les frais ?

Vérification du solde avant de commencer

PDF : Le solde doit être supérieur à « nombre de pages × 2 points ».
Autres formats : facturés en fonction du nombre de mots originaux, au moins 2 points.
Lorsque le solde est insuffisant, la tâche se terminera par quota_exceeded et aucun frais ne sera déduit.

Déduction basée sur l'utilisation réelle

Une fois la tâche terminée, les frais seront déduits en fonction de l'utilisation réelle. Si la tâche échoue ou est annulée, aucun frais ne sera déduit.

Requête gratuite

Aucun point ne sera déduit pour la vérification du solde, du statut de la tâche, de l'utilisation, des bons et des adresses de téléchargement.

Forfait de points

Les forfaits de points commencent à 9,9 ¥ pour 3 000 points et les points achetés sont valables longtemps. Les forfaits en vente peuvent être interrogés via GET /billing/credits/plans.

Étape suivante

Des exemples complets de cURL, Python, Node.js peuvent être consultés dans la documentation du développeur : https://docs.omnidoc.top/guide/quickstart/.

Si vous ne souhaitez pas écrire de code pour le moment, vous pouvez également vous connecter à l’assistant IA d’OmniDoc pour traduire directement les fichiers natifs. Pour plus de détails, voir « Laisser l'IA exploiter directement Word, Excel et PPT » : https://omnidoc.top/blog/ai-word-excel-ppt-omnidoc/.

📊 Comparaison de base

Différents formats de fichiers ont différentes méthodes de sortie bilingue. Vous pouvez planifier à l'avance en fonction de votre propre type de fichier.

Type de fichier	Méthode de comparaison bilingue	S'il faut prendre en charge le bilinguisme
Word	Comparer par paragraphe	Oui
Excel	Comparer par colonne	Oui
PDF	Comparer par page	Oui
Sous-titres (SRT/ASS)	Comparer par ligne	Oui
PPTX	Retour à la traduction uniquement	Non

🎯 Quelle méthode vous convient ?

Si vous devez traiter par lots des contrats, des spécifications ou des documents

Utilisez l'API pour vous connecter au système et télécharger, créer des tâches et télécharger automatiquement des traductions selon le processus en quatre étapes, éliminant ainsi les opérations manuelles.

Si votre réseau est souvent instable

Apportez la clé d'idempotence lors de la création de la tâche. Interrogez d'abord le statut après l'expiration du délai pour éviter des créations ou des déductions répétées.

Si vous souhaitez traiter la tâche immédiatement après sa fin

Configurez Webhook et remplissez le secret pour la vérification de la signature. Le système informera de manière proactive votre serveur lorsque la tâche sera terminée.

Si vous avez des exigences unifiées en matière de vocabulaire professionnel

Créez d'abord un glossaire, puis transmettez glossary_id lors de la création d'une tâche pour unifier la traduction des noms de marque et des mots professionnels.

❓ Questions fréquemment posées (FAQ)

1. Y aura-t-il des déductions répétées pour la soumission répétée de la même tâche ?

Si la clé d'idempotence est la même et le corps de la demande est le même, la tâche d'origine sera renvoyée sans création ou déduction répétée.

2. Si la tâche échoue ou est annulée, des points seront-ils déduits ?

Aucun frais ne sera facturé. Lorsqu'une tâche échoue ou est annulée, aucune déduction ne sera effectuée.

3. Que se passe-t-il lorsqu'il n'y a pas suffisamment de points ?

La tâche se terminera par quota_exceeded et aucun frais ne sera déduit. Le seuil de solde avant de commencer est le suivant : le PDF nécessite un solde supérieur au "nombre de pages × 2 points", et les autres formats nécessitent un solde d'au moins 2 points en fonction du nombre de mots.

4. Dois-je apporter une clé API lors du téléchargement de fichiers ?

inutile. Lorsque vous utilisez le fichier PUT d’en-tête de téléchargement, n’apportez pas la clé API.

5. Que dois-je faire si je rencontre la limite de trafic 429 ?

Réessayez en fonction du délai Retry-After indiqué dans la réponse.

📝Résumé

En enchaînant les téléchargements, la création de tâches, les rappels et les téléchargements dans un processus automatisé, la traduction de documents peut être intégrée aux activités quotidiennes. Commencez par exécuter une tâche avec un exemple Python, puis ajoutez un glossaire, une sortie bilingue et des webhooks si nécessaire.

Essayez-le maintenant : téléchargez le document pour lancer la traduction, en conservant la mise en page d'origine.