# 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 Esegui l'autenticazione con una chiave API nell'header standard `Authorization`. ```bash curl https://api.gtx.dev/v2/project/info/PROJECT_ID \ -H "Authorization: Bearer gtx-api-..." ``` 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 Per gli endpoint con ambito progetto che hanno un ID progetto nel percorso, è quell'ID a selezionare il progetto. Se presente, il parametro facoltativo `gt-project-id` deve corrispondere, altrimenti la richiesta non riesce con `403`. Se il percorso non indica una destinazione, le chiavi di progetto usano il progetto a cui sono associate, mentre le chiavi di Organization devono inviare `gt-project-id`. L'individuazione di progetti e Organization non richiede un progetto di destinazione. Le route con ambito Organization che indicano una destinazione nel percorso usano quell'Organization, mentre le route dei Context Group (`/v2/context-groups/{groupId}`) usano l'Organization proprietaria del gruppo. Gli header legacy per le chiavi API restano supportati e hanno la precedenza sull'header bearer. 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/project/list-orgs), [List Projects](/docs/platform/openapi/reference/project/list-projects) e [Get Project information](/docs/platform/openapi/reference/project/project-info) 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/project/create-api-key) consente di selezionare le autorizzazioni oppure di omettere la selezione per concedere tutte le autorizzazioni di progetto delegabili. Le autorizzazioni HTTP Write concesse esplicitamente non includono implicitamente Read. Gli endpoint di Context Management richiedono autorizzazioni a livello di Organization, quindi è necessaria una chiave di Organization: le chiavi di progetto non possono chiamarli. 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 e leggere le informazioni sui file, lo stato della traduzione, le informazioni sul branch, i file orfani e le informazioni sui job. * `project:files:write` per effettuare il caricamento di 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. * `org:context:read` per leggere i Context Group, il relativo Glossario e i Custom Prompt, 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'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 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 header `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 l'accodamento delle traduzioni. * **Medium:** 120 richieste/minuto per caricamenti, diff, generazione del contesto, spostamenti, file orfani e pubblicare. * **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, branch, tag, informazioni sul progetto, informazioni sul job, informazioni sul file, stato della traduzione, traduzione runtime e Context Management. L'individuazione di progetti e Organization e la creazione di progetti/chiavi condividono lo stesso limite di richieste. Il superamento di un limite successivo all'autenticazione restituisce `429` con header `RateLimit-*`. Le quote dei token dell'Organization restituiscono `402` da `POST /v2/translate`. ### 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 Gli errori 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. 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 viene superata una quota di token di Organization (`POST /v2/translate`). * `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 o quando una ridenominazione entra in conflitto con un termine del Glossario o un Custom Prompt 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). * `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. In caso di risposte `425`, `429` e `503`, riprova la richiesta dopo un intervallo di attesa. Per `429`, attendi il numero di secondi indicato nell'header `Retry-After`. ## 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. 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/context-management/list-groups - /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.