# General Translation Platform: 上传源文件
URL: https://generaltranslation.com/zh/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/分钟) 

上传某个项目的源文件 (未翻译) 。若要上传已翻译的文件，请使用 [上传译文](/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 密钥。        | 是  |
| `x-gt-project-id` | 项目 ID。使用组织 API 密钥时必填。 | 否  |

### 请求体

**内容类型** `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 密钥，或 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"
        }
      }
    ]
  }'
```