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

# Khởi động nhanh

> Tạo một dự án karaoke, chờ hoàn tất, xuất dự án và tải xuống kết quả

Hướng dẫn này trình bày lộ trình nhanh nhất từ một tệp âm thanh thô đến một video karaoke đã được render bằng `@youka/sdk`.

## Trước khi bắt đầu

* Node.js 20 trở lên
* Một Youka API key trong `YOUKA_API_KEY` (tạo tại [online.youka.io/account](https://online.youka.io/account) trong mục **API keys**)
* Một tệp âm thanh cục bộ (`./song.mp3`) hoặc một URL từ xa

## Cài đặt

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

## Tạo, chờ, xuất

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

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

async function main() {
  // 1. Tạo một dự án từ tệp cục bộ
  const projectOperation = await client.projects.create({
    source: { type: "path", path: "./song.mp3" },
    lyricsSource: { type: "transcribe" },
  });

  // 2. Chờ tách stem và đồng bộ lời hoàn tất
  const { project } = await client.projects.wait(projectOperation);
  console.log("Project ready:", project.id, project.title);

  // 3. Bắt đầu một lần xuất
  const exportOperation = await client.exports.create(project.id, {
    resolution: "1080p",
    quality: "high",
  });

  // 4. Chờ quá trình xuất hoàn tất
  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()` xử lý upload cho các nguồn `path`, `bytes`, và `url`.
  Để kiểm soát upload ở mức thấp hơn, hãy dùng `client.uploads.*`.
</Note>

## Ba loại nguồn

<Tabs>
  <Tab title="Tệp cục bộ">
    ```ts theme={null}
    const operation = await client.projects.create({
      source: { type: "path", path: "./song.mp3" },
    });
    ```
  </Tab>

  <Tab title="Bytes trong bộ nhớ">
    ```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 từ xa">
    ```ts theme={null}
    const operation = await client.projects.create({
      source: {
        type: "url",
        url: "https://example.com/song.mp4",
      },
    });
    ```
  </Tab>
</Tabs>

## Tiếp theo là gì

* [Projects](/vi/sdk/projects) — API dự án đầy đủ
* [Exports](/vi/sdk/exports) — render cục bộ và `client.exports.prepareLocal`
* [Errors](/vi/sdk/errors) — xử lý `YoukaRequestError` và `YoukaTaskError`
* [AI agents](/vi/agents) — các mẫu polling và retry được khuyến nghị