# General Translation Platform: 生成上下文
URL: https://generaltranslation.com/zh/docs/platform/openapi/reference/context/generate-context.mdx
---

title: 生成上下文
description: 从源文件生成 General Translation 项目的词汇表术语和翻译说明。生成翻译上下文的 API 参考。

method: POST
---

将后台任务加入队列，根据你引用的源文件生成项目级翻译上下文——包括词汇表术语和翻译说明。你也可以选择为目标区域设置分别生成词汇表。

## 概览 [#overview]

```http
POST https://api2.gtx.dev/v2/project/setup/generate
```

**权限** `project:context:write` · **速率限制** 中等 (120/分钟) 

构建用于指导后续翻译的上下文。如需跟踪生成的任务，请使用[获取上下文生成状态](/docs/platform/openapi/reference/context/context-status)或[获取翻译任务状态](/docs/platform/openapi/reference/translation/job-status)。

## 工作原理 [#how-it-works]

* 与项目默认区域设置属于同一方言的目标区域设置会被忽略。
* 除非 `force` 为 `true`，否则如果项目已有上下文，且所请求的目标区域设置都不需要词汇表，就会跳过生成。在这种情况下，响应为 `{ "status": "completed" }`，且不会有作业入队。
* 否则，会将一个上下文生成作业加入队列，并返回其 ID 以及 `status: "queued"`。提供目标区域设置时，项目当前的区域设置也会一并更新。

## 请求 [#request]

### 请求头

| 请求头               | 说明                    | 必填 |
| ----------------- | --------------------- | -- |
| `x-gt-api-key`    | 项目或组织 API 密钥。         | 是  |
| `x-gt-project-id` | 项目 ID。使用组织 API 密钥时必填。 | 否  |

### 请求正文

**Content type** `application/json`

| 字段                | 描述                       | 类型         | 可选 | 默认值     |
| ----------------- | ------------------------ | ---------- | -- | ------- |
| [`files`](#files) | 用于生成上下文的源文件；不能为空。        | `object[]` | 否  | —       |
| `locales`         | 要为其生成按区域设置划分的词汇表的目标区域设置。 | `string[]` | 是  | —       |
| `force`           | 即使上下文已存在，也强制重新生成。        | `boolean`  | 是  | `false` |

#### `files` [#files]

**类型** `object[]` · **必填**

每个元素都引用一个源文件：

| 字段          | 描述             | 类型       | 可选 | 默认值 |
| ----------- | -------------- | -------- | -- | --- |
| `fileId`    | 稳定的文件标识符；不能为空。 | `string` | 否  | —   |
| `versionId` | 版本标识符；不能为空。    | `string` | 否  | —   |
| `branchId`  | 文件所属的分支。       | `string` | 是  | —   |

## 响应 [#response]

**状态** `200 OK`

```json title="Response"
{
  "setupJobId": "job_...",
  "status": "queued"
}
```

如果无需生成，则响应为：

```json title="Response"
{
  "status": "completed"
}
```

## 错误 [#errors]

| 状态    | 原因                                      |
| ----- | --------------------------------------- |
| `400` | 请求体无效、`files` 数组为空，或区域设置无效。             |
| `401` | 缺少 API Key，或 API Key 无效。                |
| `403` | API Key 不具备 `project:context:write` 权限。 |
| `429` | 超出速率限制。                                 |

## 示例 [#example]

```bash
curl -X POST https://api2.gtx.dev/v2/project/setup/generate \
  -H "x-gt-api-key: gtx-api-..." \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "fileId": "file_...",
        "versionId": "ver_..."
      }
    ],
    "locales": ["es", "fr"]
  }'
```