# General Translation Platform: Panoramica
URL: https://generaltranslation.com/it/docs/platform/openapi/overview.mdx
---
title: Panoramica
description: Scopri come usare gli endpoint pubblici dell'API di General Translation e la specifica OpenAPI.

related:
  title: Sezioni di riferimento
  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
---

Usa l'API di General Translation per creare workflow di automazione personalizzati.

SDK e CLI gestiscono per te la maggior parte delle chiamate API. Chiama direttamente l'API quando devi caricare file, mettere in coda job di traduzione, scaricare traduzioni, gestire branch e tag oppure controllare lo status di Project e dei job dal tuo sistema.

La specifica OpenAPI definisce questi endpoint in un formato leggibile dalle macchine.

## Concetti di base dell'API [#api-basics]

### URL di base

* Usa `https://api2.gtx.dev` per gli endpoint dei progetti e dei file.
* Usa `https://runtime2.gtx.dev` per la traduzione runtime, compreso `POST /v2/translate`.

### Autenticazione

Invia la chiave API nell'header `x-gt-api-key`.

```bash
curl https://api2.gtx.dev/v2/project/info/PROJECT_ID \
  -H "x-gt-api-key: gtx-api-..."
```

Usa il tipo di chiave corretto:

* **Project (sviluppo)** con prefisso `gtx-dev-`: per uso locale e di anteprima, rifiutata dagli endpoint riservati alla produzione
* **Project (produzione)** con prefisso `gtx-api-`: associata a un Project
* **Organization** con prefisso `gtx-org-`: funziona in tutti i Project. Quando usi una chiave Organization su endpoint con ambito Project, devi inviare `x-gt-project-id`.

Vedi [chiavi API](/docs/platform/dashboard/reference/api-keys) per sapere come creare e definire l'ambito delle chiavi API.

### Autorizzazioni

Ogni endpoint richiede un'autorizzazione associata alla chiave API. Le chiavi di organizzazione configurano esplicitamente le autorizzazioni. Le chiavi di progetto usano quelle predefinite del Progetto.

Autorizzazioni comuni:

* `project:files:read` per scaricare file, leggere le informazioni sui file, lo stato della traduzione, le informazioni sul branch, i file orfani, le informazioni sul Progetto e le informazioni sui job.
* `project:files:write` per caricare file e traduzioni, diff, pubblicare, creare branch e tag e spostare file.
* `project:translations:enqueue` per mettere in coda i file per la traduzione.
* `project:translations:generate` per la traduzione runtime.
* `project:context:read` per leggere lo stato di generazione del contesto.
* `project:context:write` per generare il contesto.
* `project:write` per aggiornare le impostazioni del Progetto.

### Versionamento

Invia l'header facoltativo `gt-api-version` per vincolare il formato della risposta.

```bash
-H "gt-api-version: 2026-03-06.v1"
```

Se ometti l'header, viene utilizzata la prima versione supportata. L'ultima versione è `2026-03-06.v1`.

### Limiti di frequenza

Le richieste sono soggette a limiti di frequenza per chiave API o IP client su una finestra di 60 secondi. I limiti variano in base all'endpoint:

* **Heavy:** 30 richieste/minuto per l'accodamento delle traduzioni.
* **Medium:** 120 richieste/minuto per upload, diff, contesto, spostamenti e file orphaned.
* **Light:** 300 richieste/minuto per il download di file.
* **Default:** 200 richieste/minuto per publish, branch, tag, informazioni sul Project, informazioni sul job, informazioni sul file, stato della traduzione e traduzione runtime.

Il superamento di un limite restituisce `429`. Le quote dei token dell'Organization restituiscono `402` da `POST /v2/translate`.

### Errori

In caso di errore, viene restituito un messaggio `error`. Per la versione dell'API `2026-02-18.v1` e successive, il corpo è in JSON; nelle versioni precedenti, inclusa quella predefinita usata quando non viene inviato alcun header `gt-api-version`, il messaggio viene restituito come testo semplice.

```json
{
  "error": "API key is missing required permission: project:files:write"
}
```

Codici di stato comuni:

* `400` per corpo della richiesta, query o versione non validi.
* `401` per chiave API mancante o non valida.
* `402` quando viene superata una quota di token di Organization (`POST /v2/translate`).
* `403` quando la chiave API non dispone dell'autorizzazione necessaria o l'azione non è consentita nel piano attuale.
* `404` quando la risorsa non viene trovata.
* `429` quando viene superato un limite di richieste.

## Specifica OpenAPI [#openapi-spec]

Una specifica OpenAPI 3.1 in formato leggibile dalle macchine è disponibile all'indirizzo [`/openapi.yaml`](/openapi.yaml). Importala in Postman, Insomnia o in un client OpenAPI per generare richieste e tipi.
## Sezioni di riferimento

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