# 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` 请求头中提供 Bearer 凭据。端点参考文档会说明某个操作接受 API 密钥、OAuth 2.1 用户访问令牌，还是两者均可。

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

使用正确的密钥类型：

* **项目 (开发) **，前缀为 `gtx-dev-`：用于本地和预览环境，生产环境专用的 端点 不接受此类密钥
* **项目 (生产) **，前缀为 `gtx-api-`：绑定到单个项目
* **Organization**，前缀为 `gtx-org-`：可跨项目使用。大多数项目层级的 端点 都需要 `gt-project-id`。`GET /v2/project/info/{projectId}` 同样需要该请求头，并会检查两个 ID 是否匹配。`POST /v2/projects/{projectId}/api-keys` 则改用其路径参数。Organization 层级的端点 (例如 `POST /v2/orgs/{orgId}/projects`) 使用路径中的 Organization，并要求凭据具有对其的访问权限。

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

OAuth 应用使用带 Proof Key for Code Exchange (PKCE) 的授权码流程。请在 `https://dash.generaltranslation.com/.well-known/oauth-authorization-server/api/auth` 发现授权服务器，仅请求应用所需的层级，并在同一个 bearer 请求头中发送获得的用户访问令牌。该令牌同时受其被授予的层级以及用户当前对目标 Organization 或项目的访问权限的限制。

### Permission

每个端点都要求请求身份具有相应 Permission。Organization 密钥会显式配置 Permission。在仪表板中创建的项目密钥使用其密钥类型的默认 Permission；通过 Organization API 创建的密钥所拥有的 Permission 可能更少，因为它们仅限于请求身份可委派的范围。OAuth 用户访问令牌必须包含匹配的层级，且登录用户仍须持有该 Permission。

常见 Permission：

* `org:projects:create`：用于通过 `POST /v2/orgs/{orgId}/projects` 创建项目。
* `project:api_keys:write`：用于通过 `POST /v2/projects/{projectId}/api-keys` 创建项目 API 密钥。
* `project:files:read`：用于下载文件，以及读取文件信息、翻译状态、分支信息、孤立文件、项目信息和作业信息。
* `project:files:write`：用于上传文件、翻译和资源；提交差异；发布；创建分支和标签；以及移动文件。
* `project:translations:enqueue`：用于将文件加入翻译队列。
* `project:translations:generate`：用于运行时翻译。
* `project: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 秒时间窗口内，按 API 密钥或客户端 IP 对请求进行速率限制。不同端点的限制如下：

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

超出限制时会返回 `429`。Organization 令牌配额超限时，`POST /v2/translate` 会返回 `402`。

### 错误

已认证的应用程序错误会返回一条 `error` 消息。对于 API 版本 `2026-02-18.v1` 及之后的版本，响应体为 JSON；更早的版本 (包括未发送 `gt-api-version` 请求头时使用的默认版本) 则会以纯文本形式返回该消息。解析、payload 大小限制和速率限制失败时，可能会在认证前返回纯文本。

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

常见状态码：

* `400` 表示请求体、查询参数或版本无效。
* `401` 表示缺少 bearer 凭据或其无效。
* `402` 表示超出 Organization 令牌配额 (`POST /v2/translate`) 。
* `403` 表示请求身份缺少 Permission，或当前套餐不允许执行该操作。
* `404` 表示找不到资源。
* `413` 表示请求体超过端点限制。
* `425` 表示请求的翻译后的文件仍在处理中。
* `429` 表示超出速率限制。
* `500` 表示内部服务器错误。
* `503` 表示服务暂时不可用。

## OpenAPI 规范 [#openapi-spec]

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

JavaScript 工具还会附带用于生成其已安装 SDK 版本的 OpenAPI 快照。该内置快照可能与当前托管的契约有所差异：

* 在 `gt` 2.20.0 或更高版本中运行 [`npx gt api --spec`](/docs/cli/reference/commands/api)。
* 从 `generaltranslation` 9.2.0 或更高版本中导入 `generaltranslation/api/openapi.json`。
* 从独立生成的 SDK 中导入 `@generaltranslation/api/spec/openapi.json`。

如需带类型的 端点 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/translation/translate-runtime
- /docs/platform/openapi/reference/project/create-project

## Sitemap

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