项目设置

每个项目都有一组当前设置——裁剪、背景、字幕样式、布局——用于控制导出的渲染方式。当你需要仅在项目内生效、但又不值得作为预设共享的覆盖项时，请使用项目设置。共享的 preset、settings.style 和 settingsOverride 字段映射请参见 Render settings reference。

端点

Method	Path	Purpose
`GET`	`/projects/{projectId}/settings`	获取当前项目设置。
`PATCH`	`/projects/{projectId}/settings`	应用预设、修改设置，或两者同时进行。

完整的请求与响应 schema 见 API reference。

获取当前设置

curl https://api.youka.io/api/v1/projects/prj_abc/settings \
  -H "Authorization: Bearer yk_..."

返回完整的当前项目设置，包括已应用的任何预设。

修改设置

PATCH 接受 presetId 和 settings 的任意子集。当两者同时传入时，会先应用预设，然后将 settings 合并覆盖到其之上。

应用预设
内联设置
预设 + 覆盖项

curl -X PATCH https://api.youka.io/api/v1/projects/prj_abc/settings \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "presetId": "preset_abc123"
  }'

curl -X PATCH https://api.youka.io/api/v1/projects/prj_abc/settings \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "trim": { "startSeconds": 5, "endSeconds": 180 },
      "style": {
        "background": {
          "type": "color",
          "color": "#101010"
        }
      }
    }
  }'

curl -X PATCH https://api.youka.io/api/v1/projects/prj_abc/settings \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "presetId": "preset_abc123",
    "settings": {
      "trim": { "startSeconds": 5, "endSeconds": 180 }
    }
  }'

发现有效字段

SDK 导出了用于验证项目设置更新的 schema。可在运行时将其转换为 JSON Schema：

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

const schema = RestUpdateProjectSettingsRequestSchema.toJSONSchema();

Agent 在修改项目设置之前，应先获取 SDK schema 或 OpenAPI 请求 schema，以便始终了解当前的数据结构。

可读性更强的参考：

项目设置 vs 预设 vs 导出覆盖项

Youka 有三层可承载渲染设置的位置：

Layer	Scope	When to use
Preset	全账号范围	多个项目共享同一种视觉风格。
Project settings	单个项目	项目专属的裁剪、背景或颜色设置。
Export `settingsOverride`	仅单次导出	在不改动项目的前提下微调一次渲染。

导出时会按该顺序逐层合并。

接下来

Render settings reference — 所有共享字段路径与枚举值
Presets — 可复用的配置
Media — 设置中引用的媒体
CLI projects — 在终端中完成同样流程
SDK project settings — TypeScript 中的同一组端点

选择一个版本

GET /projects/{projectId}/versions 会列出项目的各个版本。你可以在 settings 的 GET 请求中添加 ?versionId=ver_example，或在 PATCH body 中包含 versionId 来选择版本。Settings 的响应会包含 versionId。省略它将保持主版本（primary-version）行为不变。导出请求也接受 versionId。对齐（alignment）的选择属于项目层级，并在各版本之间共享。关于时间轴修订与导出快照，请参见 Automate lyric videos。

Overview

How To

Customization

Audio

Settings

Exporting

Account

端点

获取当前设置

修改设置

发现有效字段

项目设置 vs 预设 vs 导出覆盖项

接下来

选择一个版本

​端点

​获取当前设置

​修改设置

​发现有效字段

​项目设置 vs 预设 vs 导出覆盖项

​接下来

​选择一个版本

端点

获取当前设置

修改设置

发现有效字段

项目设置 vs 预设 vs 导出覆盖项

接下来

选择一个版本