# General Translation Platform: Обзор
URL: https://generaltranslation.com/ru/docs/platform/openapi/overview.mdx
---

title: Обзор
description: Узнайте, как использовать публичные эндпоинты API General Translation и спецификацию OpenAPI.

related:
  title: Справочные разделы
  links:
    - /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/project-info
---

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

SDK и CLI берут на себя большинство вызовов API. Обращайтесь к API напрямую, когда вам нужно загружать файлы, ставить задачи перевода в очередь, скачивать переводы, управлять ветвями и тегами или проверять статус Project и задач из своей системы.

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

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

### Базовые URL-адреса

* Используйте `https://api2.gtx.dev` для эндпоинтов проектов и файлов.
* Используйте `https://runtime2.gtx.dev` для перевода во время выполнения, включая `POST /v2/translate`.

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

Отправьте свой API-ключ в заголовке `x-gt-api-key`.

```bash
curl https://api2.gtx.dev/v2/project/info/PROJECT_ID \
  -H "x-gt-api-key: gtx-api-..."
```

Используйте правильный тип ключа:

* **Project (development)** с префиксом `gtx-dev-`: для локального использования и предпросмотра; отклоняется эндпоинтами, доступными только в production
* **Project (production)** с префиксом `gtx-api-`: привязан к одному Project
* **Organization** с префиксом `gtx-org-`: работает в разных Projects. При использовании ключа Organization на эндпоинтах с областью Project необходимо передавать `x-gt-project-id`.

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

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

Для каждого эндпоинта требуется соответствующее разрешение в API-ключе. Для ключей организации разрешения настраиваются явно. Ключи проекта используют разрешения Project по умолчанию.

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

* `project:files:read` для скачивания файлов, чтения сведений о файлах, статуса перевода, информации о ветке, осиротевших файлах, информации о Project и информации о задаче.
* `project:files:write` для загрузки файлов и переводов, диффов, публикации, создания веток и тегов, а также перемещения файлов.
* `project:translations:enqueue` для постановки файлов в очередь на перевод.
* `project:translations:generate` для перевода во время выполнения.
* `project:context:read` для чтения статуса генерации контекста.
* `project:context:write` для генерации контекста.
* `project:write` для обновления настроек Project.

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

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

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

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

### Ограничения частоты запросов

Частота запросов ограничивается по API-ключу или IP-адресу клиента в 60-секундном окне. Лимиты зависят от эндпоинта:

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

При превышении лимита возвращается `429`. При исчерпании квоты токенов Organization запрос `POST /v2/translate` возвращает `402`.

### Ошибки

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

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

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

* `400` для недопустимого тела запроса, параметров query или версии.
* `401` для отсутствующего или недопустимого API-ключа.
* `402`, если превышена квота токенов Organization (`POST /v2/translate`).
* `403`, если у API-ключа нет разрешения или действие недоступно в текущем тарифном плане.
* `404`, если ресурс не найден.
* `429`, если превышен лимит запросов.

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

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

- /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/project-info