Skip to main content
预设（preset）是一种可复用的渲染配置——背景、字幕样式、布局——你可以将其应用到任何项目或导出。当你需要在多条音轨之间保持一致的视觉风格时，使用预设。 完整的 preset 结构以及所有由枚举支持的选项，请参见 渲染设置参考。

​
何时使用预设

在以下情况使用预设…

你希望在多个项目中保持相同风格，并且需要在一个地方统一更新。

在以下情况使用项目设置…

你需要仅限某个项目的覆盖配置，但这些配置不值得共享。

​
端点

MethodPathPurpose
GET/presets列出已认证账户的预设。
POST/presets创建一个新的预设。
GET/presets/{presetId}获取单个预设。
PATCH/presets/{presetId}更新名称、内容，或设置为默认值。
DELETE/presets/{presetId}删除一个预设。
完整的请求与响应 schema 可在侧边栏 API reference 下查看。

​
创建预设

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。请保存它，并在项目或导出中引用。
为每个 POST 配对一个幂等键。对同一 payload 重复使用相同的键会返回原始预设，而不是创建重复项。

​
发现有效的预设字段

预设会在服务端根据 KaraokePresetSchema 进行校验。SDK 导出该 schema，因此你可以在运行时将其转换为 JSON Schema： 
import { KaraokePresetSchema } from "@youka/sdk";

const jsonSchema = KaraokePresetSchema.toJSONSchema();
使用 CLI： 
youka preset schema --json
Agent 作者在修改预设之前应先调用此命令/接口，这样模型才能了解所有有效字段以及取值类型。 可读性更强的参考：

​
更新预设

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 的任意子集即可。未包含的字段将保持不变。

​
设置默认预设

每个账户最多只有一个默认预设，会自动应用到新项目。 
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
  }'
设置新的默认值会自动取消之前的默认预设。

​
应用预设

你可以在三个位置引用预设：
WhereField
创建项目时POST /projects 中的 presetId
项目中的任意时刻PATCH /projects/{projectId}/settings 中的 presetId
导出时POST /projects/{projectId}/exports 中的 presetId
导出示例： 
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"
  }'

​
删除预设

curl -X DELETE https://api.youka.io/zh/api/v1/presets/preset_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: delete-preset_abc123"
删除预设不会影响之前使用该预设渲染的项目或导出。未来引用已删除预设的导出将会失败。

​
下一步