# General Translation Platform: 概览
URL: https://generaltranslation.com/zh/docs/platform/openapi/overview.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 调用公开的 General Translation API 端点并下载 OpenAPI 规范。

使用 General Translation API 构建自定义自动化工作流。

CLI 会替你处理大多数 API 调用。使用 [`@generaltranslation/api` TypeScript 客户端](/docs/platform/core/reference/api-client) 获取生成的请求和响应类型，或在需要自定义自动化时直接调用端点。

OpenAPI 规范以机器可读的格式定义了这些端点。

## API 基础知识 [#api-basics]

### 基础 URL

包括通过 `POST /v2/projects/{projectId}/translate` 进行的运行时翻译在内，所有端点均以 `https://api.gtx.dev` 为基础 URL。

### 身份验证

在标准 `Authorization` 请求头中使用 API 密钥 进行身份验证。

```bash
curl https://api.gtx.dev/v2/projects/PROJECT_ID \
  -H "Authorization: Bearer gtx-api-..." \
  -H "gt-api-version: 2026-10-08.v1"
```

选择与你的工作流相匹配的密钥层级：

* **项目**，前缀为 `gtx-api-`：绑定到单个项目，可在任何环境中使用，受其 Permission 限制
* **Organization**，前缀为 `gtx-org-`：可在其绑定的 Organization 内跨项目使用，受其 Permission 限制

请求的作用对象由路径决定：`/v2/projects/{projectId}/...` 作用于该项目，`/v2/orgs/{orgId}/...` 作用于该 Organization，`/v2/context-groups/{groupId}/...` 则作用于该组所属的 Organization。发现端点 (`GET /v2/orgs` 和 `GET /v2/projects`) 无需提供 ID。密钥必须拥有所选项目或 Organization 的访问权限，因此项目密钥只能用于其自身所属的项目。

切勿将 API 密钥 打包进已部署的浏览器端和移动端 bundle 中。

(有关如何创建 API 密钥 以及设置其层级，请参阅 [API 密钥](/docs/platform/dashboard/reference/api-keys))。

### Permission

大多数端点都要求请求身份具有相应 Permission。[列出 Organization](/docs/platform/openapi/reference/organizations/list-orgs)、[列出项目](/docs/platform/openapi/reference/projects/list-projects)和[获取项目](/docs/platform/openapi/reference/projects/get-project)只需能够访问所返回的 Organization 或项目，无需其他资源 Permission。Organization 密钥和项目密钥在仪表板中均支持 **All** 或 **Custom** Permission，但仅限于创建者可授予的 Permission。通过[项目 API 密钥 端点](/docs/platform/openapi/reference/projects/create-project-api-key)，你可以选择 Permission；若不作选择，则会授予你可委派的所有项目 Permission。Write Permission 并不包含 Read Permission。项目密钥无法持有 Organization Permission (`org:*`) 或 `project:api_keys:write`，因此需要这些 Permission 的端点必须使用 Organization 密钥。

常见 Permission：

* `org:projects:create`：用于通过 `POST /v2/orgs/{orgId}/projects` 创建项目。
* `project:api_keys:write`：用于通过 `POST /v2/projects/{projectId}/api-keys` 创建项目 API 密钥。
* `org:assets:write`：用于通过 `POST /v2/orgs/{orgId}/assets` 上传字体。
* `project:files:read`：用于下载文件；读取文件元数据和状态；列出分支及分支文件；以及读取任务。
* `project:files:write`：用于上传源文件和译文；覆盖译文；发布；创建和更新分支；设置标签；以及移动文件。
* `project:translations:enqueue`：用于通过 `POST /v2/projects/{projectId}/files/translate` 翻译文件。
* `project:translations:generate`：用于运行时翻译。
* `project:context:write`：用于生成上下文。
* `org:context:read`：用于读取上下文分组及其词汇表和自定义提示词、项目分配情况以及导出内容。
* `org:context:write`：用于创建、更新和删除上下文分组及其内容，导入内容，以及为项目分配组、取消分配组和调整组的顺序。
* `project:write`：用于更新项目设置。

### 版本管理

每个请求都需携带 `gt-api-version` 请求头，用于指定所使用的 API 契约版本。

```bash
-H "gt-api-version: 2026-10-08.v1"
```

* 如果某个端点的参考页面将该请求头标记为必填，那么缺少该请求头或使用较旧版本时，该端点会返回 `400`。
* 其他端点在缺少该请求头时会使用所支持的最旧版本，并以纯文本 (而非 JSON) 格式返回错误。

如需查看旧版本的端点，请在任一 OpenAPI 页面顶部的 API 版本菜单中选择对应版本。

### 批量请求

以下批处理端点会按请求顺序，为每个条目各返回一个结果。

* **写入** (上传源文件和译文，移动、发布和覆盖文件，以及上传字体资源) 返回 `200`，并附带 `summary` (包含 `total`、`succeeded` 和 `failed` 计数) 和 `results`，即使所有条目均失败也是如此。失败的条目带有 `status: "failed"` 和 `error`；其余条目仍会正常应用。未通过校验的请求返回 `400`，且不会应用任何更改。
* **读取** (文件查询、文件内容查询和任务查询) 返回 `200`，并附带 `results`。项目中不存在的条目为 `not_found`。已存储但尚未完成的文件翻译 (例如处于布局处理阶段) 为 `pending`，请稍后重新请求。翻译任务尚未存储某条翻译时，该翻译为 `not_found`，因此请先通过 `GET /v2/projects/{projectId}/jobs/{jobId}` 或 `POST /v2/projects/{projectId}/jobs/query` 等待任务完成，再进行读取。未指定 `versionId` 时，读取会返回该分支上最新的已完成版本，仅当尚无任何已完成版本时才为 `pending`。任务查询会返回每个任务的状态。

