Créer un travail de traduction
POST /api/v1/jobsIdempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402fContent-Type: application/json| Champ | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
document_id | chaîne de caractères | ✅ | — | ID d’un document confirmé |
target_lang | chaîne de caractères | ✅ | — | Code de la langue cible |
source_lang | chaîne de caractères | — | Détection automatique | Code de la langue source |
engine | chaîne de caractères | — | xr-397b | ID de paramètre de traduction, voir paramètres de traduction |
output_mode | chaîne de caractères | — | bilingual | single ou bilingual |
glossary_id | chaî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_images | booléen | — | false | Traduisez également le texte figurant sur les images du document. |
context_translation | booléen | — | false | Activez l’amélioration du contexte |
style_preset | chaî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 .
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"}| État | Cause |
|---|---|
403 | La clé ne permet pas le paramètre sélectionné, ou un compte non payé a envoyé glossary_id |
404 | Le document ou le glossaire n’existe pas, a été supprimé ou appartient à un autre compte |
415 | Le format de fichier ne peut pas être traduit |
422 | Le fichier est vide, ne contient aucun texte traduisible ou un paramètre est invalide. |
429 | Trop de requêtes, ou la file d’attente est pleine ; veuillez réessayer après Retry-After |
Idempotence
Section intitulée « Idempotence »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.