# General Translation Platform: Vue d’ensemble
URL: https://generaltranslation.com/fr/docs/platform/openapi/overview.mdx
---
title: Vue d’ensemble
description: Découvrez comment utiliser les endpoints publics de l’API General Translation et la spécification OpenAPI.

related:
  title: Sections de référence
  links:
    - /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/project-info
---

Utilisez l’API General Translation pour créer des workflows d’automatisation personnalisés.

Le SDK et la CLI gèrent la plupart des appels à l’API pour vous. Appelez l’API directement lorsque vous devez envoyer des fichiers, mettre en file d’attente des jobs de traduction, télécharger des traductions, gérer des branches et des tags, ou consulter l’état du projet et des jobs depuis votre propre système.

La spécification OpenAPI définit ces endpoints dans un format exploitable par machine.

## Notions de base de l’API [#api-basics]

### URL de base

* Utilisez `https://api2.gtx.dev` pour les endpoint de projet et de fichier.
* Utilisez `https://runtime2.gtx.dev` pour la traduction à l’exécution, y compris `POST /v2/translate`.

### Authentification

Envoyez votre clé API dans l’en-tête `x-gt-api-key`.

```bash
curl https://api2.gtx.dev/v2/project/info/PROJECT_ID \
  -H "x-gt-api-key: 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. Lorsque vous utilisez une clé d’Organisation sur des endpoints au niveau du Projet, vous devez envoyer `x-gt-project-id`.

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

Chaque endpoint nécessite une permission sur la clé API. Les clés d’organisation configurent les permissions explicitement. Les clés de projet utilisent les valeurs par défaut du projet.

Permissions courantes :

* `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 et des traductions, 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:read` pour lire l’état de génération du contexte.
* `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 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 uploads, les diffs, le contexte, les déplacements et les fichiers orphelins.
* **Faible :** 300 requêtes/minute pour les téléchargements de fichiers.
* **Par défaut :** 200 requêtes/minute pour la publication, 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 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.

```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 une clé API manquante ou invalide.
* `402` lorsque le quota de jetons de l’organisation est dépassé (`POST /v2/translate`).
* `403` lorsque la clé API 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.
* `429` lorsqu’une limite de débit est dépassée.

## Spécification OpenAPI [#openapi-spec]

Une spécification OpenAPI 3.1 exploitable par des machines est disponible à l’adresse [`/openapi.yaml`](/openapi.yaml). Importez-la dans Postman, Insomnia ou un client OpenAPI pour générer des requêtes et des types.
## Sections de référence

- /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/project-info