# General Translation Platform: Обзор
URL: https://generaltranslation.com/ru/docs/platform/openapi/overview.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Обращайтесь к публичным конечным точкам API General Translation и скачивайте спецификацию OpenAPI.

Используйте API General Translation, чтобы создавать собственные рабочие процессы автоматизации.

CLI берёт на себя большинство вызовов API. Используйте [TypeScript-клиент `@generaltranslation/api`](/docs/platform/core/reference/api-client) для получения сгенерированных типов запросов и ответов или обращайтесь к конечным точкам напрямую, когда вам нужна собственная автоматизация.

Спецификация OpenAPI определяет эти конечные точки в машиночитаемом формате.

## Основы API [#api-basics]

### Базовый URL

Все конечные точки, включая конечную точку для перевода во время выполнения `POST /v2/projects/{projectId}/translate`, доступны по адресу `https://api.gtx.dev`.

### Аутентификация

Для аутентификации передавайте API-ключ в стандартном заголовке `Authorization`.

```bash
curl https://api.gtx.dev/v2/projects/PROJECT_ID \
  -H "Authorization: Bearer gtx-api-..." \
  -H "gt-api-version: 2026-10-08.v1"
```

Выберите область ключа, соответствующую вашему рабочему процессу:

* **Проект** с префиксом `gtx-api-`: привязан к одному проекту и может использоваться в любом окружении с учётом его разрешений
* **Организация** с префиксом `gtx-org-`: работает во всех проектах той организации, к которой он привязан, с учётом его разрешений

Путь определяет, над чем выполняется запрос: `/v2/projects/{projectId}/...` — над проектом, `/v2/orgs/{orgId}/...` — над организацией, а `/v2/context-groups/{groupId}/...` — над организацией, которой принадлежит группа. Конечным точкам обнаружения (`GET /v2/orgs` и `GET /v2/projects`) ID не нужен. Ключ должен иметь доступ к выбранному проекту или организации, поэтому ключ проекта работает только со своим проектом.

Не включайте API-ключи в развёртываемые браузерные и мобильные бандлы.

(См. [API-ключи](/docs/platform/dashboard/reference/api-keys), чтобы узнать, как создавать API-ключи и задавать для них область).

### Разрешения

Для большинства конечных точек требуется соответствующее разрешение у идентичности запроса. [List организаций](/docs/platform/openapi/reference/organizations/list-orgs), [List проектов](/docs/platform/openapi/reference/projects/list-projects) и [Получение проекта](/docs/platform/openapi/reference/projects/get-project) не требуют разрешений на ресурсы — достаточно доступа к возвращаемой организации или проекту. И ключи организации, и ключи проекта поддерживают разрешения **All** или **Custom** в Dashboard, ограниченные теми разрешениями, которые может выдать создатель. [Конечная точка API-ключей проекта](/docs/platform/openapi/reference/projects/create-project-api-key) позволяет выбрать разрешения или не указывать их: в этом случае выдаются все разрешения проекта, которые вы можете делегировать. Разрешения Write не включают Read. Ключи проекта не могут иметь разрешения уровня организации (`org:*`) или `project:api_keys:write`, поэтому для конечных точек, которым они требуются, нужен ключ организации.

Распространённые разрешения:

* `org:projects:create` для создания проектов с помощью `POST /v2/orgs/{orgId}/projects`.
* `project:api_keys:write` для создания API-ключей проекта с помощью `POST /v2/projects/{projectId}/api-keys`.
* `org:assets:write` для загрузки шрифтов с помощью `POST /v2/orgs/{orgId}/assets`.
* `project:files:read` для скачивания файлов; чтения метаданных и статуса файлов; получения списка веток и файлов веток; а также чтения заданий.
* `project:files:write` для загрузки исходных файлов и переводов; перезаписи переводов; публикации; создания и обновления веток; установки тегов; а также перемещения файлов.
* `project:translations:enqueue` для перевода файлов с помощью `POST /v2/projects/{projectId}/files/translate`.
* `project:translations:generate` для перевода во время выполнения.
* `project:context:write` для генерации контекста.
* `org:context:read` для чтения контекстных групп, их Glossary и пользовательских промптов, назначений проектам и экспортов.
* `org:context:write` для создания, обновления и удаления контекстных групп и их содержимого, импорта содержимого, а также для назначения групп проектам, отмены назначения и изменения их порядка.
* `project:write` для обновления настроек проекта.

