# api: Riferimento API URL: https://generaltranslation.com/it/docs/api.mdx --- title: Riferimento API description: Endpoint API pubblici di General Translation, autenticazione e specifica OpenAPI index: true --- L'API di General Translation ti consente di caricare contenuti sorgente e file tradotti, scaricare traduzioni, tradurre e mettere in coda contenuti, gestire branch e tag e consultare lo stato di progetti e job. La maggior parte dei workflow degli SDK e della CLI richiama questi endpoint automaticamente, ma puoi anche chiamarli direttamente per automazioni personalizzate. Ogni endpoint ha una pagina dedicata in questa sezione con parametri, schemi e un playground interattivo per le richieste. Insieme a queste pagine è disponibile anche una specifica OpenAPI 3.1 in formato machine-readable come `openapi.yaml`: importala in Postman, Insomnia o in un client OpenAPI per generare richieste e tipi. ## URL di base | API | URL di base | | ----------------------------------------- | ------------------------- | | Endpoint di progetto e file | `https://api.gtx.dev` | | Traduzione runtime (`POST /v2/translate`) | `https://runtime.gtx.dev` | ## Autenticazione Autentica ogni richiesta con una chiave API nell'header `x-gt-api-key`. ```bash curl https://api.gtx.dev/v2/project/info/PROJECT_ID \ -H "x-gt-api-key: gtx-api-..." ``` | Tipo di chiave | Prefisso | Note | | --------------------- | ---------- | ------------------------------------------------------------------------------------------- | | Progetto (produzione) | `gtx-api-` | Associata a un solo progetto | | Progetto (sviluppo) | `gtx-dev-` | Per uso locale e in anteprima; rifiutata dagli endpoint riservati alla produzione | | Organizzazione | `gtx-org-` | Funziona su più progetti; nelle route a livello di progetto, devi inviare `x-gt-project-id` | **Chiavi di organizzazione:** Quando esegui l'autenticazione con una chiave di organizzazione, includi il progetto di destinazione nell'header `x-gt-project-id` per qualsiasi endpoint a livello di progetto. Vedi [chiavi API](/docs/platform/api-keys) per sapere come creare le chiavi e definirne lo scope. ## Autorizzazioni Ogni endpoint richiede un'autorizzazione sulla chiave API. Le chiavi di organizzazione le configurano esplicitamente; le chiavi di progetto usano quelle predefinite del progetto. | Autorizzazione | Utilizzato per | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `project:files:read` | Scaricare file, informazioni sui file, stato delle traduzioni, informazioni sul branch, file orfani, informazioni sul progetto, informazioni sui job | | `project:files:write` | Caricare file e traduzioni, diff, pubblicazione, creazione di branch, creazione di tag, spostamenti | | `project:translations:enqueue` | Accodare i file per la traduzione | | `project:translations:generate` | Traduzione runtime | | `project:context:read` | Leggere lo stato di generazione del contesto | | `project:context:write` | Generare il contesto | | `project:write` | Aggiornare le impostazioni del progetto | ## Versioning Invia l'header facoltativo `gt-api-version` per bloccare il formato della risposta. Se omesso, viene usata la versione supportata meno recente. L'ultima versione è `2026-03-06.v1`. ```bash -H "gt-api-version: 2026-03-06.v1" ``` ## Limiti di frequenza Le richieste sono soggette a limiti di frequenza per chiave API (o IP client) in una finestra di 60 secondi. I limiti variano in base all'endpoint: | Tier | Limit | Endpoints | | ------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | Heavy | 20 / min | Accodamento delle traduzioni | | Medium | 60 / min | Upload, diff, contesto, spostamenti, elementi orfani | | Light | 120 / min | Download dei file | | Default | 200 / min | Pubblicazione, branch, tag, informazioni sul progetto, informazioni sul job, informazioni sul file, stato della traduzione, traduzione Runtime | Il superamento di un limite restituisce `429`. Anche le quote dei token di organizzazione possono restituire `429` da `POST /v2/translate`. ## Errori Gli errori restituiscono un corpo JSON con un messaggio `error`: ```json { "error": "API key is missing required permission: project:files:write" } ``` | Stato | Significato | | ----- | ------------------------------------------------------------------------------------------------------------- | | `400` | Corpo della richiesta, query o versione non validi | | `401` | chiave API mancante o non valida | | `403` | La chiave API non ha l'autorizzazione richiesta oppure l'azione non è consentita con il piano attuale | | `404` | Risorsa non trovata | | `429` | Limite di frequenza o quota di token superati | ## Passaggi successivi * [Chiavi API](/docs/platform/api-keys) - Crea chiavi e definiscine l'ambito * [Webhook](/docs/platform/webhooks) - Ricevi eventi di traduzione * [Impostazioni regionali supportate](/docs/platform/supported-locales) - Codici locale usati nelle richieste