# General Translation Platform: API-клиент URL: https://generaltranslation.com/ru/docs/platform/core/reference/api-client.mdx Docs index: https://generaltranslation.com/llms.txt Description: Создание типизированного клиента для General Translation API и вызов сгенерированных вспомогательных функций эндпоинтов. Справочник API по createApiClient. Импортируйте TypeScript-клиент из `generaltranslation/api`, когда нужен контроль на уровне эндпоинтов без самостоятельного формирования HTTP-запросов. Модуль объединяет аутентифицированный транспорт с поддержкой версий и повторных попыток, сгенерированные вспомогательные функции эндпоинтов, а также подключаемые по желанию утилиты для пакетной обработки и опроса задач перевода. `generaltranslation/api` доступен в `generaltranslation` начиная с версии 9.2.0. Приведённые ниже примеры рассчитаны на `generaltranslation` 9.4.0 и эквивалентный автономный пакет `@generaltranslation/api` 0.3.0. Сгенерированные вспомогательные функции соответствуют снимку OpenAPI, который поставляется с установленным пакетом. Этот снимок может отличаться от текущего размещённого [публичного контракта OpenAPI](/docs/platform/openapi/overview), поэтому проверяйте по публичному справочнику, какие эндпоинты и форматы файлов доступны в данный момент. ## Обзор [#overview] | Экспорт | Описание | | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | [`createApiClient`](#create-client) | Создаёт аутентифицированный клиент с поддержкой версионирования, повторных попыток и тайм-аутов. | | [`ApiClientConfig`](#client-config) | Настраивает транспорт клиента и общие заголовки запросов. | | [`API_VERSION`](#api-version) | Текущая версия контракта API, отправляемая по умолчанию. | | [Вспомогательные функции эндпоинта](#endpoint-helpers) | Типизированные функции, сгенерированные для каждой операции во встроенном снимке OpenAPI. | | [`awaitJobs`](#job-polling) и [`pollJobs`](#job-polling) | Опрашивают задачи перевода до их завершения или истечения тайм-аута. | | [`processBatches`](#batch-processing) и [`DEFAULT_BATCH_SIZE`](#batch-processing) | Обрабатывают входной массив пакетами настраиваемого размера. | | [Сгенерированные типы](#types-errors) | Описывают данные эндпоинтов, ответы, ошибки и контракты клиента. | | [Встроенная спецификация OpenAPI](#openapi-spec) | JSON-снимок, на основе которого генерируется устанавливаемый пакет. | ## `createApiClient` [#create-client] ```ts function createApiClient(config: ApiClientConfig): Client; ``` Клиент добавляет к каждому запросу заданную версию API, Bearer-токен и ID проекта. Передайте его в сгенерированную вспомогательную функцию эндпоинта: ```ts title="project-info.ts" import { createApiClient, getProjectInfo } from 'generaltranslation/api'; const projectId = process.env.GT_PROJECT_ID!; const client = createApiClient({ apiKey: process.env.GT_API_KEY, baseUrl: 'https://api.gtx.dev', projectId, }); const result = await getProjectInfo({ client, path: { projectId }, }); if (result.error) { throw new Error('Could not load Project information'); } console.log(result.data); ``` В примерах ниже используется этот же настроенный `client`. ## `ApiClientConfig` [#client-config] | Option | Описание | Type | Optional | Default | | ----------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------- | -------- | ------------------ | | [`apiKey`](#apikey) | API Key или пользовательский токен доступа OAuth, передаваемый в заголовке `Authorization`. | `string` | Да | — | | [`apiVersion`](#apiversion) | Версия контракта, передаваемая в `gt-api-version`. | `ApiVersion` | Да | `API_VERSION` | | [`baseUrl`](#baseurl) | Базовый адрес API. | `string` | Нет | — | | [`fetch`](#fetch) | Пользовательская реализация Fetch API. | `typeof fetch` | Да | `globalThis.fetch` | | [`projectId`](#projectid) | ID проекта, передаваемый в `gt-project-id`. | `string` | Да | — | | [`retryPolicy`](#retrypolicy) | Стратегия задержки между повторными попытками. | `'exponential' \| 'linear' \| 'none'` | Да | `'exponential'` | | [`timeoutMs`](#timeoutms) | Тайм-аут на одну попытку или `false`, чтобы отключить встроенный тайм-аут. | `number \| false` | Да | `60000` | ### `apiKey` **Тип** `string` · **Необязательный** API key или пользовательский токен доступа OAuth 2.1, передаваемый в виде `Authorization: Bearer `. Клиент не читает переменные окружения автоматически. ### `apiVersion` **Type** `ApiVersion` · **Optional** · **Default** `API_VERSION` Версия контракта API, передаваемая в header `gt-api-version`. ### `baseUrl` **Тип** `string` · **Обязательно** Origin (базовый адрес) API. Для облачного General Translation API используйте `https://api.gtx.dev`. ### `fetch` **Type** `typeof fetch` · **Опционально** · **Default** `globalThis.fetch` Пользовательская реализация Fetch API. Используйте её для инструментирования, тестирования или в средах выполнения, где нет глобальной реализации fetch. ### `projectId` **Type** `string` · **Optional** ID проекта, передаваемый в заголовке `gt-project-id`. Организационным ключам и пользовательским токенам доступа OAuth этот заголовок необходим для эндпоинтов с областью проекта, которые не содержат ID проекта в пути. ### `retryPolicy` **Type** `'exponential' | 'linear' | 'none'` · **Optional** · **Default** `'exponential'` Идемпотентные запросы повторяются при сетевых ошибках, ответах `429` и `5xx` — до трёх раз. Неидемпотентные запросы повторяются только при ответах `429`, но не при сетевых ошибках или ответах `5xx`. Укажите `'none'`, если повторными попытками управляет вызывающая сторона. ### `timeoutMs` **Type** `number | false` · **Optional** · **Default** `60000` Тайм-аут в миллисекундах для каждой попытки запроса. Укажите `false`, если тайм-аутами запросов управляет собственная реализация `fetch`. ## `API_VERSION` [#api-version] **Тип** `ApiVersion` Текущая версия контракта по умолчанию — `2026-03-06.v1`. Если интеграция должна работать со старым контрактом ответа, передайте другую поддерживаемую версию в `apiVersion`. ## Вспомогательные функции эндпоинта [#endpoint-helpers] Сгенерированные вспомогательные функции эндпоинта принимают один объект с общим `client` и соответствующими полями эндпоинта: `body`, `headers`, `path` и `query`. По умолчанию они возвращают `{ data, error, request, response }`. ```ts title="project-info.ts" import { getProjectInfo } from 'generaltranslation/api'; const result = await getProjectInfo({ client, path: { projectId: 'your-project-id' }, throwOnError: true, }); console.log(result.data.name); ``` Обычно генерируются следующие параметры: | Option | Описание | Type | Optional | Default | | --------------- | ---------------------------------------------------------------------- | ------------------------- | -------- | ---------- | | `client` | Клиент, возвращаемый `createApiClient`. | `Client` | Нет | — | | `body` | Типизированное тело JSON-запроса. | Зависит от эндпоинта | Зависит | — | | `path` | Типизированные параметры пути. | Зависит от эндпоинта | Зависит | — | | `query` | Типизированные параметры строки запроса. | Зависит от эндпоинта | Зависит | — | | `headers` | Заголовки отдельного вызова, переопределяющие общие заголовки клиента. | Зависит от эндпоинта | Да | — | | `throwOnError` | Выбрасывать исключение при неуспешном ответе вместо возврата `error`. | `boolean` | Да | `false` | | `responseStyle` | Возвращать все поля ответа или только разобранные данные. | `'fields' \| 'data'` | Да | `'fields'` | | `signal` | Отмена запроса с помощью сигнала Fetch API. | `AbortSignal` | Да | — | | `meta` | Значения, доступные пользовательским интеграциям клиента. | `Record` | Да | — | Установленный SDK версии 0.3.0 предоставляет сгенерированные вспомогательные функции для следующих публичных операций: | Функция | Операция | | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | [`createProject`](/docs/platform/openapi/reference/project/create-project) | Создать проект в выбранной организации. | | [`createProjectApiKey`](/docs/platform/openapi/reference/project/create-api-key) | Создать API-ключ проекта с разрешениями, делегированными вызывающей стороной. | | [`uploadSourceFiles`](/docs/platform/openapi/reference/files/upload-source) | Загрузить исходные файлы. | | [`uploadTranslations`](/docs/platform/openapi/reference/files/upload-translations) | Загрузить переведённые файлы, связанные с существующими исходными файлами. | | `uploadAssets` | Загрузить ресурсы проекта. | | `submitUserEditDiffs` | Отправить локальные правки перевода. | | `generateProjectContext` | Сгенерировать контекст проекта. | | `enqueueFileTranslations` | Поставить загруженные файлы в очередь на перевод. | | `publishFiles` | Опубликовать файлы или снять их с публикации. | | [`downloadFile`](/docs/platform/openapi/reference/files/download) | Скачать один файл. | | `downloadFiles` | Скачать несколько файлов. | | `getBranchInfo` | Получить информацию о ветке. | | `createBranch` | Создать ветку. | | [`createTag`](/docs/platform/openapi/reference/project/upsert-tag) | Создать или обновить тег. | | `getProjectInfo` | Получить информацию о проекте. | | `updateProjectInfo` | Обновить информацию о проекте. | | `getTranslationJobInfo` | Получить статус задачи перевода. | | [`translate`](/docs/platform/openapi/reference/translation/translate-runtime) | Перевести контент во время выполнения. | | `getFileInfo` | Получить метаданные файла. | | `getTranslationStatus` | Получить статус перевода файла. | | `processFileMoves` | Переместить или переименовать файлы. | | `getOrphanedFiles` | Найти осиротевшие файлы. | **Изменено в v0.3.0:** `encodeBase64`, `decodeBase64`, `encodeFileContent` и `decodeFileContent` больше не экспортируются. Кодируйте содержимое файла перед передачей в сгенерированную вспомогательную функцию загрузки. **Изменено в v0.2.1:** [`createProject`](/docs/platform/openapi/reference/project/create-project) теперь требует `path.orgId` и обращается к `POST /v2/orgs/{orgId}/projects`. В этой версии также добавлена функция [`createProjectApiKey`](/docs/platform/openapi/reference/project/create-api-key) и удалены `shouldGenerateProjectContext` и `getProjectContextGenerationStatus`. Для задач по контексту используйте `generateProjectContext` вместе с `getTranslationJobInfo`. Вспомогательная функция [`downloadFile`](/docs/platform/openapi/reference/files/download) по-прежнему считается устаревшей; для скачивания как одного файла, так и нескольких используйте `downloadFiles`. Актуальные разрешения эндпоинтов, ограничения частоты запросов, схемы и коды статусов смотрите в [публичном справочнике OpenAPI](/docs/platform/openapi/overview). ## Опрос задач [#job-polling] [`awaitJobs`](#job-polling) с помощью настроенного клиента вызывает `getTranslationJobInfo` до тех пор, пока каждая запрошенная задача не будет завершена, не завершится с ошибкой, не окажется в неизвестном состоянии или не будет найдена, либо пока не истечёт общий тайм-аут. ```ts function awaitJobs( client: Client, jobIds: readonly string[], options?: AwaitJobsOptions ): Promise; ``` | Опция | Описание | Тип | Необязательно | По умолчанию | | ------------------------ | --------------------------------- | -------- | ------------- | ------------ | | `pollingIntervalSeconds` | Задержка между запросами статуса. | `number` | Да | `5` | | `timeoutSeconds` | Общий тайм-аут опроса. | `number` | Да | `600` | ```ts import { awaitJobs, enqueueFileTranslations, } from 'generaltranslation/api'; const result = await enqueueFileTranslations({ client, body: { files: [{ fileId: 'homepage', versionId: 'version-1' }], sourceLocale: 'en', targetLocales: ['es'], }, throwOnError: true, }); if (!('jobData' in result.data)) { throw new Error('Expected the current enqueue response'); } const jobs = await awaitJobs(client, Object.keys(result.data.jobData)); if (!jobs.complete) { console.warn('Translation jobs did not finish before the timeout'); } ``` `AwaitJobsResult` содержит поле `complete`, которое равно `false` только при истечении времени ожидания опроса, и поле `jobs` с последним результатом для каждого запрошенного идентификатора. Отсутствующая задача получает статус `unknown`. Передача пустого массива сразу разрешается значением `{ complete: true, jobs: [] }`. Ошибка API или загрузчика статусов до наступления общего дедлайна приводит к отклонению промиса опроса. Если запрос завершается неудачей уже после истечения дедлайна, опрос возвращает последние результаты с `complete: false`. `pollJobs` предоставляет тот же цикл опроса с внедряемым загрузчиком статусов: ```ts function pollJobs( jobIds: readonly string[], getJobStatuses: GetJobStatuses, options?: AwaitJobsOptions ): Promise; type GetJobStatuses = ( jobIds: string[], signal: AbortSignal ) => Promise; ``` Используйте этот вариант, когда требуется собственная нормализация запросов или ошибок. Загрузчик получает сигнал прерывания, ограниченный оставшимся общим дедлайном и лимитом в 60 секунд на один опрос. ## Пакетная обработка [#batch-processing] `processBatches` разбивает входной массив на части, вызывает ваш обработчик для каждой части и «схлопывает» возвращённые массивы в один в порядке следования пакетов. ```ts function processBatches( items: readonly TInput[], processBatch: (batch: TInput[]) => Promise, options?: BatchOptions ): Promise; ``` | Option | Описание | Type | Optional | Default | | ----------- | ------------------------------------------------------------------------- | --------- | -------- | -------------------- | | `batchSize` | Количество входных значений в каждом batch. Укажите значение больше нуля. | `number` | Да | `DEFAULT_BATCH_SIZE` | | `parallel` | Обрабатывать все batch параллельно, а не последовательно. | `boolean` | Да | `true` | `DEFAULT_BATCH_SIZE` равен `100`. Если обработчик batch завершается с ошибкой, `processBatches` тоже завершается с ошибкой. При параллельной обработке остальные уже запущенные batch продолжают выполняться независимо. ```ts import { Buffer } from 'node:buffer'; import { processBatches, uploadSourceFiles, } from 'generaltranslation/api'; // Сгенерированные вспомогательные функции эндпоинтов ожидают содержимое файла, закодированное для передачи. const content = Buffer.from('{"greeting":"Hello"}', 'utf8').toString('base64'); const files = [{ source: { content, fileName: 'en.json', fileFormat: 'JSON' as const, locale: 'en', }, }]; const results = await processBatches(files, async (batch) => { const result = await uploadSourceFiles({ client, body: { data: batch }, throwOnError: true, }); return result.data.uploadedFiles; }); ``` ## Типы и ошибки [#types-errors] Модуль экспортирует `Client`, `Options`, `ApiClientConfig`, `ApiVersion`, `RetryPolicy`, `AwaitJobsOptions`, `AwaitJobsResult`, `GetJobStatuses`, `JobResult`, `BatchOptions`, `RuntimeFileFormat`, а также сгенерированные типы OpenAPI для перечисленных выше публичных операций. Для каждой перечисленной выше публичной операции пакет экспортирует: * `Data` — типизированные входные данные: `body`, `headers`, `path` и `query`. * `Errors` — карту документированных ошибок по кодам состояния. * `Error` — объединение документированных ошибок. * `Responses` — карту документированных успешных ответов по кодам состояния. * `Response` — объединение документированных успешных ответов. При значении по умолчанию `throwOnError: false` сгенерированная операция возвращает либо `data`, либо `error`, а также `request` из Fetch API. Если получен HTTP-ответ, доступно поле `response`; если сбой произошёл до получения ответа, оно остаётся неопределённым. При `throwOnError: true` сбои API, сети, отмены и тайм-аута выбрасывают исключение. ## Спецификация OpenAPI [#openapi-spec] Импортируйте снимок, на основе которого сгенерирован установленный клиент: ```ts import openApiSpec from 'generaltranslation/api/openapi.json' with { type: 'json', }; ``` Автономный пакет `@generaltranslation/api` предоставляет тот же SDK и публикует свой снимок по адресу `@generaltranslation/api/spec/openapi.json`. Команда [`gt api --spec`](/docs/cli/reference/commands/api) выводит снимок, входящий в установленную зависимость Ядра для этого CLI. Актуальный размещённый контракт доступен по адресу [`/openapi.json`](/openapi.json). ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.