# General Translation Platform: Panoramica URL: https://generaltranslation.com/it/docs/platform/openapi/overview.mdx Docs index: https://generaltranslation.com/llms.txt Description: Chiama gli endpoint pubblici dell'API di General Translation e scarica la specifica OpenAPI. Usa l'API di General Translation per creare workflow di automazione personalizzati. La CLI gestisce per te la maggior parte delle chiamate API. Usa il [client TypeScript `generaltranslation/api`](/docs/platform/core/reference/api-client) per i tipi generati di richiesta e risposta, oppure chiama direttamente gli endpoint quando ti serve un'automazione personalizzata. La specifica OpenAPI definisce questi endpoint in un formato leggibile dalle macchine. ## Concetti di base dell'API [#api-basics] ### URL di base Tutti gli endpoint, inclusa la traduzione runtime con `POST /v2/translate`, sono disponibili all'indirizzo `https://api.gtx.dev`. ### Autenticazione Ogni endpoint richiede una credenziale bearer nell'header standard `Authorization`. Il riferimento degli endpoint indica se un'operazione accetta una chiave API, un token di accesso utente OAuth 2.1 o entrambi. ```bash curl https://api.gtx.dev/v2/project/info/PROJECT_ID \ -H "Authorization: Bearer gtx-api-..." ``` Usa il tipo di chiave corretto: * **progetto (sviluppo)** con prefisso `gtx-dev-`: per uso locale e di anteprima, rifiutata dagli endpoint riservati alla produzione * **progetto (produzione)** con prefisso `gtx-api-`: associata a un progetto * **Organization** con prefisso `gtx-org-`: funziona in tutti i progetti. La maggior parte degli endpoint con ambito progetto richiede `gt-project-id`. `GET /v2/project/info/{projectId}` richiede comunque quell'header e verifica che i due ID corrispondano. `POST /v2/projects/{projectId}/api-keys` usa invece il proprio parametro nel percorso. Gli endpoint con ambito Organization come `POST /v2/orgs/{orgId}/projects` usano l'Organization presente nel percorso e richiedono che la credential vi abbia accesso. (Vedi [chiavi API](/docs/platform/dashboard/reference/api-keys) per sapere come creare e definire l'ambito delle chiavi API). Le applicazioni OAuth usano il flow Authorization Code con Proof Key for Code Exchange (PKCE). Individua l'authorization server su `https://dash.generaltranslation.com/.well-known/oauth-authorization-server/api/auth`, richiedi solo gli scope necessari alla tua applicazione e invia l'access token utente risultante nello stesso header Bearer. Il token è limitato sia dagli scope concessi sia dall'accesso attuale dell'utente all'Organization o al progetto di destinazione. ### Autorizzazioni Ogni endpoint richiede un'autorizzazione sull'identità della richiesta. Le chiavi di Organization configurano esplicitamente le autorizzazioni. Le chiavi di progetto create nella Dashboard usano i valori predefiniti del rispettivo tipo di chiave; le chiavi create tramite l'API Organization possono avere meno autorizzazioni, poiché sono limitate a quelle che l'identità della richiesta può delegare. I token di accesso utente OAuth devono includere lo scope corrispondente e l'utente autenticato deve comunque possedere tale autorizzazione. Autorizzazioni comuni: * `org:projects:create` per creare progetti con `POST /v2/orgs/{orgId}/projects`. * `project:api_keys:write` per creare chiavi API di progetto con `POST /v2/projects/{projectId}/api-keys`. * `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, traduzioni e risorse; inviare 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: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 dei metadati a runtime Per `POST /v2/translate`, un valore intero positivo di `maxChars` aggiunge un'istruzione sulla lunghezza ai prompt di traduzione supportati; non è un limite garantito sulla lunghezza dell'output. I numeri non positivi o frazionari vengono ignorati. I valori di tipo errato fanno fallire la validazione della richiesta. Ogni file `sourceCode` conserva al massimo cinque entry di contesto. L'API tronca i campi `before` e `after` di ogni entry a 2.000 caratteri e il campo `target` a 500 caratteri. Imposta `fileFormat` su `MD` o `MDX` per tradurre un intero documento fornito come stringa. Le richieste di documenti devono usare `dataFormat: STRING` e non possono includere `maxChars` o `sourceCode`. L'API analizza il documento suddividendolo in blocchi, aggiunge il contesto della richiesta a ciascun blocco e restituisce una singola stringa di documento validata. Un blocco non riuscito o un documento finale non valido fa fallire quella entry anziché restituire un output parziale. ### 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, file orfani e pubblicare. * **Light:** 300 richieste/minuto per il download di file. * **Default:** 200 richieste/minuto per la creazione di progetti e di chiavi API di progetto, branch, tag, informazioni sul progetto, 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 Gli errori dell'applicazione autenticata restituiscono 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. Gli errori di analisi, di limite del payload e di limite di frequenza possono restituire testo semplice prima dell'autenticazione. ```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 credenziale bearer mancante o non valida. * `402` quando viene superata una quota di token di Organization (`POST /v2/translate`). * `403` quando l'identità della richiesta non dispone del permesso necessario o l'azione non è consentita nel piano attuale. * `404` quando la risorsa non viene trovata. * `413` quando il corpo della richiesta supera il limite dell'endpoint. * `425` quando un file tradotto richiesto è ancora in elaborazione. * `429` quando viene superato un limite di frequenza. * `500` per un errore interno del server. * `503` quando il servizio è temporaneamente non disponibile. ## Specifica OpenAPI [#openapi-spec] Una specifica OpenAPI 3.1 in formato leggibile dalle macchine è disponibile all'indirizzo [`/openapi.json`](/openapi.json). Importala in Postman, Insomnia o in un client OpenAPI per generare richieste e tipi. Gli strumenti JavaScript includono anche lo snapshot OpenAPI usato per generare la versione dell'SDK installata. Tale snapshot incluso nel bundle può differire dal contratto attualmente ospitato: * Esegui [`npx gt api --spec`](/docs/cli/reference/commands/api) con `gt` 2.20.0 o versione successiva. * Importa `generaltranslation/api/openapi.json` da `generaltranslation` 9.2.0 o versione successiva. * Importa `@generaltranslation/api/spec/openapi.json` dall'SDK generato autonomo. Per gli helper tipizzati degli endpoint, usa il [client `generaltranslation/api`](/docs/platform/core/reference/api-client). ## Sezioni di riferimento - /docs/platform/core/reference/api-client - /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/create-project ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.