> ## 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` 필드 맵은 [Render settings reference](/en/render-settings-reference)를 참고하세요.

## 엔드포인트

| Method  | Path                             | Purpose                  |
| ------- | -------------------------------- | ------------------------ |
| `GET`   | `/projects/{projectId}/settings` | 활성 프로젝트 설정을 가져옵니다.       |
| `PATCH` | `/projects/{projectId}/settings` | 프리셋 적용, 설정 패치 또는 둘 다 수행. |

전체 요청 및 응답 스키마는 **API reference**에 있습니다.

## 현재 설정 가져오기

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

적용된 프리셋을 포함하여 전체 활성 프로젝트 설정을 반환합니다.

## 설정 패치하기

`PATCH`는 `presetId`와 `settings`의 어떤 하위 집합이든 허용합니다. 둘 다 전달되면 먼저 프리셋이 적용되고 그 위에 `settings`가 병합됩니다.

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

  <Tab title="인라인 설정">
    ```bash theme={null}
    curl -X PATCH https://api.youka.io/ko/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="프리셋 + 재정의">
    ```bash theme={null}
    curl -X PATCH https://api.youka.io/ko/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는 프로젝트 설정 업데이트를 검증하는 스키마를 내보냅니다. 런타임에 이를 JSON Schema로 변환하세요:

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

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

<Tip>
  에이전트는 프로젝트 설정을 변경하기 전에 SDK 스키마 또는 OpenAPI 요청 스키마를 가져와서
  항상 현재 형태를 알 수 있도록 해야 합니다.
</Tip>

사람이 읽기 쉬운 레퍼런스:

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

## 프로젝트 설정 vs 프리셋 vs 내보내기 재정의

Youka에는 렌더 설정이 존재할 수 있는 세 가지 레이어가 있습니다:

| Layer                         | Scope           | When to use                    |
| ----------------------------- | --------------- | ------------------------------ |
| **Preset**                    | Account-wide    | 여러 프로젝트에서 동일한 룩을 사용할 때.        |
| **Project settings**          | One project     | 프로젝트별 트림, 배경 또는 색상이 필요할 때.     |
| **Export `settingsOverride`** | One export only | 프로젝트를 건드리지 않고 단일 렌더만 미세 조정할 때. |

내보내기 시점에 각 레이어는 위 순서대로 병합됩니다.

## 다음 단계

* [Render settings reference](/en/render-settings-reference) — 공유되는 모든 필드 경로와 enum 값
* [Presets](/ko/api/presets) — 재사용 가능한 구성
* [Media](/ko/api/media) — settings에서 참조됨
* [CLI projects](/ko/cli/projects) — 터미널에서 동일한 흐름
* [SDK project settings](/ko/sdk/project-settings) — TypeScript에서 동일한 엔드포인트