# api: API 参考 URL: https://generaltranslation.com/zh/docs/api.mdx --- title: API 参考 description: 公开的 General Translation API 端点、身份验证和 OpenAPI 规范 index: true --- General Translation API 让您能够上传源内容和翻译后的文件、下载翻译、翻译内容并加入队列、管理 分支 和 标签，以及查询项目和 任务 状态。大多数 SDK 和 CLI 工作流都会替您调用这些端点，但您也可以直接调用它们来实现自定义自动化。 本节中的每个端点都有各自的页面，包含参数、模式和交互式请求面板。除此之外，还附带一份机器可读的 OpenAPI 3.1 规范，文件名为 `openapi.yaml`——将其导入 Postman、Insomnia 或 OpenAPI 客户端中，即可生成请求和类型。 ## 基础 URL | API | 基础 URL | | ---------------------------- | ------------------------- | | 项目和文件接口 | `https://api.gtx.dev` | | 运行时翻译 (`POST /v2/translate`) | `https://runtime.gtx.dev` | ## 身份验证 在 `x-gt-api-key` 请求头中附带 API 密钥，对每个请求进行身份验证。 ```bash curl https://api.gtx.dev/v2/project/info/PROJECT_ID \ -H "x-gt-api-key: gtx-api-..." ``` | 密钥类型 | 前缀 | 说明 | | ---------------- | ---------- | ----------------------------------------- | | 项目 (Production) | `gtx-api-` | 绑定到单个项目 | | 项目 (开发环境) | `gtx-dev-` | 用于本地和预览环境；仅限 Production 的端点会拒绝此类密钥 | | 组织 | `gtx-org-` | 可跨项目使用；在项目层级路由上必须传送 `x-gt-project-id` 请求头 | **组织密钥：**使用组织密钥进行身份验证时，对于任何项目层级的 端点，都需要在 `x-gt-project-id` 请求头中指定目标项目。 有关如何创建密钥及设置其层级，请参阅 [API 密钥](/docs/platform/api-keys)。 ## 权限 每个端点都要求 API 密钥 具备相应权限。Organization keys 需要显式配置这些权限；project keys 则使用项目默认权限。 | 权限 | 用于 | | ------------------------------- | ---------------------------------- | | `project:files:read` | 下载文件、文件信息、翻译状态、分支信息、孤立文件、项目信息、任务信息 | | `project:files:write` | 上传文件和翻译、diff、发布、创建分支、创建标签、移动 | | `project:translations:enqueue` | 将文件加入翻译队列 | | `project:translations:generate` | 运行时翻译 | | `project:context:read` | 读取上下文生成状态 | | `project:context:write` | 生成上下文 | | `project:write` | 更新项目“设置” | ## 版本控制 发送可选的 `gt-api-version` 请求头以锁定响应格式。若省略，则使用当前受支持的最早版本。最新版本是 `2026-03-06.v1`。 ```bash -H "gt-api-version: 2026-03-06.v1" ``` ## 速率限制 请求会在 60 秒时间窗口内按每个 API 密钥 (或客户端 IP) 进行速率限制。不同接口的限制如下： | Tier | Limit | Endpoints | | ------- | --------- | ---------------------------------- | | Heavy | 20 / min | 翻译排队 | | Medium | 60 / min | 上传、差异、上下文、移动、孤立项 | | Light | 120 / min | 下载文件 | | Default | 200 / min | 发布、分支、标签、项目信息、任务信息、文件信息、翻译状态、运行时翻译 | 超过限制时会返回 `429`。Organization 令牌配额也可能导致 `POST /v2/translate` 返回 `429`。 ## 错误 出错时会返回一个包含 `error` 消息的 JSON 响应体： ```json { "error": "API key is missing required permission: project:files:write" } ``` | 状态 | 含义 | | ----- | ---------------------------- | | `400` | 请求体、查询参数或版本无效 | | `401` | 缺少 API 密钥，或 API 密钥 无效 | | `403` | API 密钥 缺少所需权限，或当前套餐不允许执行此操作 | | `404` | 资源未找到 | | `429` | 超出速率限制或令牌配额 | ## 后续步骤 * [API 密钥](/docs/platform/api-keys) - 创建密钥并设置其范围 * [Webhooks](/docs/platform/webhooks) - 接收翻译事件 * [支持的区域设置](/docs/platform/supported-locales) - 请求中使用的区域设置代码