> ## 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.

# 预设

> 在 SDK 中管理可复用的渲染配置

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

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

## `client.presets.list(options?)`

列出已认证账号拥有的所有预设。

```ts theme={null}
const presets = await client.presets.list();
presets.forEach((p) => console.log(p.id, p.name, p.isDefault));
```

## `client.presets.get(presetId, options?)`

获取单个预设。

```ts theme={null}
const preset = await client.presets.get("preset_abc123");
```

## `client.presets.create(body, options?)`

创建一个新的预设。

```ts theme={null}
const preset = await client.presets.create({
  name: "Neon Night",
  preset: {
    background: {
      type: "gradient",
      colors: ["#12001f", "#2f0a57"],
      angle: 90,
    },
    singerTextStyles: {
      0: {
        fontFamily: "Inter",
        textColor: "#00f5ff",
        effectColor: "#ff4fd8",
      },
    },
  },
  isDefault: false,
});
```

<ParamField path="name" type="string" required>
  在 Youka UI 中显示的名称。
</ParamField>

<ParamField path="preset" type="KaraokePreset" required>
  完整的预设内容。可使用 [`渲染设置
      参考`](/en/render-settings-reference) 查看便于阅读的字段映射，或使用 `KaraokePresetSchema.toJSONSchema()` 获取机器可读的 schema。
</ParamField>

<ParamField path="isDefault" type="boolean">
  将新预设标记为账号默认值。同一时间只能有一个预设作为默认值。
</ParamField>

配合幂等键以安全重试：

```ts theme={null}
const preset = await client.presets.create(body, {
  idempotencyKey: "create-neon-night-v1",
});
```

## `client.presets.update(presetId, body, options?)`

对现有预设进行补丁更新。可传入 `name`、`preset`、`isDefault` 的任意子集。

```ts theme={null}
const updated = await client.presets.update("preset_abc123", {
  name: "Neon Night v2",
  preset: {
    singerTextStyles: {
      0: { textColor: "#ff2a2a" },
    },
  },
});
```

## `client.presets.delete(presetId, options?)`

删除一个预设。

```ts theme={null}
await client.presets.delete("preset_abc123", {
  idempotencyKey: "delete-preset_abc123",
});
```

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

## `client.presets.setDefault(presetId, options?)`

将某个预设标记为新项目的默认预设。这是对 `client.presets.update(presetId, { isDefault: true })` 的便捷封装。

```ts theme={null}
await client.presets.setDefault("preset_abc123");
```

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

## 发现有效字段

SDK 导出了用于校验预设内容的 Zod schema。你可以在运行时将其转换为 JSON Schema，供智能体与表单构建器使用：

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

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

<Tip>
  智能体作者：在修改预设之前先调用该 schema，让模型了解精确的字段名称与取值类型。
</Tip>

便于阅读的参考：

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

## 应用预设

可在三个节点应用预设：

<Tabs>
  <Tab title="在创建项目时">
    ```ts theme={null}
    await client.projects.create({
      source: { type: "path", path: "./song.mp3" },
      presetId: "preset_abc123",
    });
    ```
  </Tab>

  <Tab title="在项目设置中">
    ```ts theme={null}
    await client.projects.updateSettings("prj_abc123", {
      presetId: "preset_abc123",
    });
    ```
  </Tab>

  <Tab title="在导出时">
    ```ts theme={null}
    await client.exports.create("prj_abc123", {
      presetId: "preset_abc123",
      resolution: "1080p",
    });
    ```
  </Tab>
</Tabs>

## 下一步

* [渲染设置参考](/en/render-settings-reference) — 所有共享字段路径与枚举值
* [媒体](/zh/sdk/media) — 在预设内容中被引用
* [项目设置](/zh/sdk/project-settings) — 将预设应用到项目
* [API 预设](/zh/api/presets) — 通过原始 HTTP 完成相同流程
* [CLI 预设](/zh/cli/presets) — 在终端中完成相同流程
* [导出](/zh/sdk/exports) — 使用预设进行渲染