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

# 项目设置

> 读取并修补项目的活动设置

每个项目都有活动设置——裁剪、背景、字幕样式、布局——用于控制导出如何渲染。当你需要项目本地的覆盖项、但又不值得作为预设共享时，请使用项目设置。

共享的 `preset`、`settings.style` 和 `settingsOverride` 字段映射请参见 [渲染设置参考](/en/render-settings-reference)。

## 端点

| 方法      | 路径                               | 用途                 |
| ------- | -------------------------------- | ------------------ |
| `GET`   | `/projects/{projectId}/settings` | 获取当前活动的项目设置。       |
| `PATCH` | `/projects/{projectId}/settings` | 应用预设、修补设置，或同时执行两者。 |

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

## 获取当前设置

```bash theme={null}
curl https://api.youka.io/zh/api/v1/projects/prj_abc/settings \
  -H "Authorization: Bearer yk_..."
```

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

## 修补设置

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

<Tabs>
  <Tab title="Apply a preset">
    ```bash theme={null}
    curl -X PATCH https://api.youka.io/zh/api/v1/projects/prj_abc/settings \
      -H "Authorization: Bearer yk_..." \
      -H "Content-Type: application/json" \
      -d '{
        "presetId": "preset_abc123"
      }'
    ```
  </Tab>

  <Tab title="Inline settings">
    ```bash theme={null}
    curl -X PATCH https://api.youka.io/zh/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"
            }
          }
        }
      }'
    ```
  </Tab>

  <Tab title="Preset + overrides">
    ```bash theme={null}
    curl -X PATCH https://api.youka.io/zh/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 }
        }
      }'
    ```
  </Tab>
</Tabs>

## 发现有效字段

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

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

const schema = RestUpdateProjectSettingsRequestSchema.toJSONSchema();
```

<Tip>
  Agents 在变更项目设置之前，应先获取 SDK schema 或 OpenAPI 请求 schema，以确保始终了解当前的数据结构。
</Tip>

便于阅读的参考：

* [渲染设置参考](/en/render-settings-reference)
* [CLI projects](/zh/cli/projects)
* [SDK project settings](/zh/sdk/project-settings)

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

Youka 有三个层级可承载渲染设置：

| 层级                            | 作用域   | 何时使用              |
| ----------------------------- | ----- | ----------------- |
| **Preset**                    | 账号范围  | 在多个项目中保持相同的外观。    |
| **Project settings**          | 单个项目  | 项目特定的裁剪、背景或颜色。    |
| **Export `settingsOverride`** | 仅单次导出 | 调整一次渲染效果而不影响项目本身。 |

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

## 接下来

* [渲染设置参考](/en/render-settings-reference) — 所有共享字段路径与枚举值
* [Presets](/zh/api/presets) — 可复用配置
* [Media](/zh/api/media) — 在 settings 中被引用
* [CLI projects](/zh/cli/projects) — 在终端中走同样的流程
* [SDK project settings](/zh/sdk/project-settings) — TypeScript 中的同一组端点