### Управление версиями

Передавайте заголовок `gt-api-version` в каждом запросе, чтобы указать версию контракта API.

```bash
-H "gt-api-version: 2026-10-08.v1"
```

* Конечные точки, у которых на справочной странице этот заголовок отмечен как обязательный, возвращают `400`, если он отсутствует или указывает более старую версию.
* Остальные конечные точки при отсутствии заголовка используют самую старую из поддерживаемых версий и возвращают ошибки в виде обычного текста, а не JSON.

Чтобы просмотреть конечные точки более старой версии, выберите её в меню версий API в верхней части любой страницы OpenAPI.

### Пакетные запросы

Перечисленные ниже пакетные конечные точки возвращают по одному результату на каждый элемент в том же порядке, что и в запросе.

* **Операции записи** (загрузка исходных файлов и переводов, перемещение, публикация и перезапись файлов, а также загрузка шрифтов) возвращают `200` с `summary` (количество `total`, `succeeded` и `failed`) и `results`, даже если ни один элемент не обработан успешно. У элемента с ошибкой указаны `status: "failed"` и `error`; остальные элементы при этом всё равно применяются. Запрос, не прошедший валидацию, возвращает `400`, и ничего не применяется.
* **Операции чтения** (запросы файлов, содержимого файлов и заданий) возвращают `200` с `results`. Элемент, которого нет в проекте, получает статус `not_found`. Перевод файла, который уже сохранён, но ещё не завершён (например, во время обработки вёрстки), получает статус `pending` — повторите запрос позже. Пока задание на перевод не сохранило перевод, он имеет статус `not_found`, поэтому перед чтением дождитесь завершения задания с помощью `GET /v2/projects/{projectId}/jobs/{jobId}` или `POST /v2/projects/{projectId}/jobs/query`. Если `versionId` не указан, чтение возвращает последнюю завершённую версию в ветке; статус `pending` возвращается, только пока ни одна версия не завершена. Запросы заданий возвращают статус каждого задания.

Остальные пакетные конечные точки возвращают ответы в собственном формате: постановка перевода файлов в очередь возвращает `202` с созданными `jobs`, а upsert глоссария и пользовательских промптов в Context Management применяет пакет целиком либо не применяет ничего и возвращает `committed` с `counts` по элементам.

### Ограничения метаданных времени выполнения

Для `POST /v2/projects/{projectId}/translate` положительное целое значение `maxChars` добавляет в поддерживаемые промпты перевода указание о длине; это не гарантированное ограничение длины результата. Неположительные и дробные числа игнорируются. Значения неверного типа не проходят валидацию запроса.

Каждый файл `sourceCode` хранит не более пяти контекстных записей. API усекает поля `before` и `after` каждой записи до 2 000 символов, а поле `target` — до 500 символов.

Укажите для `fileFormat` значение `MD` или `MDX`, чтобы перевести целый документ, переданный в виде строки. Запросы на перевод документов должны использовать `dataFormat: STRING` и не могут содержать `maxChars` или `sourceCode`. API разбивает документ на фрагменты, добавляет контекст запроса к каждому фрагменту и возвращает одну проверенную строку документа. Если фрагмент не удалось перевести или итоговый документ оказался некорректным, ошибку получает соответствующая запись, а частичный результат не возвращается.

### Лимиты запросов

Частота запросов ограничивается в 60-секундных окнах на двух уровнях:

