# 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/projects/{projectId}/translate`), sont accessibles sous `https://api.gtx.dev`. ### Authentification Authentifiez-vous avec une clé API dans l’en-tête standard `Authorization`. ```bash curl https://api.gtx.dev/v2/projects/PROJECT_ID \ -H "Authorization: Bearer gtx-api-..." \ -H "gt-api-version: 2026-10-08.v1" ``` Choisissez la portée de clé qui correspond à votre workflow : * **Projet** avec le préfixe `gtx-api-` : liée à un seul projet et utilisable dans n’importe quel environnement, selon ses permissions * **Organisation** avec le préfixe `gtx-org-` : fonctionne sur tous les projets de l’Organisation à laquelle elle est liée, selon ses permissions Le chemin détermine la cible d’une requête : `/v2/projects/{projectId}/...` cible le projet, `/v2/orgs/{orgId}/...` l’Organisation, et `/v2/context-groups/{groupId}/...` l’Organisation à laquelle appartient le groupe. Les endpoints de découverte (`GET /v2/orgs` et `GET /v2/projects`) ne nécessitent aucun identifiant. La clé doit avoir accès au projet ou à l’Organisation sélectionné ; une clé de projet ne fonctionne donc que sur son propre projet. N’incluez jamais de clés API dans les bundles déployés pour le navigateur ou les applications mobiles. (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). ### Permissions La plupart des endpoints nécessitent une permission sur l’identité de la requête. [List Organizations](/docs/platform/openapi/reference/organizations/list-orgs), [List Projects](/docs/platform/openapi/reference/projects/list-projects) et [Get a Project](/docs/platform/openapi/reference/projects/get-project) ne nécessitent aucune permission sur une ressource, au-delà de l’accès à l’organisation ou au projet renvoyé. Les clés d’organisation comme les clés de projet prennent en charge les permissions **All** ou **Custom** dans le dashboard, dans la limite des permissions que le créateur peut accorder. L’[endpoint de clé API de projet](/docs/platform/openapi/reference/projects/create-project-api-key) vous permet de sélectionner des permissions, ou d’omettre la sélection pour accorder toutes les permissions de projet que vous pouvez déléguer. Les permissions Write n’incluent pas Read. Les clés de projet ne peuvent pas détenir de permissions d’organisation (`org:*`) ni `project:api_keys:write` ; les endpoints qui les exigent nécessitent donc une clé d’organisation. 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`. * `org:assets:write` pour téléverser des polices avec `POST /v2/orgs/{orgId}/assets`. * `project:files:read` pour télécharger des fichiers ; consulter les métadonnées et l’état des fichiers ; lister les branches et leurs fichiers ; et consulter les tâches. * `project:files:write` pour téléverser des fichiers sources et des traductions ; écraser des traductions ; publier ; créer et mettre à jour des branches ; définir des tags ; et déplacer des fichiers. * `project:translations:enqueue` pour traduire des fichiers avec `POST /v2/projects/{projectId}/files/translate`. * `project:translations:generate` pour la traduction à l’exécution. * `project:context:write` pour générer le contexte. * `org:context:read` pour consulter les Context Groups, leur glossaire et leurs Custom Prompts, leurs attributions aux projets et leurs exports. * `org:context:write` pour créer, modifier et supprimer des Context Groups et leur contenu, importer du contenu, ainsi qu’attribuer des groupes aux projets, les en retirer et en modifier l’ordre. * `project:write` pour mettre à jour les paramètres du projet. ### Gestion des versions Envoyez l'en-tête `gt-api-version` dans chaque requête pour sélectionner le contrat d'API. ```bash -H "gt-api-version: 2026-10-08.v1" ``` * Les endpoints dont la page de référence indique que l'en-tête est obligatoire renvoient une erreur `400` si celui-ci est absent ou spécifie une version plus ancienne. * Les autres endpoints utilisent la plus ancienne version prise en charge lorsque l'en-tête est absent, et renvoient leurs erreurs en texte brut plutôt qu'en JSON. Pour consulter les endpoints d'une version plus ancienne, sélectionnez-la dans le menu de version de l'API, en haut de n'importe quelle page OpenAPI. ### Requêtes par lots Les endpoints par lots ci-dessous renvoient un résultat par élément, dans l'ordre de la requête. * **Écritures** (téléversement de fichiers sources et de traductions, déplacement, publication et écrasement de fichiers, et téléversement de ressources de polices) : renvoient `200` avec `summary` (nombres `total`, `succeeded` et `failed`) et `results`, même lorsque tous les éléments échouent. Un élément en échec a `status: "failed"` et une `error` ; les autres éléments sont tout de même appliqués. Une requête dont la validation échoue renvoie `400` et n'applique rien. * **Lectures** (requêtes de fichiers, de contenu de fichiers et de tâches) : renvoient `200` avec `results`. Un élément absent du projet est `not_found`. Une traduction de fichier stockée mais pas encore terminée, par exemple pendant une passe de mise en page, est `pending` ; renvoyez la requête plus tard. Une traduction est `not_found` tant que sa tâche de traduction ne l'a pas encore stockée : attendez donc la fin de la tâche avec `GET /v2/projects/{projectId}/jobs/{jobId}` ou `POST /v2/projects/{projectId}/jobs/query` avant de la lire. Sans `versionId`, une lecture renvoie la version terminée la plus récente sur la branche, et n'est `pending` que tant qu'aucune version n'est terminée. Les requêtes de tâches renvoient l'état de chaque tâche. Les autres endpoints par lots ont leur propre format de réponse : la mise en file d'attente d'une traduction de fichiers renvoie `202` avec les `jobs` créées, tandis que les upserts de glossaire et de prompts personnalisés de Context Management appliquent le lot entier ou rien du tout, et renvoient `committed` avec les `counts` par élément. ### Limites des métadonnées d'exécution Pour `POST /v2/projects/{projectId}/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 de caractères. 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 caractères 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 La limitation de débit s’applique sur des fenêtres de 60 secondes, à deux niveaux : * **Avant l’authentification :** chaque identifiant présenté peut effectuer 600 tentatives par minute, y compris les requêtes dont l’authentification échoue. Les requêtes sans identifiant ne sont pas concernées par ce niveau. En cas de dépassement, l’API renvoie `429` avec `Retry-After: 60`, sans en-têtes `RateLimit-*`. * **Après l’authentification :** chaque groupe de routes limite les requêtes par appelant authentifié, par exemple une clé API. Pour les routes limitées sans appelant authentifié, c’est l’adresse IP cliente qui est utilisée. Les limites après authentification varient selon l’endpoint : * **Élevé :** 30 requêtes/minute pour la traduction de fichiers. * **Moyen :** 120 requêtes/minute pour le téléversement de fichiers sources, de traductions et de polices ; l’écrasement de traductions ; la génération de contexte ; le déplacement de fichiers ; le listage des fichiers d’une branche ; et la publication. * **Faible :** 300 requêtes/minute pour les téléchargements de fichiers. * **Par défaut :** 200 requêtes/minute pour la découverte de projets et d’organisations, la création de projet et de clé API de projet, les paramètres du projet, les branches, les tags, les tâches, les métadonnées et l’état des fichiers, la traduction à l’exécution et Context Management. Le listage des projets, la création de projets et la création de clés API de projet partagent une même limite. En cas de dépassement d’une limite après authentification, l’API renvoie `429` avec des en-têtes `RateLimit-*`. ### Pagination Les endpoints de liste renvoient une seule page de résultats au format `{ "items": [...], "nextCursor": ... }`. Passez `limit` (de 1 à 100, valeur par défaut : 50) pour définir la taille de la page. Lorsque `nextCursor` est une chaîne de caractères, transmettez-la dans `cursor` pour récupérer la page suivante ; lorsqu'il vaut `null`, il n'y a plus de résultats. Un curseur n'est valable que pour la liste et les filtres qui l'ont généré. Les pages étant lues indépendamment les unes des autres, les éléments modifiés entre deux requêtes peuvent être omis ou apparaître en double. ### Erreurs Lorsque `gt-api-version` est défini, les erreurs renvoient un corps JSON contenant un message `error`. Cela s’applique à toutes les erreurs, y compris en cas de JSON mal formé (`400`), de corps de requête trop volumineux (`413`) et de dépassement de la limite de débit (`429`). ```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 identifiant bearer manquant ou invalide. * `402` lorsque le compte de facturation de l’organisation est bloqué, ou que ses limites d’utilisation ou son solde de crédits ne couvrent pas la requête (traduction de fichiers et traduction à l’exécution). * `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. * `409` en cas de conflit, par exemple lorsqu’une création de projet dépasserait la limite de projets de l’organisation, qu’un nom de branche est déjà utilisé ou qu’un renommage est en conflit avec un terme de glossaire ou un Custom Prompt existant. * `413` lorsque le corps de la requête dépasse la limite de l’endpoint, ou lorsqu’une réponse de Context Management dépasserait 1 Mio (demandez une valeur `limit` plus petite). * `415` lorsque l’en-tête `Content-Type` du corps de la requête est absent ou différent de `application/json`. * `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. Pour les réponses `429` et `503`, réessayez après un certain délai. Pour `429`, attendez le nombre de secondes indiqué dans l’en-tête `Retry-After`. ## Spécification OpenAPI [#openapi-spec] Une spécification OpenAPI 3.1 lisible par machine de la dernière version est disponible à l’adresse [`/openapi.json`](/openapi.json), et celle de chaque version antérieure à l’adresse `/openapi/.json`. Importez-la dans Postman, Insomnia ou un client OpenAPI pour générer des requêtes et des types. Pour des utilitaires d’endpoint typés, utilisez le [client `@generaltranslation/api`](/docs/platform/core/reference/api-client). ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.