# api: Справочник API
URL: https://generaltranslation.com/ru/docs/api.mdx
---
title: Справочник API
description: Публичные эндпоинты API General Translation, аутентификация и спецификация OpenAPI
index: true
---

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

У каждого эндпоинта в этом разделе есть отдельная страница с параметрами, схемами и интерактивной средой для отправки запросов. Рядом с этими страницами также доступна машиночитаемая спецификация OpenAPI 3.1 в виде `openapi.yaml` — импортируйте её в Postman, Insomnia или OpenAPI-клиент, чтобы генерировать запросы и типы.

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

| API                                                | Базовый URL               |
| -------------------------------------------------- | ------------------------- |
| Эндпоинты проектов и файлов                        | `https://api.gtx.dev`     |
| Перевод во время выполнения (`POST /v2/translate`) | `https://runtime.gtx.dev` |

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

Аутентифицируйте каждый запрос, передавая API-ключ в заголовке `x-gt-api-key`.

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

| Тип ключа            | Префикс    | Заметки                                                                                       |
| -------------------- | ---------- | --------------------------------------------------------------------------------------------- |
| Проект (production)  | `gtx-api-` | Привязан к одному проекту                                                                     |
| Проект (development) | `gtx-dev-` | Для локальной работы и превью; отклоняется эндпоинтами только для production                  |
| Организация          | `gtx-org-` | Работает в разных проектах; на маршрутах проекта нужно передавать заголовок `x-gt-project-id` |

<Callout type="info">
  **Ключи организации:** При аутентификации с помощью ключа организации указывайте целевой проект в заголовке `x-gt-project-id` для любого эндпоинта проекта.
</Callout>

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

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

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

| Разрешение                      | Используется для                                                                                                                   |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `project:files:read`            | Скачивание файлов, сведений о файлах, статуса перевода, сведений о ветке, осиротевших файлов, сведений о проекте, сведений о задаче |
| `project:files:write`           | Загрузка файлов и переводов, различий, публикация, создание веток, создание тегов, перемещение                                     |
| `project:translations:enqueue`  | Постановка файлов в очередь на перевод                                                                                             |
| `project:translations:generate` | Перевод во время выполнения                                                                                                        |
| `project:context:read`          | Чтение статуса генерации контекста                                                                                                 |
| `project:context:write`         | Генерация контекста                                                                                                                |
| `project:write`                 | Обновление настроек проекта                                                                                                        |

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

Отправьте необязательный заголовок `gt-api-version`, чтобы закрепить формат ответа. Если его не указать, будет использоваться самая ранняя поддерживаемая версия. Последняя версия — `2026-03-06.v1`.

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

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

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

| Уровень | Лимит     | Эндпоинты                                                                                                                |
| ------- | --------- | ------------------------------------------------------------------------------------------------------------------------ |
| Heavy   | 20 / min  | Постановка переводов в очередь                                                                                           |
| Medium  | 60 / min  | Загрузка, диффы, контекст, перемещения, осиротевшие строки                                                               |
| Light   | 120 / min | Скачивание файлов                                                                                                        |
| Default | 200 / min | Публикация, ветки, теги, информация о проекте, информация о задаче, информация о файле, статус перевода, runtime-перевод |

При превышении лимита возвращается `429`. Квоты токенов организации также могут приводить к `429` для `POST /v2/translate`.

## Ошибки

При ошибке возвращается тело JSON с сообщением `error`:

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

| Статус | Значение                                                                           |
| ------ | ---------------------------------------------------------------------------------- |
| `400`  | Недопустимое тело запроса, параметры query или версия                              |
| `401`  | Отсутствует API-ключ или указан недопустимый API-ключ                              |
| `403`  | У API-ключа нет необходимого разрешения, или действие недоступно на текущем тарифе |
| `404`  | Ресурс не найден                                                                   |
| `429`  | Превышен лимит частоты запросов или квота токенов                                  |

## Следующие шаги

* [API-ключи](/docs/platform/api-keys) - Создание ключей и настройка области действия
* [Вебхуки](/docs/platform/webhooks) - Получение событий перевода
* [Поддерживаемые локали](/docs/platform/supported-locales) - Коды локалей, используемые в запросах