# General Translation Platform: uploadFonts
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/translation/upload-fonts.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 上传供 Lottie 翻译工作流长期使用的字体资源。uploadFonts 的 API 参考。

通过项目上传 TrueType 或 OpenType 字体，以便同一组织中的 Lottie 翻译任务在布局处理期间使用这些字体。

## 概述 [#overview]

调用 `uploadFonts` 时，最多可传入 10 个 Base64 编码的字体资源。该方法会返回已存储资源的内部标识符。如需上传更多字体，请分多次调用，每次最多 10 个。

```typescript
const result = await gt.uploadFonts(fonts, {
  timeout: 30000,
});
```

签名：

```typescript
uploadFonts(
  fonts: AssetUpload[],
  options?: UploadAssetsOptions
): Promise<UploadAssetsResponse>
```

*注意：`uploadFonts` 需要具备 `org:assets:write` 权限 (即仪表板中的 **Organization assets**) 的组织 API 密钥，可通过 `apiKey` 或已弃用的 `devApiKey` 别名传入，同时还需在 GT 实例上配置 `projectId`。使用项目 API 密钥会返回 403 错误。*

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

* 传给该方法的字体内容必须已进行 Base64 编码。
* 每个字体都必须具有 `.ttf` 或 `.otf` 文件名，且解码后大小不得超过 20MB。
* 项目决定字体归属的组织。上传的字体会在该组织的所有翻译任务中保留。
* 服务会从字体元数据中识别字体系列、字重和斜体样式；如果无法识别，则回退到文件名。再次上传具有相同派生字体标识的字体，会替换已存储的资源。
* API 每个请求最多接受 10 个字体，超出时会返回 400 错误并拒绝该请求。该方法仅在输入超过 50 个字体时才会将其拆分为多个请求，因此一次传入 11 个或更多字体的调用会失败。请将字体按每组最多 10 个分组，每组分别调用一次 `uploadFonts`。

(有关验证、字体标识和重试行为，请参阅[上传项目资源](/docs/platform/openapi/reference/organizations/upsert-assets)) 。

## 参数 [#parameters]

| 参数                    | 描述                | 类型                    | 可选 | 默认值  |
| --------------------- | ----------------- | --------------------- | -- | ---- |
| [`fonts`](#fonts)     | 要上传的 Base64 编码字体。 | `AssetUpload[]`       | 否  | —    |
| [`options`](#options) | 请求选项。             | `UploadAssetsOptions` | 是  | `{}` |

### `fonts` [#fonts]

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

| 字段          | 描述                        | 类型       | 可选 |
| ----------- | ------------------------- | -------- | -- |
| `assetType` | 资源类型。仅支持 `FONT`。          | `'FONT'` | 否  |
| `content`   | Base64 编码的字体字节数据。         | `string` | 否  |
| `fileName`  | 以 `.ttf` 或 `.otf` 结尾的文件名。 | `string` | 否  |

### `options` [#options]

**类型** `UploadAssetsOptions` · **可选** · **默认值** `{}`

| 字段        | 描述            | 类型       | 可选 |
| --------- | ------------- | -------- | -- |
| `timeout` | 请求超时时间，单位为毫秒。 | `number` | 是  |

## 返回值 [#returns]

**类型** `Promise<UploadAssetsResponse>`

解析后返回已存储的资源内部标识符和已处理的字体数量：

| 属性                  | 描述                                   | 类型                |
| ------------------- | ------------------------------------ | ----------------- |
| `assets`            | 已存储的字体资源。                            | `UploadedAsset[]` |
| `assets[].id`       | 已存储的组织资源 ID。                         | `string`          |
| `assets[].assetKey` | 派生的字体标识，格式为 `<family>-<weight>[-i]`。 | `string`          |
| `assets[].fileName` | 上传时提供的文件名。                           | `string`          |
| `count`             | 已处理的字体数量。                            | `number`          |

<Callout type="info">
  **v9.5.0 变更：**`UploadedAsset` 不再声明 `deduped` 字段，服务实际上从未返回过该字段。上传派生标识相同的字体会替换已存储的资源。 (参见[工作原理](#how-it-works)。) 
</Callout>

## 示例 [#example]

```typescript title="upload-fonts.ts"
import { readFile } from 'node:fs/promises';
import { GT } from 'generaltranslation';

// 具有 org:assets:write 权限的组织 API 密钥（gtx-org-）。
const gt = new GT({
  apiKey: process.env.GT_API_KEY,
  projectId: process.env.GT_PROJECT_ID,
});

const fileNames = ['BrandSans.ttf', 'BrandSans-Bold.ttf'];
const fonts = await Promise.all(
  fileNames.map(async (fileName) => ({
    assetType: 'FONT' as const,
    content: (await readFile(`./public/fonts/${fileName}`)).toString('base64'),
    fileName,
  }))
);

// 该 API 每次请求最多接受 10 个字体文件。
for (let i = 0; i < fonts.length; i += 10) {
  const result = await gt.uploadFonts(fonts.slice(i, i + 10));
  console.log(result.assets.map((asset) => asset.assetKey));
}
```

## Sitemap

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