其他批处理端点的响应各不相同：将文件翻译加入队列会返回 `202` 及所创建的 `jobs`；Context Management 中的词汇表和自定义提示词更新或插入操作要么整批应用，要么全部不应用，并返回 `committed` 及各条目的 `counts`。

### 运行时元数据限制

对于 `POST /v2/projects/{projectId}/translate`，若 `maxChars` 为正整数，则会在支持的翻译提示中加入长度约束说明，但并不能保证输出长度一定受限。非正数或带小数的数字会被忽略。类型错误的值会导致请求校验失败。

每个 `sourceCode` 文件最多保留五个上下文条目。API 会将每个条目的 `before` 和 `after` 字段截断至 2,000 个字符，`target` 字段截断至 500 个字符。

将 `fileFormat` 设置为 `MD` 或 `MDX`，即可翻译以字符串形式提供的整篇文档。文档请求必须使用 `dataFormat: STRING`，且不能包含 `maxChars` 或 `sourceCode`。API 会将文档解析为若干分块，为每个分块附加请求上下文，并返回一个经过校验的文档字符串。若某个分块失败或最终文档无效，则该条目判定为失败，而不会返回部分输出。

### 速率限制

速率限制分两层进行，均采用 60 秒时间窗口：

* **身份验证之前：**每个出示的凭据每分钟最多可尝试 600 次，身份验证失败的请求也计入其中。未携带凭据的请求不经过此层。超出限制时返回 `429`，并附带 `Retry-After: 60`，但不包含 `RateLimit-*` 响应头。
* **身份验证之后：**每个路由组按已验证的调用方 (例如 API 密钥) 限制请求数。对于受限路由，如果没有已验证的调用方，则按客户端 IP 进行限制。

身份验证后的限制因端点而异：

* **高负载：**每分钟 30 个请求，用于翻译文件。
* **中负载：**每分钟 120 个请求，用于上传源文件、译文和字体，覆盖译文，生成上下文，移动文件，列出分支文件，以及发布。
* **低负载：**每分钟 300 个请求，用于下载文件。
* **默认：**每分钟 200 个请求，用于项目和 Organization 发现、创建项目和项目 API 密钥、项目设置、分支、标签、任务、文件元数据和状态、运行时翻译和 Context Management。

列出项目、创建项目和创建项目 API 密钥共用同一个限额。

超出身份验证后的限制时返回 `429`，并附带 `RateLimit-*` 响应头。

### 分页

列表端点每次返回一页结果，格式为 `{ "items": [...], "nextCursor": ... }`。可通过 `limit` (1 到 100，默认为 50) 设置每页大小。若 `nextCursor` 为字符串，将其作为 `cursor` 传入即可获取下一页；若为 `null`，则表示没有更多结果。游标仅对生成它的列表及筛选条件有效。由于各页是独立读取的，在两次请求之间发生变化的条目可能会被遗漏或重复返回。

### 错误

设置 `gt-api-version` 后，错误会返回一个包含 `error` 消息的 JSON 响应体。这适用于所有错误，包括 JSON 格式错误 (`400`) 、请求体过大 (`413`) 和超出速率限制 (`429`) 。

```json
{
  "error": "API key is missing required permission: project:files:write"
}
```

常见状态码：

* `400` 表示请求体、查询参数或版本无效。
* `401` 表示缺少 bearer 凭据或其无效。
* `402` 表示 Organization 的计费账户被冻结，或其用量上限或额度余额不足以支付该请求 (翻译文件和运行时翻译) 。
* `403` 表示请求身份缺少 Permission，或当前套餐不允许执行该操作。
* `404` 表示找不到资源。
* `409` 表示发生冲突，例如创建项目时超出 Organization 的项目数量上限、分支名称已被使用，或重命名后与现有的词汇表术语或自定义提示词重名。
* `413` 表示请求体超过端点限制，或 Context Management 响应将超过 1 MiB (请在请求中使用更小的 `limit`) 。
* `415` 表示请求体的 `Content-Type` 缺失或不是 `application/json`。
* `429` 表示超出速率限制。
* `500` 表示内部服务器错误。
* `503` 表示服务暂时不可用。

收到 `429` 或 `503` 响应时，请稍候再重试。对于 `429`，请等待 `Retry-After` 响应头中指定的秒数后再重试。

## OpenAPI 规范 [#openapi-spec]

最新版本的机器可读 OpenAPI 3.1 规范见 [`/openapi.json`](/openapi.json)，各旧版本的规范见 `/openapi/<version>.json`。将其导入 Postman、Insomnia 或 OpenAPI 客户端，即可生成请求和类型。

如需带类型的 端点 helper，请使用 [`@generaltranslation/api` 客户端](/docs/platform/core/reference/api-client)。

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.