# General Translation Platform: 上传项目资源
URL: https://generaltranslation.com/zh/docs/platform/openapi/reference/project/upload-assets.mdx
---

title: 上传项目资源
description: 在 Organization 中为 General Translation Lottie 工作流上传字体资源。上传项目资源的 API 参考。

method: POST

---

通过项目上传 OpenType 或 TrueType 字体，使其可供所属 Organization 中的 Lottie 翻译工作流使用。

## 概览 [#overview]

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

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

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

* 每个请求可包含 1 至 50 个字体。
* 每个字体必须是有效的 base64 数据，文件名必须使用 `.ttf` 或 `.otf` 扩展名，且解码后不得超过 20MB。
* 项目决定资源归属的 Organization。上传的字体会在该 Organization 的翻译任务之间持续保留。
* 每个字体均以由字体系列、字重和斜体样式组成的标准化标识作为键。服务器端使用提供的 `family` 和 `style`，或从字体元数据中推导；若无法获取，再从文件名中推导。
* 即使字节内容或文件名发生变化，重复上传相同的字体标识也会覆盖现有资源。
* 重试前请修正 `400` 输入错误。收到 `500` 响应后，可以安全地完整重试，因为每个字体标识都会执行 upsert 操作。

## 请求 [#request]

### 请求头

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

### 请求体

**内容类型** `application/json`

| 字段                  | 描述                  | 类型         | 可选 | 默认值 |
| ------------------- | ------------------- | ---------- | -- | --- |
| [`assets`](#assets) | 要上传的字体资源 (1–50 个) 。 | `object[]` | 否  | —   |

#### `assets`

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

| 字段          | 描述                                                                       | 类型       | 可选 | 默认值                            |
| ----------- | ------------------------------------------------------------------------ | -------- | -- | ------------------------------ |
| `assetType` | 资源类型。仅支持 `FONT`。                                                         | `'FONT'` | 否  | —                              |
| `content`   | Base64 编码的字体内容，解码后最大为 20MB。                                              | `string` | 否  | —                              |
| `fileName`  | 以 `.ttf` 或 `.otf` 结尾的字体文件名 (1–255 个字符) 。                                 | `string` | 否  | —                              |
| `family`    | Lottie 文件使用的字体系列名称。省略时，服务器端会根据字体或文件名自动推导。                                | `string` | 是  | 自动推导                           |
| `style`     | 与 `family` 配合使用的样式或字重，例如 `Bold`、`350` 或 `Bold Italic`。省略 `family` 时将被忽略。 | `string` | 是  | 设置 `family` 时为 Regular (`400`) |

## 响应 [#response]

**状态** `201 Created`

| 字段                  | 描述                                   | 类型         |
| ------------------- | ------------------------------------ | ---------- |
| `assets`            | 已上传的字体资源。                            | `object[]` |
| `assets[].id`       | 已存储的 Organization 资源 ID。                | `string`   |
| `assets[].assetKey` | 采用 `<family>-<weight>[-i]` 格式的标准化标识。 | `string`   |
| `assets[].fileName` | 请求中的文件名。                             | `string`   |
| `count`             | 已上传资源的数量。                            | `number`   |

```json title="Response"
{
  "assets": [
    {
      "id": "asset_...",
      "assetKey": "brandsans-700",
      "fileName": "BrandSans.ttf"
    }
  ],
  "count": 1
}
```

## 错误 [#errors]

| 状态    | 原因                                                                                                |
| ----- | ------------------------------------------------------------------------------------------------- |
| `400` | 请求体无效、base64 无效、资源为空、文件扩展名不受支持、资源大小超过 20MB，或无法确定字体系列。无法推导标识时请提供 `family`；`style` 仍为可选，默认值为 `400`。 |
| `401` | API 密钥缺失或无效。                                                                                      |
| `403` | API 密钥不具备 `project:files:write` 权限。                                                               |
| `404` | 未找到项目。                                                                                            |
| `413` | JSON 请求体超过 100MB。                                                                                 |
| `429` | 超出速率限制。                                                                                           |
| `500` | 无法存储资源。请重新发送完整请求。                                                                                 |

## 示例 [#example]

```bash
FONT_BASE64=$(base64 < ./BrandSans.ttf | tr -d '\n')

curl -X POST https://api2.gtx.dev/v2/project/assets \
  -H "x-gt-api-key: gtx-api-..." \
  -H "Content-Type: application/json" \
  -d "{
    \"assets\": [
      {
        \"assetType\": \"FONT\",
        \"content\": \"$FONT_BASE64\",
        \"fileName\": \"BrandSans.ttf\",
        \"family\": \"Brand Sans\",
        \"style\": \"Bold\"
      }
    ]
  }"
```