# 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/translate`, доступны по адресу `https://api.gtx.dev`.

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

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

```bash
curl https://api.gtx.dev/v2/project/info/PROJECT_ID \
  -H "Authorization: Bearer gtx-api-..."
```

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

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

Для эндпоинтов с областью проекта, у которых ID проекта указан в пути, проект определяется этим ID. Необязательный заголовок `gt-project-id` должен с ним совпадать, иначе запрос завершится ошибкой `403`. Если цель в пути не указана, ключи проекта используют привязанный к ним проект, а ключи организации должны передавать `gt-project-id`. Для обнаружения проектов и организаций указывать целевой проект не нужно. Маршруты с областью организации, у которых цель указана в пути, используют эту организацию, а маршруты контекстных групп (`/v2/context-groups/{groupId}`) — организацию, которой принадлежит группа.

Устаревшие заголовки API-ключей по-прежнему поддерживаются и имеют приоритет над bearer-заголовком. Не включайте API-ключи в развёртываемые браузерные и мобильные бандлы.

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

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

Для большинства эндпоинтов требуется соответствующее разрешение у идентичности запроса. [List организаций](/docs/platform/openapi/reference/project/list-orgs), [List проектов](/docs/platform/openapi/reference/project/list-projects) и [Получение информации о проекте](/docs/platform/openapi/reference/project/project-info) не требуют разрешений на ресурсы — достаточно доступа к возвращаемой организации или проекту. И ключи организации, и ключи проекта поддерживают разрешения **All** или **Custom** в Dashboard, ограниченные теми разрешениями, которые может выдать создатель. [Эндпоинт API-ключей проекта](/docs/platform/openapi/reference/project/create-api-key) позволяет выбрать разрешения или не указывать их: в этом случае выдаются все делегируемые разрешения проекта. Явно выданные разрешения HTTP Write не включают Read автоматически. Эндпоинтам Context Management требуются разрешения уровня организации, поэтому для них нужен ключ организации; ключи проекта не могут их вызывать.

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

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

### Версионирование

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

```bash
-H "gt-api-version: 2026-03-06.v1"
```

Если заголовок не указан, используется самая ранняя поддерживаемая версия. Последняя версия — `2026-03-06.v1`.

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

Для `POST /v2/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.

Обнаружение проектов и организаций, а также создание проектов и ключей подчиняются общему лимиту запросов.

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

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

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

### Ошибки

Ошибки возвращают сообщение `error`. В API версии `2026-02-18.v1` и более поздних версиях тело ответа имеет формат JSON; в более ранних версиях, включая версию по умолчанию, которая используется, если не отправлен заголовок `gt-api-version`, сообщение возвращается как обычный текст. Это относится ко всем ошибкам, включая некорректный JSON (`400`), превышение допустимого размера тела запроса (`413`) и превышение лимита запросов (`429`).

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

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

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

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

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

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

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

## Справочные разделы

- /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.