# General Translation Platform: 移动文件
URL: https://generaltranslation.com/zh/docs/platform/openapi/reference/files/move-files.mdx
---

title: 移动文件
description: 在 General Translation 项目中移动或重命名文件。移动文件的 API 参考。

method: POST
---

通过在新的文件 ID 和名称下克隆每个源文件及其翻译内容来移动或重命名文件。每个要移动的文件提交一个条目。

## 概览 [#overview]

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

**权限** `project:files:write` · **速率限制** 中等 (120/分钟) 

在源文件重命名或移动后同步更新，且不丢失其翻译。要检测哪些文件已失效，请使用[获取孤立文件](/docs/platform/openapi/reference/files/orphaned-files)。

## 工作方式 [#how-it-works]

* 每次移动都会将现有源文件及其翻译克隆到 `newFileId` 和 `newFileName`，同时保留这些翻译。
* 如果缺少 `branchId`，则默认使用默认分支。提供的 `branchId` 必须属于该项目，否则请求会返回 `404`。
* 如果 `moves` 数组为空，则会返回空结果集，不会报错。
* 响应会返回每次移动的结果，以及移动总数、成功数和失败数的汇总统计。

## 请求 [#request]

### 请求头

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

### 请求体

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

| 字段                | 描述            | 类型         | 可选 | 默认值  |
| ----------------- | ------------- | ---------- | -- | ---- |
| [`moves`](#moves) | 要处理的文件移动对象数组。 | `object[]` | 否  | —    |
| `branchId`        | 文件所属的分支。      | `string`   | 是  | 默认分支 |

#### `moves` [#moves]

**类型** `object[]`

每个元素表示一次文件移动：

| 字段            | 描述            | 类型       | 可选 | 默认值 |
| ------------- | ------------- | -------- | -- | --- |
| `oldFileId`   | 当前文件标识符；不得为空。 | `string` | 否  | —   |
| `newFileId`   | 新文件标识符；不得为空。  | `string` | 否  | —   |
| `newFileName` | 新文件名；不得为空。    | `string` | 否  | —   |

## 响应 [#response]

**状态** `200 OK`

```json title="Response"
{
  "results": [
    {
      "oldFileId": "file_old...",
      "newFileId": "file_new...",
      "success": true,
      "newSourceFileId": "sf_...",
      "clonedTranslationsCount": 2
    }
  ],
  "summary": {
    "total": 1,
    "succeeded": 1,
    "failed": 0
  }
}
```

## 错误 [#errors]

| 状态    | 原因                                    |
| ----- | ------------------------------------- |
| `400` | 请求体无效。                                |
| `401` | 缺少 API 密钥，或 API 密钥 无效。              |
| `403` | API 密钥 不具备 `project:files:write` 权限。 |
| `404` | 在项目中找不到提供的 `branchId`。                |
| `429` | 已超出速率限制。                              |

## 示例 [#example]

```bash
curl -X POST https://api2.gtx.dev/v2/project/files/moves \
  -H "x-gt-api-key: gtx-api-..." \
  -H "Content-Type: application/json" \
  -d '{
    "moves": [
      {
        "oldFileId": "file_old...",
        "newFileId": "file_new...",
        "newFileName": "en/renamed.json"
      }
    ]
  }'
```