Aller au contenu

Intégrez les flux de travail documentaires à votre application

Du téléchargement d’un fichier à sa traduction, en passant par la consultation de l’avancement et le téléchargement du résultat. Chaque étape est expliquée dans l’ordre d’intégration, avec des points d’accès pour la gestion des fichiers, le traitement des documents et les services audio et vidéo.

Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · Authentification par clé API · les traductions de fichiers s’exécutent sous forme de tâches asynchrones

Ce site décrit l’API cloud HTTP.

01 Commencez par une requête qui ne consomme aucun crédit

Section intitulée « 01 Commencez par une requête qui ne consomme aucun crédit »

Vérifiez que votre clé et votre réseau fonctionnent avant de téléverser des fichiers. Une vérification du solde ne consomme aucun crédit et ne génère aucun travail de traduction.

  1. Obtenez une clé API

    Connectez-vous à la console API et créez une clé commençant par sk_. Utilisez une clé distincte pour chaque application et définissez un budget pour celle-ci.

    Une clé sert au compte qui l’a créée. Conservez-la sur le serveur et lisez-la à partir d’une variable d’environnement ; ne la placez jamais dans le code source d’une page web ni dans un dépôt public.

  2. Vérifier le solde

    Définissez la variable d’environnement OMNIDOC_API_KEY, puis exécutez l’un des exemples ci-dessous. La valeur JSON indique un succès ; 401 signifie que la clé présente un problème et doit être vérifiée. Ne divulguez jamais la clé complète dans les tickets, captures d’écran ou journaux.

    Fenêtre de terminal
    export OMNIDOC_API_KEY="sk_your_key"
    curl --fail-with-body --silent --show-error \
    'https://omnidoc.top/api/v1/billing/credits/balance' \
    -H "X-API-Key: $OMNIDOC_API_KEY"

Un téléchargement réussi signifie uniquement que le fichier est stocké. Après avoir créé une tâche, attendez qu’elle atteigne un état final, puis listez et téléchargez ses résultats.

ÉtapeMéthode et cheminCe qu’il faut conserver
Demander un téléchargementPOST /upload/presignupload_url, upload_headers, finalize_token
Envoyez le fichierPUT vers le upload_url renvoyéRéponse de succès ; cette requête ne contient pas de clé API
Confirmez le téléchargementPOST /upload/finalizedocument.id
Créez une traductionPOST /jobsJob id
Vérifiez l’étatGET /jobs/{job_id}completed ou failed
Listez les résultatsGET /artifacts?job_id={job_id}ID et formats des artefacts
Télécharger un résultatGET /artifacts/{artifact_id}/downloadOctets du fichier et nom du fichier de réponse

Pour le téléchargement direct, envoyez le upload_headers depuis le serveur exactement tel qu’il est renvoyé, et n’envoyez jamais de X-API-Key à l’adresse de stockage. Si l’adresse de téléchargement expire ou si le transfert échoue, demandez-en une nouvelle. Détails : protocole de téléchargement , démarrage rapide , flux de travail complet des Node.js et champs de la demande de traduction .

Chaque entrée répertorie les chemins, les champs de requête et des exemples. L’état du service de votre compte ainsi que les limites de votre clé s’appliquent à tous.

Une clé API identifie un compte. Il ne s’agit pas d’un mot de passe public pour télécharger un fichier.

En-tête de requête

Utilisez X-API-Key: sk_… ou Authorization: Bearer sk_…, l’un des deux par demande. Envoyez Content-Type: application/json avec les corps JSON.

Ce qu'une clé peut atteindre

Une clé ne donne accès qu’aux ressources que son compte est autorisé à utiliser ; le statut du service, le budget de la clé et les paramètres de traduction autorisés restent applicables. Les modifications du compte ainsi que la création, la rotation ou la révocation des clés s’effectuent dans la console.

Voir l’authentification, les budgets et la rotation et les services et les autorisations .

05 Intégrer la gestion des échecs de construction dans l’intégration

Section intitulée « 05 Intégrer la gestion des échecs de construction dans l’intégration »

Un délai d’attente n’indique pas que la tâche n’a pas été créée. Différenciez les erreurs réessayables des requêtes nécessitant une correction, afin qu’aucune donnée ne soit soumise ou traitée deux fois.

  • Création idempotente : génère un Idempotency-Key pour chaque nouvelle opération de création ; lorsque vous réessayez la même opération, réutilisez la clé d’origine et le corps de requête exactement identique. Les opérations de document, les tâches multimédias et la création vocale nécessitent la clé ; pour les autres points de terminaison de création, consultez leurs pages de référence.
  • Notifications asynchrones : le polling convient pour une première intégration ; pour suivre les progrès en continu, utilisez SSE , et pour recevoir les états finaux en arrière-plan, utilisez un webhook webhook .
ÉtatVérifiez d’abordQue faire
401 / 403Clé, autorisations, propriété des ressourcesCorrigez les informations d’identification ou les autorisations ; n’effectuez pas de nouvelles tentatives sans vérification.
402Crédits disponiblesRechargez, puis soumettez à nouveau
409Clé et corps d’idempotence, état de la ressourceInterrogez l’opération initiale avant d’en démarrer une nouvelle.
422Erreurs de champ dans la réponseCorrigez les paramètres ou le fichier
429Entreprise code et Retry-AfterLes limites de débit et de file d’attente peuvent être respectées en attendant ; un budget de clés épuisé doit d’abord être augmenté.
5xxErreur temporaire du serviceRéessai exponentiel limité ; conservez la clé d’idempotence pour les requêtes de création

Conservez l’en-tête de réponse X-Request-Id, l’heure de la requête et le chemin pour le dépannage ; ne journalisez jamais la clé complète. Tous les codes d’erreur et les exemples de retry se trouvent dans la référence d’erreur . .

06 Vérifiez le fonctionnement de la facturation avant d’intégrer

Section intitulée « 06 Vérifiez le fonctionnement de la facturation avant d’intégrer »

Aucun crédit

Le téléchargement, la vérification des travaux, le téléchargement des résultats ainsi que la consultation du solde et des relevés de règlement ne consomment aucun crédit ; il en va de même pour les glossaires, les projets, les tags, la recherche et le partage.

Facturé à l'usage

La traduction de fichiers, les outils documentaires, la traduction instantanée ainsi que les services audio et vidéo sont facturés au prorata de leur utilisation réelle ; la création d’un projet ne constitue pas la facturation finale.

Avant le démarrage d’une tâche, seul le seuil de solde est vérifié ; après son achèvement, la consommation réelle est facturée. Si le solde est insuffisant, la différence est enregistrée comme une dette, et les crédits reçus ultérieurement sont utilisés en priorité pour la régler. Vous pouvez effectuer le rapprochement des frais et des remboursements par tâche ou par opération de crédit. Lorsque le budget d’une clé est épuisé, vous pouvez toutefois consulter les tâches, les résultats et les enregistrements associés à cette clé.