# 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-`：绑定到单个项目，可在任何环境中使用，受其 权限 限制
* **组织**，前缀为 `gtx-org-`：可在其绑定的 组织 内跨项目使用，受其 权限 限制

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

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

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

### 权限

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

常见 权限：

* `org:projects:create`：用于通过 `POST /v2/orgs/{orgId}/projects` 创建项目。
* `project:api_keys:read`：用于列出和读取项目 API 密钥。
* `project:api_keys:write`：用于通过 `POST /v2/projects/{projectId}/api-keys` 创建项目 API 密钥，以及删除项目 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:read`：用于读取分配给该项目的上下文组及其词汇表和自定义提示词，以及导出内容。
* `project:context:write`：用于生成上下文，编辑分配给该项目的上下文组的词汇表和自定义提示词，向这些分组导入内容，以及调整分组顺序。
* `org:context:read`：用于读取组织内所有上下文组及其词汇表和自定义提示词、项目分配情况以及导出内容。
* `org:context:write`：用于创建、更新和删除上下文组及其内容，导入内容，以及为项目分配组、取消分配组和调整组的顺序。
* `project:write`：用于更新项目设置。

对于读取或编辑分组内容的上下文管理端点，以及列出、读取项目所属分组或调整其顺序的端点，既可使用组织权限，也可使用该分组所分配项目的项目权限。列出组织的分组、创建、更新和删除分组，以及分配和取消分配分组，均需要组织权限。如果请求身份无权操作某个分组，返回的 `403` 与分组不存在时完全相同。

### 版本管理

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

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

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

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

### 请求体

请以 JSON 格式发送请求，并设置 `Content-Type: application/json`。你可以对请求体进行 gzip 压缩，并将 `Content-Encoding` 设置为 `gzip` 或 `x-gzip`。大小限制按解压后的请求体计算。如果编码后的请求体已超出该路由的限制，则会在解码前直接被拒绝。

### 写入响应

写入操作会返回其更改的内容，结构与读取同一资源时的返回结果相同。

* 使用 `POST` **创建**项目、分支、上下文分组 或项目 API 密钥时，返回 `201` 和新资源。新建的 API 密钥还会附带其密钥 `key`，此后的任何响应都不会再返回该值。
* 使用 `PATCH` **更新**单个资源时，返回 `200` 和更新后的资源。
* **`PUT`** 端点 (设置标签、分配 上下文分组 以及设置词汇表术语翻译) 会返回该资源：若资源由本次请求创建，状态码为 `201`；若资源已存在，则为 `200`。
* **删除**操作返回 `200` 和 `{ "deleted": true }`。

<Callout type="info">
  **`2026-10-08.v1` 中的变更：** Context Management 写入操作改为返回资源、`counts` 或 `deleted`，不再返回 `committed: true`。创建项目或项目 API 密钥时直接返回资源，不再使用 `project` 或 `apiKey` 包装层。运行时翻译改为以数组形式接收 `requests`，并返回 `summary` 和 `results`，不再返回以请求为键的对象。早期版本的响应保持不变；如需查看，请在 API 版本菜单中选择对应版本。
</Callout>

### 批处理请求

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

* **写入** (上传源文件和译文，移动、发布和覆盖文件，以及上传字体资源) 返回 `200`，并附带 `summary` (包含 `total`、`succeeded` 和 `failed` 计数) 和 `results`，即使所有条目均失败也是如此。失败的条目带有 `status: "failed"` 和 `error`；其余条目仍会正常应用。未通过校验的请求返回 `400`，且不会应用任何更改。
* **运行时翻译** (`POST /v2/projects/{projectId}/translate`) 接受数组形式的 `requests`，返回 `200`，并附带 `summary` 和 `results`。无法翻译的条目带有 `status: "failed"`，以及 `error` 和 `code`；其余条目仍会正常翻译。重复内容会在每个条目中分别翻译一次，因此每个字符串请只发送一次。
* **读取** (文件查询、文件内容查询和任务查询) 返回 `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 中的词汇表和自定义提示词更新或插入操作要么整批处理应用，要么全部不应用，并返回 `counts` (包含 `created`、`updated` 和 `unchanged`) 及 `items`：按请求顺序，每个条目对应一个 `id` 和 `outcome`。

### 运行时元数据限制

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

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

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

### 区域设置允许列表

如果项目的区域设置列表非空，且 `targetLocale` 不在列表中，运行时翻译会返回 `403`，错误代码为 `locale_not_allowed`。区域设置列表为空时，不限制目标语言区域。如果某个批处理请求完全由缓存响应，则会跳过此检查，因此即使某个区域设置已从项目中移除，仍可能返回该区域设置的缓存译文。

### 速率限制

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

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

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

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

列出项目、创建项目，以及列出、读取、创建和删除项目 API 密钥共用同一个限额。

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

### 分页

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

### 错误

自 API 版本 `2026-02-18.v1` 起，错误会返回 JSON 响应体，其中包含 `error` 消息和稳定的 `code`。这包括 JSON 格式错误 (`400`) 、请求体过大 (`413`) 以及触发速率限制 (`429`) 等情况。较早的版本大多以纯文本形式返回错误，且不含 `code`。

```json
{
  "error": "Missing required permission: project:files:write",
  "code": "permission_missing"
}
```

`code` 指明错误原因。路由可能返回比其状态对应的通用错误码更具体的错误码；每个端点的参考文档都列出了其可能返回的错误码。后续可能会新增错误码，因此遇到无法识别的错误码时，请按其 HTTP 状态码处理。

常见状态码及其对应的通用 `code`：

* `400` `invalid_request`：请求体、查询参数或版本无效。gzip 请求体损坏或被截断时返回 `invalid_content_encoding`。
* `401` `unauthenticated`：缺少 bearer 凭据或凭据无效。
* `402` `payment_required`：组织的计费账户被冻结，或其方案用量上限、每月支出上限或额度余额不足以支付该请求 (适用于翻译文件和运行时翻译) 。
* `403` `permission_denied`：请求身份缺少权限，或当前方案不允许该操作。缺少某项权限时返回 `permission_missing`，并在 `error` 中注明所缺权限。
* `404` `not_found`：未找到资源。
* `409` `conflict`：发生冲突，例如创建项目时超出组织的项目数量上限、分支名称已被占用，或重命名时与现有词汇表术语或自定义提示词重名。
* `410` `route_retired`：该路由在所请求的 API 版本中已停用。`error` 会注明应改用的路由。
* `413` `payload_too_large`：请求体超出端点限制，或 Context Management 响应将超过 1 MiB (请减小 `limit` 的值) 。
* `415` `unsupported_media_type`：请求体缺少 `Content-Type`，或其值不是 `application/json`。若 `Content-Encoding` 不受支持，则返回 `unsupported_content_encoding`。请求体请以未压缩或 gzip 编码的形式发送。
* `423` `locked`：资源已被正在进行的操作锁定。
* `425` `not_ready`：所请求的结果尚未就绪。
* `429` `rate_limited`：超出速率限制。
* `500` `internal_error`：服务器内部错误。
* `502` `upstream_error`：上游服务未能完成请求。
* `503` `unavailable`：服务暂时不可用。

收到 `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.
