Aller au contenu

Créer un travail de traduction

POST /api/v1/jobs
Idempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402f
Content-Type: application/json
ChampTypeObligatoirePar défautDescription
document_idchaîne de caractères✅—ID d’un document confirmé
target_langchaîne de caractères✅—Code de la langue cible
source_langchaîne de caractères—Détection automatiqueCode de la langue source
enginechaîne de caractères—xr-397bID de paramètre de traduction, voir paramètres de traduction
output_modechaîne de caractères—bilingualsingle ou bilingual
glossary_idchaîne de caractères——Un identifiant de glossaire pour ce compte. Les glossaires sont réservés aux comptes à jour de paiement (au moins un paiement réussi) ; un compte impayé qui envoie une requête reçoit 403
include_imagesbooléen—falseTraduisez également le texte figurant sur les images du document.
context_translationbooléen—falseActivez l’amélioration du contexte
style_presetchaîne de caractères——Préréglage de style

Une tâche créée est ajoutée à la file d’attente. Chaque compte traite jusqu’à 5 fichiers simultanément ; les tâches supplémentaires sont toujours créées et s’ajoutent automatiquement à la file, en commençant dès que les tâches précédentes sont terminées. Pendant qu’une tâche attend, son stage_message indique le nombre de tâches qui la précèdent.

Avant le démarrage d’un travail, le solde est vérifié par rapport à un seuil : un PDF nécessite un solde supérieur à « pages × 2 crédits » ; les autres formats se basent sur la longueur du texte source, soit au moins 2 crédits. Si le solde ne permet pas de démarrer un fichier, ce travail se termine avec status=failed et quota_exceeded=true, aucun frais n’est facturé, et les autres travaux ne sont pas affectés. Lorsqu’un travail est terminé, l’utilisation réelle est facturée ; si le coût dépasse le solde, celui-ci devient négatif, les crédits reçus ultérieurement remboursent d’abord cette dette, et de nouveaux travaux ne peuvent pas être lancés tant que le solde est négatif, il faut donc effectuer un rechargement. Voir crédits et utilisation .

Fenêtre de terminal
curl --fail-with-body -X POST https://omnidoc.top/api/v1/jobs \
-H "X-API-Key: $OMNIDOC_API_KEY" \
-H "Idempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402f" \
-H "Content-Type: application/json" \
-d '{"document_id":"4q8mx2q9z1k7p6ra","target_lang":"en"}'

Réponse 201 (le stage_message du serveur est en chinois) :

{
"id": "q3f8s6c2a9m1k4tx",
"document_id": "4q8mx2q9z1k7p6ra",
"source_lang": null,
"target_lang": "en",
"engine": "xr-397b",
"status": "pending",
"stage": "queued",
"stage_progress": 0,
"stage_message": "排队中",
"time_cost": 0,
"error_msg": null,
"quota_exceeded": false,
"queue_position": null,
"created_at": "2026-10-01T12:01:00Z",
"updated_at": "2026-10-01T12:01:00Z"
}
ÉtatCause
403La clé ne permet pas le paramètre sélectionné, ou un compte non payé a envoyé glossary_id
404Le document ou le glossaire n’existe pas, a été supprimé ou appartient à un autre compte
415Le format de fichier ne peut pas être traduit
422Le fichier est vide, ne contient aucun texte traduisible ou un paramètre est invalide.
429Trop de requêtes, ou la file d’attente est pleine ; veuillez réessayer après Retry-After

Idempotency-Key est facultatif mais recommandé pour chaque soumission. Une clé est composée de 1 à 128 caractères ASCII visibles et reste valable indéfiniment pour le même identifiant :

  • Même clé, même corps : renvoie le travail d’origine (y compris un travail ayant échoué) ; rien n’est créé ni facturé deux fois.
  • Même clé, corps différent : 409 (idempotency_request_conflict).
  • Le travail original a été supprimé : 410 (idempotency_job_gone).

Utilisez une nouvelle UUID pour chaque nouvelle soumission, et réutilisez la clé d’origine uniquement lors d’une tentative de reprise de cette même soumission.