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

# 빠른 시작

> 가라오케 프로젝트를 생성하고, 완료될 때까지 기다린 다음, 내보내고 결과를 다운로드합니다

이 가이드는 `@youka/sdk`를 사용해 원본 오디오 파일에서 렌더링된 가라오케 비디오까지 가장 빠르게 진행하는 방법을 안내합니다.

## 시작하기 전에

* Node.js 20 이상
* `YOUKA_API_KEY`에 설정된 Youka API 키 ( [online.youka.io/account](https://online.youka.io/account) 에서 **API keys** 아래 생성)
* 로컬 오디오 파일(`./song.mp3`) 또는 원격 URL

## 설치

```bash theme={null}
npm install @youka/sdk
```

## 생성, 대기, 내보내기

```ts theme={null}
import { YoukaClient, YoukaRequestError, YoukaTaskError } from "@youka/sdk";

const client = new YoukaClient({
  apiKey: process.env.YOUKA_API_KEY!,
});

async function main() {
  // 1. 로컬 파일로 프로젝트 생성
  const projectOperation = await client.projects.create({
    source: { type: "path", path: "./song.mp3" },
    lyricsSource: { type: "transcribe" },
  });

  // 2. 스템 및 가사 싱크 완료까지 대기
  const { project } = await client.projects.wait(projectOperation);
  console.log("Project ready:", project.id, project.title);

  // 3. 내보내기 시작
  const exportOperation = await client.exports.create(project.id, {
    resolution: "1080p",
    quality: "high",
  });

  // 4. 내보내기 완료까지 대기
  const finishedExport = await client.exports.wait(exportOperation);
  await client.exports.download(finishedExport, {
    output: "./exports",
  });
  console.log("Export ready:", finishedExport.url);
}

main().catch((error) => {
  if (error instanceof YoukaRequestError) {
    console.error("Request failed:", error.code, error.status, error.message);
    process.exit(1);
  }
  if (error instanceof YoukaTaskError) {
    console.error("Task failed:", error.code, error.status, error.message);
    process.exit(1);
  }
  throw error;
});
```

<Note>
  `client.projects.create()`는 `path`, `bytes`, `url`
  소스에 대한 업로드를 처리합니다. 더 낮은 수준에서 업로드를 제어하려면 `client.uploads.*`를 사용하세요.
</Note>

## 세 가지 소스 타입

<Tabs>
  <Tab title="로컬 파일">
    ```ts theme={null}
    const operation = await client.projects.create({
      source: { type: "path", path: "./song.mp3" },
    });
    ```
  </Tab>

  <Tab title="메모리 내 bytes">
    ```ts theme={null}
    const fileBuffer = new Uint8Array([/* audio bytes */]);

    const operation = await client.projects.create({
      source: {
        type: "bytes",
        data: fileBuffer,
        filename: "song.mp3",
      },
    });
    ```
  </Tab>

  <Tab title="원격 URL">
    ```ts theme={null}
    const operation = await client.projects.create({
      source: {
        type: "url",
        url: "https://example.com/song.mp4",
      },
    });
    ```
  </Tab>
</Tabs>

## 다음 단계

* [Projects](/ko/sdk/projects) — 전체 projects API
* [Exports](/ko/sdk/exports) — 로컬 렌더링 및 `client.exports.prepareLocal`
* [Errors](/ko/sdk/errors) — `YoukaRequestError`와 `YoukaTaskError` 처리
* [AI agents](/ko/agents) — 권장 폴링 및 재시도 패턴