# General Translation Platform: 概览
URL: https://generaltranslation.com/zh/docs/platform/openapi/overview.mdx
---

title: 概览
description: 了解如何使用公开的 General Translation API 端点和 OpenAPI 规范。

related:
  title: 参考部分
  links:
    - /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/project-info
---

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

SDK 和 CLI 会替你处理大多数 API 调用。需要从你自己的系统上传文件、排队翻译任务、下载译文、管理分支和标签，或查看项目和任务状态时，再直接调用 API。

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

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

### 基础 URL

* 项目和文件 端点 请使用 `https://api2.gtx.dev`。
* 运行时翻译 (包括 `POST /v2/translate`) 请使用 `https://runtime2.gtx.dev`。

### 身份验证

在 `x-gt-api-key` 请求头中发送你的 API Key。

```bash
curl https://api2.gtx.dev/v2/project/info/PROJECT_ID \
  -H "x-gt-api-key: gtx-api-..."
```

使用正确的密钥类型：

* **项目 (开发) **，前缀为 `gtx-dev-`：用于本地和预览环境，生产环境专用的 端点 不接受此类密钥
* **项目 (生产) **，前缀为 `gtx-api-`：绑定到单个项目
* **组织**，前缀为 `gtx-org-`：可跨项目使用。使用组织密钥调用项目层级的 端点 时，必须发送 `x-gt-project-id`。

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

### 权限

每个端点都要求 API Key 具有相应权限。组织密钥会显式配置权限，项目密钥则使用项目默认权限。

常见权限：

* `project:files:read`：用于下载文件，以及读取文件信息、翻译状态、分支信息、孤立文件、项目信息和作业信息。
* `project:files:write`：用于上传文件和翻译、差异、发布、创建分支和标签，以及移动文件。
* `project:translations:enqueue`：用于将文件加入翻译队列。
* `project:translations:generate`：用于运行时翻译。
* `project:context:read`：用于读取上下文生成状态。
* `project:context:write`：用于生成上下文。
* `project:write`：用于更新项目“设置”。

### 版本管理

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

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

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

### 速率限制

系统会在 60 秒时间窗口内，按 API 密钥或客户端 IP 对请求进行速率限制。不同端点的限制如下：

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

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

### 错误

错误响应会返回一条 `error` 消息。对于 API 版本 `2026-02-18.v1` 及之后的版本，响应体为 JSON；更早的版本 (包括未发送 `gt-api-version` 请求头时使用的默认版本) 则会以纯文本形式返回该消息。

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

常见状态码：

* `400` 表示请求体、查询参数或版本无效。
* `401` 表示缺少 API 密钥或其无效。
* `402` 表示超出 Organization 令牌配额 (`POST /v2/translate`) 。
* `403` 表示 API 密钥缺少 Permission，或当前套餐不允许执行该操作。
* `404` 表示找不到资源。
* `429` 表示超出速率限制。

## OpenAPI 规范 [#openapi-spec]

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

- /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/project-info