# 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 Authentifiez-vous avec une clé API dans l’en-tête standard `Authorization`. ```bash curl https://api.gtx.dev/v2/project/info/PROJECT_ID \ -H "Authorization: Bearer gtx-api-..." ``` 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 Pour les endpoints au niveau du projet dont le chemin contient un identifiant de projet, c’est cet identifiant qui détermine le projet. Si un en-tête `gt-project-id` facultatif est fourni, il doit correspondre, sans quoi la requête échoue avec une erreur `403`. En l’absence de cible dans le chemin, les clés de projet utilisent le projet auquel elles sont liées ; les clés d’Organisation doivent envoyer `gt-project-id`. La découverte des projets et des Organisations ne nécessite aucune cible de projet. Les routes au niveau de l’Organisation dont le chemin comporte une cible utilisent cette Organisation, et les routes des Context Groups (`/v2/context-groups/{groupId}`) utilisent l’Organisation à laquelle appartient le groupe. Les anciens en-têtes de clé API restent pris en charge et ont priorité sur l’en-tête Bearer. 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/project/list-orgs), [List Projects](/docs/platform/openapi/reference/project/list-projects) et [Get Project information](/docs/platform/openapi/reference/project/project-info) 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/project/create-api-key) vous permet de sélectionner des permissions, ou d’omettre la sélection pour accorder toutes les permissions de projet délégables. Les droits HTTP Write explicites n’incluent pas implicitement Read. Les endpoints de Context Management nécessitent des permissions d’organisation, et donc une clé d’organisation ; les clés de projet ne peuvent pas les appeler. 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 et consulter les informations sur les fichiers, l’état des traductions, les informations sur les branches, les fichiers orphelins 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. * `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. ### 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 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 mise en file d’attente de traductions. * **Moyen :** 120 requêtes/minute pour les téléversements, les diffs, la génération de 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 découverte de projets et d’organisations, 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, la traduction à l’exécution et Context Management. La découverte de projets et d’organisations ainsi que la création de projets/clés partagent la même limite de requêtes. En cas de dépassement d’une limite après authentification, l’API renvoie `429` avec des en-têtes `RateLimit-*`. Les quotas de jetons d’organisation renvoient `402` depuis `POST /v2/translate`. ### 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 Les erreurs 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. 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 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. * `409` en cas de conflit, par exemple lorsqu’une création de projet dépasserait la limite de projets de l’organisation 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). * `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. Pour les réponses `425`, `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 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. 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/context-management/list-groups - /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.