# General Translation Platform: 创建分支
URL: https://generaltranslation.com/zh/docs/platform/openapi/reference/project/create-branch.mdx
---

title: 创建分支
description: 在 General Translation 项目中创建分支，或重命名并确认默认分支。用于“创建分支”的 API 参考。

method: POST
---

在项目中创建分支，或确认并重命名默认分支。返回生成分支的 ID 和名称。

## 概览 [#overview]

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

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

上传文件到某个分支前，请先创建该分支。要查询现有分支，请使用[获取分支信息](/docs/platform/openapi/reference/project/branch-info)。

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

* 当 `defaultBranch` 为 `true` 且默认分支已存在时，会返回现有的默认分支。如果提供的 `branchName` 不同，则会将该默认分支重命名为与其一致。
* 创建非默认分支需要付费套餐。在免费套餐下，请求创建非默认分支会返回 `403`。
* 否则，会创建该分支 (如果已存在则直接复用) ，并返回其 `id` 和 `name`。

## 请求 [#request]

### 请求头

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

### 请求体

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

| 字段              | 描述            | 类型        | 可选 | 默认值     |
| --------------- | ------------- | --------- | -- | ------- |
| `branchName`    | 分支名称；不能为空。    | `string`  | 否  | —       |
| `defaultBranch` | 将其设为该项目的默认分支。 | `boolean` | 是  | `false` |

## 响应 [#response]

**状态** `200 OK`

```json title="Response"
{
  "branch": { "id": "br_...", "name": "feature-x" }
}
```

## 错误 [#errors]

| 状态    | 原因                                               |
| ----- | ------------------------------------------------ |
| `400` | 请求体无效，或 `branchName` 为空。                         |
| `401` | 缺少 API 密钥，或 API 密钥无效。                            |
| `403` | API 密钥缺少 `project:files:write` 权限，或免费套餐不支持非默认分支。 |
| `429` | 已超过速率限制。                                         |

## 示例 [#example]

```bash
curl -X POST https://api2.gtx.dev/v2/project/branches/create \
  -H "x-gt-api-key: gtx-api-..." \
  -H "Content-Type: application/json" \
  -d '{
    "branchName": "feature-x"
  }'
```