# 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/translate` 进行的运行时翻译在内，所有端点均以 `https://api.gtx.dev` 为基础 URL。

### 身份验证

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

```bash
curl https://api.gtx.dev/v2/project/info/PROJECT_ID \
  -H "Authorization: Bearer gtx-api-..."
```

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

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

对于路径中包含项目 ID 的项目层级端点，由该 ID 确定目标项目。可选的 `gt-project-id` 必须与之一致，否则请求将失败并返回 `403`。若路径中未指定目标，项目键会使用其绑定的项目；Organization 密钥则必须发送 `gt-project-id`。项目和 Organization 的发现操作无需指定目标项目。对于路径中指定了目标的 Organization 层级路由，将使用该 Organization；上下文分组路由 (`/v2/context-groups/{groupId}`) 则使用该组所属的 Organization。

旧版 API Key 请求头仍受支持，且优先级高于 bearer 请求头。切勿将 API Key 打包进已部署的浏览器端和移动端 bundle 中。

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

### Permission

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

常见 Permission：

* `org:projects:create`：用于通过 `POST /v2/orgs/{orgId}/projects` 创建项目。
* `project:api_keys:write`：用于通过 `POST /v2/projects/{projectId}/api-keys` 创建项目 API Key。
* `project:files:read`：用于下载文件，以及读取文件信息、翻译状态、分支信息、孤立文件和作业信息。
* `project:files:write`：用于上传文件、翻译和资源；提交差异；发布；创建分支和标签；以及移动文件。
* `project:translations:enqueue`：用于将文件加入翻译队列。
* `project:translations:generate`：用于运行时翻译。
* `project:context:write`：用于生成上下文。
* `org:context:read`：用于读取上下文分组及其词汇表和自定义提示词、项目分配情况以及导出内容。
* `org:context:write`：用于创建、更新和删除上下文分组及其内容，导入内容，以及为项目分配组、取消分配组和调整组的顺序。
* `project:write`：用于更新项目设置。

### 版本管理

发送可选的 `gt-api-version` 请求头，以固定响应格式。

```bash
-H "gt-api-version: 2026-03-06.v1"
```

如果省略该 请求头，将使用支持的最早版本。最新版本为 `2026-03-06.v1`。

### 运行时元数据限制

对于 `POST /v2/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 Key) 限制请求数。对于受限路由，如果没有已验证的调用方，则按客户端 IP 进行限制。

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

* **高负载：**每分钟 30 个请求，用于将翻译加入队列。
* **中负载：**每分钟 120 个请求，用于上传、差异、上下文生成、移动、孤立文件和发布。
* **低负载：**每分钟 300 个请求，用于下载文件。
* **默认：**每分钟 200 个请求，用于项目和 Organization 发现、创建项目和项目 API Key、分支、标签、项目信息、作业信息、文件信息、翻译状态、运行时翻译和 Context Management。

项目和 Organization 发现与项目/密钥创建共用同一个请求限额。

超出身份验证后的限制时返回 `429`，并附带 `RateLimit-*` 响应头。Organization 令牌配额超限时，`POST /v2/translate` 会返回 `402`。

### 分页

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

### 错误

错误会返回一条 `error` 消息。对于 API 版本 `2026-02-18.v1` 及之后的版本，响应体为 JSON；更早的版本 (包括未发送 `gt-api-version` 请求头时使用的默认版本) 则会以纯文本形式返回该消息。这适用于所有错误，包括 JSON 格式错误 (`400`) 、请求体过大 (`413`) 和超出速率限制 (`429`) 。

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

常见状态码：

* `400` 表示请求体、查询参数或版本无效。
* `401` 表示缺少 bearer 凭据或其无效。
* `402` 表示超出 Organization 令牌配额 (`POST /v2/translate`) 。
* `403` 表示请求身份缺少 Permission，或当前套餐不允许执行该操作。
* `404` 表示找不到资源。
* `409` 表示发生冲突，例如创建项目时超出 Organization 的项目数量上限，或重命名后与现有的词汇表术语或自定义提示词重名。
* `413` 表示请求体超过端点限制，或 Context Management 响应将超过 1 MiB (请在请求中使用更小的 `limit`) 。
* `425` 表示请求的翻译后的文件仍在处理中。
* `429` 表示超出速率限制。
* `500` 表示内部服务器错误。
* `503` 表示服务暂时不可用。

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

## OpenAPI 规范 [#openapi-spec]

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

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

## 参考部分

- /docs/platform/core/reference/api-client
- /docs/platform/openapi/reference/files/upload-source
- /docs/platform/openapi/reference/context/generate-context
- /docs/platform/openapi/reference/context-management/list-groups
- /docs/platform/openapi/reference/translation/translate-runtime
- /docs/platform/openapi/reference/project/create-project

## Sitemap

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