# General Translation Platform: Vue d’ensemble URL: https://generaltranslation.com/fr/docs/platform/openapi/overview.mdx Docs index: https://generaltranslation.com/llms.txt Description: Appelez les endpoints publics de l’API General Translation et téléchargez la spécification OpenAPI. Utilisez l’API General Translation pour créer des workflows d’automatisation personnalisés. La CLI gère la plupart des appels à l’API pour vous. Utilisez le [client TypeScript `generaltranslation/api`](/docs/platform/core/reference/api-client) pour disposer des types de requête et de réponse générés, ou appelez directement les endpoints lorsque vous avez besoin d’une automatisation personnalisée. La spécification OpenAPI définit ces endpoints dans un format lisible par machine. ## Notions de base de l’API [#api-basics] ### URL de base Tous les endpoints, y compris celui de la traduction à l’exécution (`POST /v2/translate`), sont accessibles sous `https://api.gtx.dev`. ### Authentification Chaque endpoint nécessite un credential Bearer dans l’en-tête standard `Authorization`. La référence des endpoints indique si une opération accepte une clé API, un jeton d’accès personnel utilisateur OAuth 2.1, ou les deux. ```bash curl https://api.gtx.dev/v2/project/info/PROJECT_ID \ -H "Authorization: Bearer gtx-api-..." ``` Utilisez le bon type de clé : * **Projet (développement)** avec le préfixe `gtx-dev-` : pour un usage local et en prévisualisation, rejetée par les endpoints réservés à la production * **Projet (production)** avec le préfixe `gtx-api-` : liée à un seul projet * **Organisation** avec le préfixe `gtx-org-` : fonctionne sur tous les projets. La plupart des endpoints au niveau du projet nécessitent `gt-project-id`. `GET /v2/project/info/{projectId}` requiert toujours cet en-tête et vérifie que les deux identifiants correspondent. `POST /v2/projects/{projectId}/api-keys` utilise à la place son paramètre de chemin. Les endpoints au niveau de l’Organisation tels que `POST /v2/orgs/{orgId}/projects` utilisent l’Organisation présente dans le chemin et exigent que la clé y ait accès. (Consultez [les clés API](/docs/platform/dashboard/reference/api-keys) pour savoir comment créer des clés API et définir leur portée). Les applications OAuth utilisent le parcours Authorization Code avec Proof Key for Code Exchange (PKCE). Découvrez le serveur d’autorisation à l’adresse `https://dash.generaltranslation.com/.well-known/oauth-authorization-server/api/auth`, demandez uniquement les niveaux dont votre application a besoin, puis envoyez le jeton d’accès utilisateur obtenu dans le même en-tête Bearer. Le jeton est limité à la fois par les niveaux qui lui sont accordés et par l’accès dont dispose actuellement l’utilisateur à l’Organisation ou au projet cible. ### Permissions Chaque endpoint nécessite une permission sur l’identité de la requête. Les clés d’organisation configurent les permissions explicitement. Les clés de projet créées dans le dashboard utilisent les valeurs par défaut de leur type de clé ; les clés créées via l’API d’organisation peuvent disposer de moins de permissions, car elles sont limitées à celles que l’identité de la requête peut déléguer. Les jetons d’accès personnel utilisateur OAuth doivent inclure le niveau correspondant, et l’utilisateur connecté doit également détenir cette permission. Permissions courantes : * `org:projects:create` pour créer des projets avec `POST /v2/orgs/{orgId}/projects`. * `project:api_keys:write` pour créer des clés API de projet avec `POST /v2/projects/{projectId}/api-keys`. * `project:files:read` pour télécharger des fichiers, consulter les informations sur les fichiers, l’état des traductions, les informations sur les branches, les fichiers orphelins, les informations du projet et celles des jobs. * `project:files:write` pour téléverser des fichiers, des traductions et des assets ; soumettre des diffs ; publier ; créer des branches et des tags ; et déplacer des fichiers. * `project:translations:enqueue` pour mettre des fichiers en file d’attente pour traduction. * `project:translations:generate` pour la traduction à l’exécution. * `project:context:write` pour générer le contexte. * `project:write` pour mettre à jour les paramètres du projet. ### Versionnage Envoyez l’en-tête facultatif `gt-api-version` pour fixer le format de la réponse. ```bash -H "gt-api-version: 2026-03-06.v1" ``` Si vous omettez l’en-tête, c’est la version prise en charge la plus ancienne qui est utilisée. La version la plus récente est `2026-03-06.v1`. ### Limites des métadonnées d'exécution Pour `POST /v2/translate`, un entier positif `maxChars` ajoute une instruction de longueur aux invites de traduction prises en charge ; il ne constitue pas une limite garantie sur la longueur de la sortie. Les nombres négatifs, nuls ou fractionnaires sont ignorés. Les valeurs d'un type incorrect font échouer la validation de la requête. Chaque fichier `sourceCode` conserve au maximum cinq entrées de contexte. L'API tronque les champs `before` et `after` de chaque entrée à 2 000 caractères, et son champ `target` à 500 caractères. Définissez `fileFormat` sur `MD` ou `MDX` pour traduire un document entier fourni sous forme de chaîne. Les requêtes de document doivent utiliser `dataFormat: STRING` et ne peuvent pas inclure `maxChars` ni `sourceCode`. L'API découpe le document en fragments, ajoute le contexte de la requête à chaque fragment et renvoie une seule chaîne de document validée. Un fragment en échec ou un document final invalide fait échouer cette entrée plutôt que de renvoyer une sortie partielle. ### Limites de débit Les requêtes sont soumises à des limites de débit par clé API ou adresse IP cliente sur une fenêtre de 60 secondes. Les limites varient selon l’endpoint : * **Élevé :** 30 requêtes/minute pour la mise en file d’attente de traductions. * **Moyen :** 120 requêtes/minute pour les téléversements, les diffs, le contexte, les déplacements, les fichiers orphelins et la publication. * **Faible :** 300 requêtes/minute pour les téléchargements de fichiers. * **Par défaut :** 200 requêtes/minute pour la création de projet et de clé API de projet, les branches, les tags, les informations sur le projet, les informations sur le job, les informations sur le fichier, l’état des traductions et la traduction à l’exécution. En cas de dépassement, l’API renvoie `429`. Les quotas de jetons d’organisation renvoient `402` depuis `POST /v2/translate`. ### Erreurs Les erreurs d’application authentifiées renvoient un message `error`. Pour la version d’API `2026-02-18.v1` et les versions ultérieures, le corps de la réponse est au format JSON ; pour les versions antérieures, y compris celle utilisée par défaut lorsqu’aucun en-tête `gt-api-version` n’est envoyé, le message est renvoyé en texte brut. Les échecs d’analyse, de dépassement de la limite de payload et de dépassement de la limite de débit peuvent renvoyer du texte brut avant l’authentification. ```json { "error": "API key is missing required permission: project:files:write" } ``` Codes d’état courants : * `400` pour un corps de requête, un paramètre de requête ou une version invalide. * `401` pour un credential bearer manquant ou invalide. * `402` lorsque le quota de jetons de l’organisation est dépassé (`POST /v2/translate`). * `403` lorsque l’identité de la requête ne dispose pas de la permission requise ou que l’action n’est pas autorisée avec le forfait actuel. * `404` lorsque la ressource est introuvable. * `413` lorsque le corps de la requête dépasse la limite de l’endpoint. * `425` lorsqu’un fichier traduit demandé est toujours en cours de traitement. * `429` lorsqu’une limite de débit est dépassée. * `500` pour une erreur interne du serveur. * `503` lorsque le service est temporairement indisponible. ## Spécification OpenAPI [#openapi-spec] Une spécification OpenAPI 3.1 lisible par machine est disponible à l’adresse [`/openapi.json`](/openapi.json). Importez-la dans Postman, Insomnia ou un client OpenAPI pour générer des requêtes et des types. Les outils JavaScript embarquent également l’instantané OpenAPI ayant servi à générer la version du SDK installée. Cet instantané embarqué peut différer du contrat hébergé actuel : * Exécutez [`npx gt api --spec`](/docs/cli/reference/commands/api) avec `gt` 2.20.0 ou une version ultérieure. * Importez `generaltranslation/api/openapi.json` depuis `generaltranslation` 9.2.0 ou une version ultérieure. * Importez `@generaltranslation/api/spec/openapi.json` depuis le SDK généré standalone. Pour des utilitaires d’endpoint typés, utilisez le [client `generaltranslation/api`](/docs/platform/core/reference/api-client). ## Sections de référence - /docs/platform/core/reference/api-client - /docs/platform/openapi/reference/files/upload-source - /docs/platform/openapi/reference/context/generate-context - /docs/platform/openapi/reference/translation/translate-runtime - /docs/platform/openapi/reference/project/create-project ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.