# 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 in fase di esecuzione con `POST /v2/projects/{projectId}/translate`, sono disponibili all'indirizzo `https://api.gtx.dev`. ### Autenticazione Esegui l'autenticazione con una chiave API nell'intestazione standard `Authorization`. ```bash curl https://api.gtx.dev/v2/projects/PROJECT_ID \ -H "Authorization: Bearer gtx-api-..." \ -H "gt-api-version: 2026-10-08.v1" ``` Scegli l'ambito della chiave adatto al tuo workflow: * **progetto** con prefisso `gtx-api-`: associata a un progetto e utilizzabile in qualsiasi ambiente, in base alle sue autorizzazioni * **Organization** con prefisso `gtx-org-`: funziona in tutti i progetti dell'Organization a cui è associata, in base alle sue autorizzazioni Il percorso determina su cosa agisce una richiesta: `/v2/projects/{projectId}/...` sul progetto, `/v2/orgs/{orgId}/...` sull'Organization e `/v2/context-groups/{groupId}/...` sull'Organization proprietaria del gruppo. Gli endpoint di individuazione (`GET /v2/orgs` e `GET /v2/projects`) non richiedono alcun ID. La chiave deve avere accesso al progetto o all'Organization selezionati, quindi una chiave di progetto funziona solo sul proprio progetto. Non includere le chiavi API nei bundle distribuiti per browser e dispositivi mobili. (Vedi [chiavi API](/docs/platform/dashboard/reference/api-keys) per sapere come creare e definire l'ambito delle chiavi API). ### Autorizzazioni La maggior parte degli endpoint richiede un'autorizzazione sull'identità della richiesta. [List Organizations](/docs/platform/openapi/reference/organizations/list-orgs), [List Projects](/docs/platform/openapi/reference/projects/list-projects) e [Get a Project](/docs/platform/openapi/reference/projects/get-project) non richiedono alcuna autorizzazione sulle risorse, oltre all'accesso all'Organization o al progetto restituiti. Sia le chiavi di Organization sia quelle di progetto supportano autorizzazioni **All** o **Custom** nella Dashboard, limitate alle autorizzazioni che il creatore può concedere. L'[endpoint delle chiavi API di progetto](/docs/platform/openapi/reference/projects/create-project-api-key) consente di selezionare le autorizzazioni oppure di omettere la selezione per concedere tutte le autorizzazioni di progetto che puoi delegare. Le autorizzazioni Write non includono Read. Le chiavi di progetto non possono avere autorizzazioni a livello di Organization (`org:*`) né `project:api_keys:write`, quindi gli endpoint che le richiedono necessitano di una chiave di Organization. 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`. * `org:assets:write` per caricare font con `POST /v2/orgs/{orgId}/assets`. * `project:files:read` per scaricare file; leggere i metadati e lo stato dei file; elencare i branch e i relativi file; e leggere i job. * `project:files:write` per caricare file sorgente e traduzioni; sovrascrivere traduzioni; pubblicare; creare e aggiornare branch; impostare tag; e spostare file. * `project:translations:enqueue` per tradurre file con `POST /v2/projects/{projectId}/files/translate`. * `project:translations:generate` per la traduzione in fase di esecuzione. * `project:context:write` per generare il contesto. * `org:context:read` per leggere i Context Group, il relativo Glossario e i prompt personalizzati, le assegnazioni ai progetti e le esportazioni. * `org:context:write` per creare, aggiornare ed eliminare i Context Group e il relativo contenuto, importare contenuti, nonché assegnare i gruppi ai progetti, revocarne l'assegnazione e riordinarli. * `project:write` per aggiornare le impostazioni del progetto. ### Versionamento Invia l'intestazione `gt-api-version` con ogni richiesta per selezionare il contratto dell'API. ```bash -H "gt-api-version: 2026-10-08.v1" ``` * Gli endpoint la cui pagina di riferimento indica l'intestazione come obbligatoria restituiscono `400` se l'intestazione è assente o specifica una versione precedente. * Gli altri endpoint, se l'intestazione è assente, usano la versione supportata meno recente e restituiscono gli errori in testo semplice anziché in JSON. Per consultare gli endpoint di una versione precedente, selezionala nel menu della versione dell'API in cima a qualsiasi pagina OpenAPI. ### Richieste batch Gli endpoint batch elencati di seguito restituiscono un risultato per ogni elemento, nello stesso ordine della richiesta. * **Scritture** (caricamento di file sorgente e traduzioni, spostamento, pubblicazione e sovrascrittura di file, caricamento di asset dei font): restituiscono `200` con `summary` (conteggi `total`, `succeeded` e `failed`) e `results`, anche quando tutti gli elementi non vanno a buon fine. Un elemento non riuscito ha `status: "failed"` e un `error`; gli altri elementi vengono comunque applicati. Una richiesta che non supera la convalida restituisce `400` e non applica alcuna modifica. * **Letture** (query su file, contenuto dei file e job): restituiscono `200` con `results`. Un elemento non presente nel progetto risulta `not_found`. Una traduzione di file già memorizzata ma non ancora completata, ad esempio durante un passaggio di layout, risulta `pending`: richiedila di nuovo più tardi. Una traduzione risulta `not_found` finché la relativa attività di traduzione non l'ha memorizzata, quindi prima di leggerla attendi il completamento del job con `GET /v2/projects/{projectId}/jobs/{jobId}` o `POST /v2/projects/{projectId}/jobs/query`. Senza `versionId`, una lettura restituisce la versione completata più recente sul branch e risulta `pending` solo finché nessuna versione è stata completata. Le query sui job restituiscono lo stato di ciascun job. Gli altri endpoint batch prevedono una risposta specifica: l'accodamento della traduzione di file restituisce `202` con i `jobs` creati, mentre gli upsert del glossario e dei prompt personalizzati di Context Management applicano l'intero batch oppure nulla e restituiscono `committed` con i `counts` degli elementi. ### Limiti dei metadati a runtime Per `POST /v2/projects/{projectId}/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 I limiti di frequenza si applicano su finestre di 60 secondi, a due livelli: * **Prima dell'autenticazione:** ogni credenziale presentata può effettuare 600 tentativi al minuto, comprese le richieste che non superano l'autenticazione. Le richieste prive di credenziale non sono soggette a questo livello. Il superamento del limite restituisce `429` con `Retry-After: 60` e senza intestazioni `RateLimit-*`. * **Dopo l'autenticazione:** ogni gruppo di route limita le richieste per chiamante autenticato, ad esempio una chiave API. Per le route soggette a limiti prive di un chiamante autenticato viene utilizzato l'IP del client. I limiti successivi all'autenticazione variano in base all'endpoint: * **Heavy:** 30 richieste/minuto per la traduzione di file. * **Medium:** 120 richieste/minuto per il caricamento di file sorgente, traduzioni e font; la sovrascrittura delle traduzioni; la generazione del contesto; lo spostamento di file; l'elenco dei file del branch e la pubblicazione. * **Light:** 300 richieste/minuto per il download di file. * **Default:** 200 richieste/minuto per l'individuazione di progetti e Organization, la creazione di progetti e di chiavi API di progetto, le impostazioni del progetto, branch, tag, job, metadati e stato dei file, traduzione in fase di esecuzione e Context Management. L'elenco dei progetti, la creazione di progetti e la creazione di chiavi API di progetto condividono un unico limite. Il superamento di un limite successivo all'autenticazione restituisce `429` con intestazioni `RateLimit-*`. ### Paginazione Gli endpoint di elenco restituiscono una pagina di risultati nel formato `{ "items": [...], "nextCursor": ... }`. Passa `limit` (da 1 a 100, valore predefinito 50) per impostare la dimensione della pagina. Quando `nextCursor` è una string, invialo come `cursor` per recuperare la pagina successiva; quando è `null`, non ci sono altri risultati. Un cursore è valido solo per l'elenco e i filtri che lo hanno generato. Le pagine vengono lette in modo indipendente, quindi gli elementi modificati tra una richiesta e l'altra potrebbero essere saltati o comparire più volte. ### Errori Con `gt-api-version` impostato, gli errori restituiscono un corpo JSON con un messaggio `error`. Questo vale per tutti gli errori, compresi JSON non valido (`400`), corpi di dimensioni eccessive (`413`) e superamento dei limiti di frequenza (`429`). ```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 l'account di fatturazione dell'Organization è bloccato, oppure i suoi limiti di utilizzo o il saldo dei crediti non sono sufficienti a coprire la richiesta (traduzione di file e traduzione in fase di esecuzione). * `403` quando l'identità della richiesta non dispone dell'autorizzazione necessaria o l'azione non è consentita nel piano attuale. * `404` quando la risorsa non viene trovata. * `409` in caso di conflitto, ad esempio quando la creazione di un progetto supera il limite di progetti dell'Organization, quando un nome di branch è già in uso o quando una ridenominazione entra in conflitto con un termine del Glossario o un prompt personalizzato già esistente. * `413` quando il corpo della richiesta supera il limite dell'endpoint oppure quando una risposta di Context Management supererebbe 1 MiB (in tal caso, richiedi un `limit` inferiore). * `415` quando il `Content-Type` del corpo della richiesta è assente o diverso da `application/json`. * `429` quando viene superato un limite di frequenza. * `500` per un errore interno del server. * `503` quando il servizio è temporaneamente non disponibile. In caso di risposte `429` e `503`, riprova la richiesta dopo un intervallo di attesa. Per `429`, attendi il numero di secondi indicato nell'intestazione `Retry-After`. ## Specifica OpenAPI [#openapi-spec] Una specifica OpenAPI 3.1 dell'ultima versione, in formato leggibile dalle macchine, è disponibile all'indirizzo [`/openapi.json`](/openapi.json), mentre quella di ciascuna versione precedente si trova in `/openapi/.json`. Importala in Postman, Insomnia o in un client OpenAPI per generare richieste e tipi. Per gli helper tipizzati degli endpoint, usa il [client `@generaltranslation/api`](/docs/platform/core/reference/api-client). ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.