> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 预设

> 可复用的渲染配置——创建、更新、列出并设置账户默认值

预设（preset）是一种可复用的渲染配置——背景、字幕样式、布局——你可以将其应用到任何项目或导出。当你需要在多条音轨之间保持一致的视觉风格时，使用预设。

完整的 `preset` 结构以及所有由枚举支持的选项，请参见 [渲染设置参考](/en/render-settings-reference)。

## 何时使用预设

<Columns cols={2}>
  <Card title="在以下情况使用预设…" icon="check">
    你希望在多个项目中保持相同风格，并且需要在一个地方统一更新。
  </Card>

  <Card title="在以下情况使用项目设置…" icon="sliders" href="/zh/api/project-settings">
    你需要仅限某个项目的覆盖配置，但这些配置不值得共享。
  </Card>
</Columns>

## 端点

| Method   | Path                  | Purpose          |
| -------- | --------------------- | ---------------- |
| `GET`    | `/presets`            | 列出已认证账户的预设。      |
| `POST`   | `/presets`            | 创建一个新的预设。        |
| `GET`    | `/presets/{presetId}` | 获取单个预设。          |
| `PATCH`  | `/presets/{presetId}` | 更新名称、内容，或设置为默认值。 |
| `DELETE` | `/presets/{presetId}` | 删除一个预设。          |

完整的请求与响应 schema 可在侧边栏 **API reference** 下查看。

## 创建预设

```bash theme={null}
curl -X POST https://api.youka.io/zh/api/v1/presets \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: create-neon-night-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Neon Night",
    "preset": {
      "background": {
        "type": "gradient",
        "colors": ["#12001f", "#2f0a57"],
        "angle": 90
      },
      "singerTextStyles": {
        "0": {
          "fontFamily": "Inter",
          "textColor": "#00f5ff",
          "effectColor": "#ff4fd8"
        }
      }
    },
    "isDefault": false
  }'
```

响应会包含新的 `presetId`。请保存它，并在项目或导出中引用。

<Tip>
  为每个 `POST` 配对一个幂等键。对同一 payload 重复使用相同的键会返回原始预设，而不是创建重复项。
</Tip>

## 发现有效的预设字段

预设会在服务端根据 `KaraokePresetSchema` 进行校验。SDK 导出该 schema，因此你可以在运行时将其转换为 JSON Schema：

```ts theme={null}
import { KaraokePresetSchema } from "@youka/sdk";

const jsonSchema = KaraokePresetSchema.toJSONSchema();
```

使用 CLI：

```bash theme={null}
youka preset schema --json
```

Agent 作者在修改预设之前应先调用此命令/接口，这样模型才能了解所有有效字段以及取值类型。

可读性更强的参考：

* [渲染设置参考](/en/render-settings-reference)
* [CLI 预设](/zh/cli/presets)
* [SDK 预设](/zh/sdk/presets)

## 更新预设

```bash theme={null}
curl -X PATCH https://api.youka.io/zh/api/v1/presets/preset_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Neon Night v2",
    "preset": {
      "singerTextStyles": {
        "0": {
          "textColor": "#ff2a2a"
        }
      }
    }
  }'
```

传入 `name` 与 `preset` 的任意子集即可。未包含的字段将保持不变。

## 设置默认预设

每个账户最多只有一个默认预设，会自动应用到新项目。

```bash theme={null}
curl -X PATCH https://api.youka.io/zh/api/v1/presets/preset_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "isDefault": true
  }'
```

设置新的默认值会自动取消之前的默认预设。

## 应用预设

你可以在三个位置引用预设：

| Where    | Field                                                |
| -------- | ---------------------------------------------------- |
| 创建项目时    | `POST /projects` 中的 `presetId`                       |
| 项目中的任意时刻 | `PATCH /projects/{projectId}/settings` 中的 `presetId` |
| 导出时      | `POST /projects/{projectId}/exports` 中的 `presetId`   |

导出示例：

```bash theme={null}
curl -X POST https://api.youka.io/zh/api/v1/projects/prj_abc/exports \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "presetId": "preset_abc123",
    "resolution": "1080p",
    "quality": "high"
  }'
```

## 删除预设

```bash theme={null}
curl -X DELETE https://api.youka.io/zh/api/v1/presets/preset_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: delete-preset_abc123"
```

<Warning>
  删除预设不会影响之前使用该预设渲染的项目或导出。未来引用已删除预设的导出将会失败。
</Warning>

## 下一步

* [渲染设置参考](/en/render-settings-reference) — 所有共享字段路径与枚举值
* [媒体](/zh/api/media) — 会在预设内容中被引用
* [项目设置](/zh/api/project-settings) — 将预设应用到项目
* [CLI 预设](/zh/cli/presets) — 在终端中完成同样的流程
* [SDK 预设](/zh/sdk/presets) — 在 TypeScript 中使用同样的端点