# api: Référence de l’API URL: https://generaltranslation.com/fr/docs/api.mdx --- title: Référence de l’API description: Endpoints publics de l’API General Translation, authentification et spécification OpenAPI index: true --- L’API General Translation vous permet d’uploader du contenu source et des fichiers traduits, de télécharger des traductions, de traduire du contenu et de le mettre en file d’attente, de gérer les branches et les tags, et de consulter l’état des projets et des jobs. La plupart des workflows des SDK et de la CLI appellent ces endpoints pour vous, mais vous pouvez également les appeler directement pour une automatisation personnalisée. Chaque endpoint a sa propre page dans cette section, avec des paramètres, des schémas et un environnement interactif pour tester les requêtes. Une spécification OpenAPI 3.1 lisible par machine est fournie avec ces pages sous la forme de `openapi.yaml` — importez-la dans Postman, Insomnia ou un client OpenAPI pour générer des requêtes et des types. ## URL de base | API | URL de base | | ----------------------------------------- | ------------------------- | | Endpoints de projet et de fichier | `https://api.gtx.dev` | | traduction à l’exécution (`POST /v2/translate`) | `https://runtime.gtx.dev` | ## Authentification Authentifiez chaque requête à l’aide d’une clé API dans l’en-tête `x-gt-api-key`. ```bash curl https://api.gtx.dev/v2/project/info/PROJECT_ID \ -H "x-gt-api-key: gtx-api-..." ``` | Type de clé | Préfixe | Notes | | ---------------------- | ---------- | ---------------------------------------------------------------------------------------------------------- | | Projet (production) | `gtx-api-` | Liée à un seul projet | | Projet (développement) | `gtx-dev-` | Usage local et en prévisualisation ; rejetée par les endpoints réservés à la production | | Organisation | `gtx-org-` | Fonctionne sur plusieurs projets ; vous devez envoyer `x-gt-project-id` sur les routes propres à un projet | **Clés d'organisation :** lorsque vous vous authentifiez avec une clé d'organisation, incluez le projet cible dans l'en-tête `x-gt-project-id` pour tout endpoint propre à un projet. Consultez [API keys](/docs/platform/api-keys) pour savoir comment créer des clés et définir leur niveau. ## Autorisations Chaque endpoint nécessite une permission sur l’clé API. Les clés d’organisation les configurent explicitement ; les clés de projet reprennent les valeurs par défaut du projet. | Permission | Utilisé par | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `project:files:read` | Téléchargement de fichiers, informations sur les fichiers, état des traductions, informations sur les branches, fichiers orphelins, informations sur le projet, informations sur les jobs | | `project:files:write` | Upload de fichiers et de traductions, diffs, publication, création de branches, création de tags, déplacements | | `project:translations:enqueue` | Mise en file d’attente des fichiers pour traduction | | `project:translations:generate` | Traduction à l’exécution | | `project:context:read` | Lecture de l’état de génération du contexte | | `project:context:write` | Génération du contexte | | `project:write` | Mise à jour des paramètres du projet | ## Gestion des versions Envoyez l’en-tête facultatif `gt-api-version` pour figer un format de réponse. S’il est omis, la version prise en charge la plus ancienne est utilisée. La version la plus récente est `2026-03-06.v1`. ```bash -H "gt-api-version: 2026-03-06.v1" ``` ## Limites de requêtes Les requêtes sont limitées par clé API (ou par IP cliente) sur une période de 60 secondes. Les limites varient selon l'endpoint : | Tier | Limit | Endpoints | | ------- | --------- | ---------------------------------------------------------------------------------------------------------------- | | Heavy | 20 / min | Mise en file d’attente des traductions | | Medium | 60 / min | Upload, diffs, contexte, déplacements, éléments orphelins | | Light | 120 / min | Téléchargement de fichiers | | Default | 200 / min | Publication, branches, tags, infos projet, infos job, infos fichier, état des traductions, traduction au Runtime | Le dépassement d’une limite renvoie `429`. Les quotas des jetons d’Organization peuvent également renvoyer `429` pour `POST /v2/translate`. ## Erreurs Les erreurs renvoient un corps JSON contenant un message `error` : ```json { "error": "API key is missing required permission: project:files:write" } ``` | État | Signification | | ----- | ----------------------------------------------------------------------------------------------------------- | | `400` | Corps de requête, paramètres de requête ou version invalides | | `401` | Clé API manquante ou invalide | | `403` | La clé API ne dispose pas de l’autorisation requise, ou l’action n’est pas autorisée avec le forfait actuel | | `404` | Ressource introuvable | | `429` | Limite de requêtes ou quota de jetons dépassé | ## Étapes suivantes * [Clés API](/docs/platform/api-keys) - Créez des clés et définissez leur portée * [Webhooks](/docs/platform/webhooks) - Recevez les événements de traduction * [Locales prises en charge](/docs/platform/supported-locales) - Codes de langue utilisés dans les requêtes