Skip to main content
预设是一种可复用的渲染配置——背景、字幕样式、布局——你可以将其应用到任何项目或导出中。当你需要在多条曲目之间保持一致的视觉风格时，使用预设非常合适。 查看 渲染设置参考 以了解完整的 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,
});
​
name
string
required
在 Youka UI 中显示的名称。
​
preset
KaraokePreset
required
完整的预设内容。可使用 渲染设置 参考 查看便于阅读的字段映射，或使用 KaraokePresetSchema.toJSONSchema() 获取机器可读的 schema。
​
isDefault
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",
});

​
下一步