# General Translation Platform: 下载文件
URL: https://generaltranslation.com/zh/docs/platform/openapi/reference/files/download-many.mdx
---

title: 下载文件
description: 通过一次请求从 General Translation 项目中下载多个翻译后的文件。下载文件的 API 参考。

method: POST
---

通过一次请求下载多个源文件或翻译后的文件。每个条目按 ID 选择一个文件，文件内容将以 base64 形式返回。

## 概览 [#overview]

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

**权限** `project:files:read` · **速率限制** 低 (300/分钟) 

一次获取多个文件。要下载单个文件，请使用[下载文件](/docs/platform/openapi/reference/files/download)。

## 工作原理 [#how-it-works]

* 发送 1 到 100 个文件引用。每个引用都会单独解析，成功的结果会一并返回。
* 不带 `locale` 的条目会返回源文件；带有 `locale` 的条目会返回对应的翻译文件。
* 缺少 `branchId` 时，会解析到默认分支。缺少 `versionId` 时，会使用该分支的头部版本，除非设置了 `useLatestAvailableVersion`。
* 文件内容会以 base64 编码形式在 `data` 字段中返回。`fileName` 仅存在于源文件中，`locale` 仅存在于翻译后的文件中。

## 请求 [#request]

### 请求头

| 请求头               | 描述                             | 必填 |
| ----------------- | ------------------------------ | -- |
| `x-gt-api-key`    | 项目或 Organization 的 API 密钥。     | 是  |
| `x-gt-project-id` | 项目 ID。使用 Organization 密钥时必须提供。 | 否  |

### 请求体

**内容类型** `application/json`

请求体是一个 JSON array，包含 1–100 个文件引用。每个元素包含以下字段：

| 字段                          | 描述                     | 类型        | 可选 | 默认值        |
| --------------------------- | ---------------------- | --------- | -- | ---------- |
| `fileId`                    | 稳定文件标识符；不可为空。          | `string`  | 否  | —          |
| `branchId`                  | 要读取的分支。                | `string`  | 是  | 默认分支       |
| `versionId`                 | 要下载的特定版本。              | `string`  | 是  | 分支 HEAD 版本 |
| `locale`                    | 要下载的区域设置。省略则下载源文件。     | `string`  | 是  | —          |
| `useLatestAvailableVersion` | 如果请求的版本不存在，则回退到最新可用版本。 | `boolean` | 是  | `false`    |

## 响应 [#response]

**状态** `200 OK`

```json title="Response"
{
  "files": [
    {
      "id": "sf_...",
      "branchId": "br_...",
      "fileId": "file_...",
      "versionId": "ver_...",
      "fileName": "en/common.json",
      "data": "eyJoZWxsbyI6ICJIZWxsbyJ9",
      "metadata": {},
      "fileFormat": "JSON"
    },
    {
      "id": "tf_...",
      "branchId": "br_...",
      "fileId": "file_...",
      "versionId": "ver_...",
      "locale": "es",
      "data": "eyJoZWxsbyI6ICJIb2xhIn0=",
      "metadata": {},
      "fileFormat": "JSON"
    }
  ],
  "count": 2
}
```

## 错误 [#errors]

| 状态    | 原因                                 |
| ----- | ---------------------------------- |
| `400` | 请求体无效，或某个条目缺少有效的 `fileId`。         |
| `401` | 缺少 API 密钥，或 API 密钥无效。              |
| `403` | API 密钥不具备 `project:files:read` 权限。 |
| `429` | 超出速率限制。                            |

## 示例 [#example]

```bash
curl -X POST https://api2.gtx.dev/v2/project/files/download \
  -H "x-gt-api-key: gtx-api-..." \
  -H "Content-Type: application/json" \
  -d '[
    { "fileId": "file_...", "locale": "es" },
    { "fileId": "file_..." }
  ]'
```