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.
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.
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.
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.
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.
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"import osimport requests
response = requests.get( "https://omnidoc.top/api/v1/billing/credits/balance", headers={"X-API-Key": os.environ["OMNIDOC_API_KEY"]}, timeout=30,)response.raise_for_status()print(response.json())// Node.js 20+, save as balance.mjsconst apiKey = process.env.OMNIDOC_API_KEY;if (!apiKey) throw new Error('Set OMNIDOC_API_KEY');const response = await fetch('https://omnidoc.top/api/v1/billing/credits/balance', { headers: { 'X-API-Key': apiKey }, signal: AbortSignal.timeout(30_000),});if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);console.log(await response.json());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.
| Étape | Méthode et chemin | Ce qu’il faut conserver |
|---|---|---|
| Demander un téléchargement | POST /upload/presign | upload_url, upload_headers, finalize_token |
| Envoyez le fichier | PUT vers le upload_url renvoyé | Réponse de succès ; cette requête ne contient pas de clé API |
| Confirmez le téléchargement | POST /upload/finalize | document.id |
| Créez une traduction | POST /jobs | Job id |
| Vérifiez l’état | GET /jobs/{job_id} | completed ou failed |
| Listez les résultats | GET /artifacts?job_id={job_id} | ID et formats des artefacts |
| Télécharger un résultat | GET /artifacts/{artifact_id}/download | Octets 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 .
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.
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.| État | Vérifiez d’abord | Que faire |
|---|---|---|
401 / 403 | Clé, autorisations, propriété des ressources | Corrigez les informations d’identification ou les autorisations ; n’effectuez pas de nouvelles tentatives sans vérification. |
402 | Crédits disponibles | Rechargez, puis soumettez à nouveau |
409 | Clé et corps d’idempotence, état de la ressource | Interrogez l’opération initiale avant d’en démarrer une nouvelle. |
422 | Erreurs de champ dans la réponse | Corrigez les paramètres ou le fichier |
429 | Entreprise code et Retry-After | Les 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é. |
5xx | Erreur temporaire du service | Ré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 . .
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é.