预设 - Youka Docs

预设是一种可复用的渲染配置——背景、字幕样式、布局——你可以将其应用到任何项目或导出中。当你需要在多条曲目之间保持一致的视觉风格时，使用预设非常合适。查看渲染设置参考以了解完整的 preset 结构以及所有由枚举支持的选项。

`client.presets.list(options?)`

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

const presets = await client.presets.list();
presets.forEach((p) => console.log(p.id, p.name, p.isDefault));

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

获取单个预设。

const preset = await client.presets.get("preset_abc123");

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

创建一个新的预设。

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,
});

string

required

在 Youka UI 中显示的名称。

KaraokePreset

required

完整的预设内容。可使用 渲染设置参考 查看便于阅读的字段映射，或使用 KaraokePresetSchema.toJSONSchema() 获取机器可读的 schema。

boolean

将新预设标记为账号默认值。同一时间只能有一个预设作为默认值。

配合幂等键以安全重试：

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

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

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

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

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

删除一个预设。

await client.presets.delete("preset_abc123", {
  idempotencyKey: "delete-preset_abc123",
});

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

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

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

await client.presets.setDefault("preset_abc123");

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

发现有效字段

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

import { KaraokePresetSchema } from "@youka/sdk";

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

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

便于阅读的参考：

应用预设

可在三个节点应用预设：

在创建项目时
在项目设置中
在导出时

await client.projects.create({
  source: { type: "path", path: "./song.mp3" },
  presetId: "preset_abc123",
});

await client.projects.updateSettings("prj_abc123", {
  presetId: "preset_abc123",
});

await client.exports.create("prj_abc123", {
  presetId: "preset_abc123",
  resolution: "1080p",
});

下一步

渲染设置参考 — 所有共享字段路径与枚举值
媒体 — 在预设内容中被引用
项目设置 — 将预设应用到项目
API 预设 — 通过原始 HTTP 完成相同流程
CLI 预设 — 在终端中完成相同流程
导出 — 使用预设进行渲染

Overview

How To

Customization

Audio

Settings

Exporting

Account

预设

`client.presets.list(options?)`

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

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

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

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

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

发现有效字段

应用预设

下一步

​client.presets.list(options?)

​client.presets.get(presetId, options?)

​client.presets.create(body, options?)

​client.presets.update(presetId, body, options?)

​client.presets.delete(presetId, options?)

​client.presets.setDefault(presetId, options?)

​发现有效字段

​应用预设

​下一步

`client.presets.list(options?)`

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

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

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

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

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

发现有效字段

应用预设

下一步