# General Translation Platform: 创建或更新标签
URL: https://generaltranslation.com/zh/docs/platform/openapi/reference/project/upsert-tag.mdx
---

title: 创建或更新标签
description: 在 General Translation 文件版本上创建或更新用于版本发布跟踪的标签。创建或更新标签的 API 参考。

method: POST
---

在一组文件版本上创建标签，或覆盖具有相同 ID 的现有标签。使用标签标记属于某个版本发布的文件版本。

## 概览 [#overview]

```http
POST https://api2.gtx.dev/v2/project/tags/create
```

**权限** `project:files:write` · **速率限制** 默认 (200/分钟) 

将命名标签固定到特定的文件版本上。如需先解析文件引用，请使用[获取文件信息](/docs/platform/openapi/reference/files/file-info)。

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

* 每个文件引用 (`fileId` + `versionId` + `branchId`) 都会解析到一个内部源文件。若已存在相同 `tagId` 的标签，则会被覆盖。
* 如果这些引用都无法解析到源文件，请求将返回 `400`。如果部分引用可以解析、部分不能，请求将返回 `400`，并列出未解析的文件 ID。
* 响应会返回已存储的标签，包括其时间戳。

## 请求 [#request]

### 请求头

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

### 请求体

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

| 字段                | 描述                     | 类型         | 可选 | 默认值 |
| ----------------- | ---------------------- | ---------- | -- | --- |
| `tagId`           | 标签标识符 (1–255 个字符) 。    | `string`   | 否  | —   |
| [`files`](#files) | 要打标签的文件版本；至少需要一个。      | `object[]` | 否  | —   |
| `message`         | 标签的可选消息 (最多 255 个字符) 。 | `string`   | 是  | —   |

#### `files` [#files]

**类型** `object[]` · **必填**

每个元素都引用一个文件版本。所有值均不能为空：

| Field       | Description | Type     | Optional | Default |
| ----------- | ----------- | -------- | -------- | ------- |
| `fileId`    | 稳定的文件标识符。   | `string` | 否        | —       |
| `versionId` | 版本标识符。      | `string` | 否        | —       |
| `branchId`  | 文件关联的分支。    | `string` | 否        | —       |

## 响应 [#response]

**状态** `200 OK`

```json title="Response"
{
  "tag": {
    "id": "tag_...",
    "tagId": "v1.2.0",
    "message": "Release 1.2.0",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
}
```

## 错误 [#errors]

| 状态    | 原因                                    |
| ----- | ------------------------------------- |
| `400` | 请求体无效、没有匹配的源文件，或某些文件引用无法解析。           |
| `401` | 缺少 API 密钥，或 API 密钥 无效。              |
| `403` | API 密钥 不具备 `project:files:write` 权限。 |
| `429` | 超出速率限制。                               |

## 示例 [#example]

```bash
curl -X POST https://api2.gtx.dev/v2/project/tags/create \
  -H "x-gt-api-key: gtx-api-..." \
  -H "Content-Type: application/json" \
  -d '{
    "tagId": "v1.2.0",
    "message": "Release 1.2.0",
    "files": [
      {
        "fileId": "file_...",
        "versionId": "ver_...",
        "branchId": "br_..."
      }
    ]
  }'
```