# General Translation Platform: Загрузка исходных файлов
URL: https://generaltranslation.com/ru/docs/platform/openapi/reference/files/upload-source.mdx
---

title: Загрузка исходных файлов
description: Загрузите один или несколько исходных файлов в проект General Translation, прежде чем ставить перевод в очередь. Справочник API для загрузки исходных файлов.

method: POST
---

Загружает исходные файлы в проект, чтобы их можно было поставить в очередь на перевод. Передавайте содержимое файлов в формате base64: от 1 до 100 файлов в одном запросе.

## Обзор [#overview]

```http
POST https://api2.gtx.dev/v2/project/files/upload-files
```

**Разрешение** `project:files:write` · **Лимит запросов** Средний (120/min)

Загрузите исходные (непереведённые) файлы проекта. Чтобы загрузить уже переведённые файлы, используйте [Загрузка переводов](/docs/platform/openapi/reference/files/upload-translations). Чтобы затем перевести загруженные файлы, см. [Постановка переводов в очередь](/docs/platform/openapi/reference/translation/queue).

## Как это работает [#how-it-works]

* Поле `content` каждого файла кодируется в base64 и декодируется на сервере; недопустимый base64 отклоняется.
* Если `fileId` отсутствует, он вычисляется хешированием `fileName`; если отсутствует `versionId`, он вычисляется хешированием содержимого файла, поэтому повторная загрузка идентичного содержимого идемпотентна в пределах версии.
* Файлы привязываются к ветке по умолчанию, если не указан корректный `branchId`; неизвестный `branchId` возвращает `400`.
* Если передан `sourceLocale` и он отличается от текущей локали проекта по умолчанию, локаль проекта по умолчанию обновляется.

## Запрос [#request]

### Заголовки

| Заголовок         | Описание                                                     | Обязателен |
| ----------------- | ------------------------------------------------------------ | ---------- |
| `x-gt-api-key`    | API-ключ проекта или Organization.                           | Да         |
| `x-gt-project-id` | проект ID. Обязателен при использовании ключа Organization. | Нет        |

### Тело

**Тип содержимого** `application/json`

| Поле            | Описание                                | Тип        | Необязательное | По умолчанию                |
| --------------- | --------------------------------------- | ---------- | -------------- | --------------------------- |
| [`data`](#data) | Массив файлов для загрузки (1–100).     | `object[]` | Нет            | —                           |
| `sourceLocale`  | Исходная локаль для загружаемых файлов. | `string`   | Да             | локаль проекта по умолчанию |

#### `data` [#data]

**Тип** `object[]` · **Обязательно**

Каждый элемент имеет вид `{ "source": { ... } }`, где `source` содержит следующие поля:

| Поле             | Описание                                                                                       | Тип      | Необязательно | По умолчанию       |
| ---------------- | ---------------------------------------------------------------------------------------------- | -------- | ------------- | ------------------ |
| `content`        | Содержимое файла, закодированное в Base64. Действует ограничение на максимальный размер файла. | `string` | Нет           | —                  |
| `fileName`       | Имя файла; не может быть пустым.                                                               | `string` | Нет           | —                  |
| `fileFormat`     | Идентификатор формата файла (например, `JSON`, `MDX`).                                         | `string` | Нет           | —                  |
| `locale`         | Локаль исходного содержимого; не может быть пустой.                                            | `string` | Нет           | —                  |
| `dataFormat`     | Формат данных для структурированного содержимого.                                              | `string` | Да            | —                  |
| `fileId`         | Постоянный идентификатор файла.                                                                | `string` | Да            | Хеш `fileName`     |
| `versionId`      | Идентификатор версии этого содержимого.                                                        | `string` | Да            | Хеш содержимого    |
| `branchId`       | Ветка, к которой будет привязан файл.                                                          | `string` | Да            | Ветка по умолчанию |
| `formatMetadata` | Дополнительные метаданные для конкретного формата.                                             | `object` | Да            | —                  |

## Ответ [#response]

**Статус** `201 Created`

```json title="Response"
{
  "uploadedFiles": [
    {
      "branchId": "br_...",
      "fileId": "file_...",
      "versionId": "ver_...",
      "fileName": "en/common.json",
      "fileFormat": "JSON",
      "dataFormat": "JSON"
    }
  ],
  "count": 1,
  "message": "Successfully uploaded 1 source file(s)"
}
```

## Ошибки [#errors]

| Статус | Причина                                                                                                                       |
| ------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Недопустимое тело запроса, недопустимая локаль/формат, ошибка декодирования, слишком большой файл или неизвестный `branchId`. |
| `401`  | Отсутствует или недействителен API-ключ.                                                                                      |
| `403`  | У API-ключа нет разрешения `project:files:write`.                                                                             |
| `429`  | Превышен лимит запросов.                                                                                                      |
| `503`  | Сервер занят; повторите попытку с увеличивающейся задержкой.                                                                  |

## Пример [#example]

```bash
curl -X POST https://api2.gtx.dev/v2/project/files/upload-files \
  -H "x-gt-api-key: gtx-api-..." \
  -H "Content-Type: application/json" \
  -d '{
    "sourceLocale": "en",
    "data": [
      {
        "source": {
          "content": "eyJoZWxsbyI6ICJIZWxsbyJ9",
          "fileName": "en/common.json",
          "fileFormat": "JSON",
          "locale": "en"
        }
      }
    ]
  }'
```