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

# Cài đặt dự án

> Đọc và cập nhật các cài đặt đang hoạt động của một dự án

Mỗi dự án đều có các cài đặt đang hoạt động — trim, background, kiểu subtitle, layout — quyết định cách các bản xuất (export) được render. Hãy dùng cài đặt dự án khi bạn muốn ghi đè theo từng dự án (project-local) mà không đáng để chia sẻ dưới dạng preset.

Xem [Render settings reference](/en/render-settings-reference) để biết bảng ánh xạ các trường dùng chung cho
`preset`, `settings.style`, và `settingsOverride`.

## Endpoints

| Method  | Path                             | Purpose                                        |
| ------- | -------------------------------- | ---------------------------------------------- |
| `GET`   | `/projects/{projectId}/settings` | Lấy các cài đặt dự án đang hoạt động.          |
| `PATCH` | `/projects/{projectId}/settings` | Áp dụng preset, cập nhật cài đặt, hoặc cả hai. |

Schema đầy đủ cho request và response có trong **API reference**.

## Lấy cài đặt hiện tại

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

Trả về toàn bộ cài đặt dự án đang hoạt động, bao gồm cả preset (nếu đang được áp dụng).

## Cập nhật cài đặt

`PATCH` chấp nhận bất kỳ tập con nào của `presetId` và `settings`. Khi truyền cả hai, preset sẽ được áp dụng trước, sau đó `settings` sẽ được merge chồng lên.

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

  <Tab title="Cài đặt inline">
    ```bash theme={null}
    curl -X PATCH https://api.youka.io/vi/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 + ghi đè">
    ```bash theme={null}
    curl -X PATCH https://api.youka.io/vi/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>

## Tìm các trường hợp lệ

SDK export schema dùng để validate các cập nhật cài đặt dự án. Hãy chuyển nó sang JSON Schema tại runtime:

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

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

<Tip>
  Agents nên lấy SDK schema hoặc OpenAPI request schema trước khi
  thay đổi cài đặt dự án để luôn nắm được cấu trúc hiện tại.
</Tip>

Tài liệu tham khảo dễ đọc:

* [Render settings reference](/en/render-settings-reference)
* [CLI projects](/vi/cli/projects)
* [SDK project settings](/vi/sdk/project-settings)

## Cài đặt dự án vs preset vs ghi đè khi export

Youka có ba lớp nơi render settings có thể tồn tại:

| Layer                         | Scope              | Khi nào dùng                                       |
| ----------------------------- | ------------------ | -------------------------------------------------- |
| **Preset**                    | Toàn bộ tài khoản  | Cùng một giao diện cho nhiều dự án.                |
| **Project settings**          | Một dự án          | Trim, background, hoặc màu sắc riêng theo dự án.   |
| **Export `settingsOverride`** | Chỉ một lần export | Tinh chỉnh một lần render mà không đụng đến dự án. |

Mỗi lớp được merge theo thứ tự đó tại thời điểm export.

## Tiếp theo

* [Render settings reference](/en/render-settings-reference) — tất cả đường dẫn trường dùng chung và các giá trị enum
* [Presets](/vi/api/presets) — các cấu hình tái sử dụng
* [Media](/vi/api/media) — được tham chiếu từ settings
* [CLI projects](/vi/cli/projects) — cùng luồng thao tác từ terminal
* [SDK project settings](/vi/sdk/project-settings) — cùng các endpoint trong TypeScript