# 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`. ### Аутентификация Для каждого эндпоинта требуются bearer-учётные данные в стандартном заголовке `Authorization`. В справочнике по эндпоинтам указано, принимает ли операция API-ключ, пользовательский access-токен OAuth 2.1 или и то, и другое. ```bash curl https://api.gtx.dev/v2/project/info/PROJECT_ID \ -H "Authorization: Bearer gtx-api-..." ``` Используйте правильный тип ключа: * **Проект (development)** с префиксом `gtx-dev-`: для локального использования и предпросмотра; отклоняется эндпоинтами, доступными только в production * **Проект (production)** с префиксом `gtx-api-`: привязан к одному проекту * **Organization** с префиксом `gtx-org-`: работает в разных проектах. Большинство эндпоинтов с областью проекта требуют `gt-project-id`. `GET /v2/project/info/{projectId}` также требует этот заголовок и проверяет совпадение обоих идентификаторов. `POST /v2/projects/{projectId}/api-keys` вместо этого использует свой параметр пути. Эндпоинты с областью Organization, такие как `POST /v2/orgs/{orgId}/projects`, используют Organization из пути и требуют, чтобы credential имел к ней доступ. (См. [API-ключи](/docs/platform/dashboard/reference/api-keys), чтобы узнать, как создавать API-ключи и задавать для них область). OAuth-приложения используют flow Authorization Code с Proof Key for Code Exchange (PKCE). Обнаружить сервер авторизации можно по адресу `https://dash.generaltranslation.com/.well-known/oauth-authorization-server/api/auth`; запрашивайте только те области, которые нужны вашему приложению, и передавайте полученный пользовательский access-токен в том же bearer-заголовке. Токен ограничен как выданными ему областями, так и текущим доступом пользователя к целевой Organization или проекту. ### Разрешения Для каждого эндпоинта требуется соответствующее разрешение у идентичности запроса. Для ключей Organization разрешения настраиваются явно. Ключи проекта, созданные в Dashboard, используют значения по умолчанию для своего типа ключа; ключи, созданные через Organization API, могут иметь меньше разрешений, поскольку они ограничены теми, которые может делегировать идентичность запроса. Пользовательские access-токены OAuth должны включать соответствующую область, и у вошедшего пользователя всё равно должно быть это разрешение. Распространённые разрешения: * `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` для генерации контекста. * `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 разбивает документ на фрагменты, добавляет контекст запроса к каждому фрагменту и возвращает одну проверенную строку документа. Если фрагмент не удалось перевести или итоговый документ оказался некорректным, ошибку получает соответствующая запись, а частичный результат не возвращается. ### Лимиты запросов Частота запросов ограничивается по API-ключу или IP-адресу клиента в 60-секундном окне. Лимиты зависят от эндпоинта: * **Тяжёлые:** 30 запросов в минуту для постановки переводов в очередь. * **Средние:** 120 запросов в минуту для загрузок, диффов, контекста, перемещений, осиротевших файлов и публикации. * **Лёгкие:** 300 запросов в минуту для скачивания файлов. * **По умолчанию:** 200 запросов в минуту для создания проекта и API-ключей проекта, веток, тегов, информации о проекте, информации о задаче, информации о файле, статуса перевода и перевода во время выполнения. При превышении лимита возвращается `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` для отсутствующих или недопустимых bearer-учётных данных. * `402`, если превышена квота токенов Organization (`POST /v2/translate`). * `403`, если у идентичности запроса нет разрешения или действие недоступно в текущем тарифном плане. * `404`, если ресурс не найден. * `413`, если тело запроса превышает лимит эндпоинта. * `425`, если запрошенный переведённый файл всё ещё обрабатывается. * `429`, если превышен лимит запросов. * `500` для внутренней ошибки сервера. * `503`, если сервис временно недоступен. ## Спецификация OpenAPI [#openapi-spec] Машиночитаемая спецификация OpenAPI 3.1 доступна по адресу [`/openapi.json`](/openapi.json). Импортируйте её в Postman, Insomnia или OpenAPI-клиент, чтобы генерировать запросы и типы. Инструменты для JavaScript также поставляются со снимком OpenAPI, на основе которого сгенерирована установленная версия SDK. Такой встроенный снимок может отличаться от актуального размещённого контракта: * Выполните [`npx gt api --spec`](/docs/cli/reference/commands/api) с `gt` версии 2.20.0 или новее. * Импортируйте `generaltranslation/api/openapi.json` из `generaltranslation` версии 9.2.0 или новее. * Импортируйте `@generaltranslation/api/spec/openapi.json` из автономного сгенерированного SDK. Для типизированных вспомогательных функций эндпоинтов используйте [клиент `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/translation/translate-runtime - /docs/platform/openapi/reference/project/create-project ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.