* **До аутентификации:** для каждых предъявленных учётных данных допускается 600 попыток в минуту, включая запросы, не прошедшие аутентификацию. Запросы без учётных данных пропускают этот уровень. При превышении лимита возвращается `429` с `Retry-After: 60` и без заголовков `RateLimit-*`.
* **После аутентификации:** каждая группа маршрутов ограничивает запросы для каждой аутентифицированной вызывающей стороны, например API-ключа. Для ограниченных маршрутов без аутентифицированной вызывающей стороны используется IP-адрес клиента.

Лимиты после аутентификации зависят от конечной точки:

* **Тяжёлые:** 30 запросов в минуту для перевода файлов.
* **Средние:** 120 запросов в минуту для загрузки исходных файлов, переводов и шрифтов, перезаписи переводов, генерации контекста, перемещения файлов, получения списка файлов ветки и публикации.
* **Лёгкие:** 300 запросов в минуту для скачивания файлов.
* **По умолчанию:** 200 запросов в минуту для обнаружения проектов и организаций, создания проекта и API-ключей проекта, настроек проекта, веток, тегов, заданий, метаданных и статуса файлов, перевода во время выполнения и Context Management.

Получение списка проектов, создание проектов и создание API-ключей проекта подчиняются общему лимиту.

При превышении лимита после аутентификации возвращается `429` с заголовками `RateLimit-*`.

### Пагинация

Эндпоинты списков возвращают одну страницу результатов в формате `{ "items": [...], "nextCursor": ... }`. Чтобы задать размер страницы, передайте `limit` (от 1 до 100, по умолчанию 50). Если `nextCursor` содержит строку, передайте её в параметре `cursor`, чтобы получить следующую страницу; если значение равно `null`, результатов больше нет. Курсор действителен только для того списка и тех фильтров, для которых он был выдан. Страницы запрашиваются независимо друг от друга, поэтому элементы, изменившиеся между запросами, могут быть пропущены или продублированы.

### Ошибки

Если задан заголовок `gt-api-version`, ошибки возвращают тело ответа в формате JSON с сообщением `error`. Это относится ко всем ошибкам, включая некорректный JSON (`400`), превышение допустимого размера тела запроса (`413`) и превышение лимита запросов (`429`).

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

Распространённые коды статуса:

* `400` для недопустимого тела запроса, параметров query или версии.
* `401` для отсутствующих или недопустимых bearer-учётных данных.
* `402`, если платёжный аккаунт организации заблокирован либо её лимитов использования или баланса кредитов недостаточно для выполнения запроса (перевод файлов и перевод во время выполнения).
* `403`, если у идентичности запроса нет разрешения или действие недоступно в текущем тарифном плане.
* `404`, если ресурс не найден.
* `409` при конфликте, например если при создании проекта превышен лимит проектов организации, имя ветки уже занято или если переименование приводит к совпадению с существующим термином Glossary или пользовательским промптом.
* `413`, если тело запроса превышает лимит конечной точки или если ответ Context Management превысит 1 MiB (запросите меньшее значение `limit`).
* `415`, если `Content-Type` тела запроса отсутствует или отличается от `application/json`.
* `429`, если превышен лимит запросов.
* `500` для внутренней ошибки сервера.
* `503`, если сервис временно недоступен.

При получении ответов `429` и `503` повторите запрос через некоторое время. В случае `429` подождите столько секунд, сколько указано в заголовке `Retry-After`.

## Спецификация OpenAPI [#openapi-spec]

Машиночитаемая спецификация OpenAPI 3.1 для последней версии доступна по адресу [`/openapi.json`](/openapi.json), а для каждой из предыдущих версий — по адресу `/openapi/<version>.json`. Импортируйте её в Postman, Insomnia или OpenAPI-клиент, чтобы генерировать запросы и типы.

Для типизированных вспомогательных функций конечных точек используйте [клиент `@generaltranslation/api`](/docs/platform/core/reference/api-client).

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.