Projects

Dự án là tài nguyên cấp cao nhất trong Youka. Mỗi dự án sở hữu tệp nguồn, lời bài hát, các bản xuất, và cài đặt dự án. Dự án karaoke cũng chứa các stem đã được tách.

Tạo một project

Trong hầu hết các trường hợp, hãy dùng client.projects.create() — hàm này sẽ xử lý việc upload cho bạn.

const operation = await client.projects.create({
  source: { type: "path", path: "./song.mp3" },
  lyricsSource: { type: "transcribe" },
});
// => ProjectOperation

Các loại source

path
bytes
url

Đọc một tệp từ ổ đĩa.

source: {
  type: "path",
  path: "./song.mp3",
  contentType: "audio/mpeg", // optional, inferred if omitted
}

Blob, File, ArrayBuffer hoặc Uint8Array trong bộ nhớ.

source: {
  type: "bytes",
  data: fileBuffer,
  filename: "song.mp3",
  contentType: "audio/mpeg", // optional
}

URL HTTP hoặc HTTPS từ xa.Các trang được host hỗ trợ phụ thuộc vào yt-dlp. Xem danh sách URL được hỗ trợ.

source: {
  type: "url",
  url: "https://example.com/song.mp4",
  maxVideoQuality: "1080p", // optional: "720p", "1080p", "4k", or "best"
}

maxVideoQuality kiểm soát chất lượng video tối đa được tải xuống đối với source dạng URL. Mặc định là 1080p. SDK sẽ dùng chất lượng tốt nhất có sẵn trong giới hạn đó, và sẽ fallback về định dạng tốt nhất sẵn có nếu nền tảng không cung cấp stream có giới hạn chất lượng. Dùng best nếu không muốn giới hạn.

Trên Node.js và Bun, SDK tự động đảm bảo các binary phụ thuộc URL cần thiết (ffmpeg, ffprobe, yt-dlp) ngay lần sử dụng đầu tiên. Lệnh CLI tương đương là youka deps ensure --for url.

Các trường khác

string

Tiêu đề project. Mặc định là tên tệp nguồn.

karaoke | lyric-video

Luồng xử lý. Mặc định là karaoke. lyric-video dùng audio gốc mà không tách stem.

SplitModel

Mô hình tách stem cho karaoke. Mặc định là mdx23c. Bị từ chối với lyric-video. Xem Tài liệu tham chiếu split model reference.

string

Áp dụng một preset tái sử dụng ngay khi tạo.

LyricsSource

Cấu hình đồng bộ lời bài hát. Xem bên dưới.

Các nguồn lyrics

// Transcribe lyrics from the audio
lyricsSource: {
  type: "transcribe",
  syncModel: "audioshake-transcription", // optional
  language: "en",                        // optional
}

// Align exact lyrics to the audio
lyricsSource: {
  type: "align",
  lyrics: "First line\nSecond line\n...",
  syncModel: "audioshake-alignment",
}

`client.projects.create(input, options?)`

client.projects.create() cũng chấp nhận source inputFile mức thấp khi bạn đã có inputFileId từ tệp đã upload.

const upload = await client.uploads.create({
  filename: "song.mp3",
  contentType: "audio/mpeg",
  contentLength: buffer.byteLength,
});

await client.uploads.upload(upload.uploadUrl, buffer, {
  contentType: "audio/mpeg",
});

const operation = await client.projects.create({
  source: {
    type: "inputFile",
    inputFileId: upload.inputFileId,
    filename: "song.mp3",
  },
  title: "My Song",
});

`client.projects.quote(input, options?)`

Báo giá số credit cần để tạo một project mà không tạo thật.

const quote = await client.projects.quote({
  source: { type: "path", path: "./song.mp3" },
  lyricsSource: { type: "transcribe", language: "en" },
  splitModel: "mdx23c",
});

console.log(quote.creditsRequired, quote.sufficientBalance);

client.projects.quote(...) chấp nhận các dạng source giống như client.projects.create(...), bao gồm URL maxVideoQuality. Nếu bạn đã biết thời lượng media và không muốn upload tệp chỉ để báo giá, hãy truyền đúng shape REST mức thấp:

const quote = await client.projects.quote({
  durationSeconds: 210,
  lyricsSource: null,
  splitModel: "mdx23c",
});

`client.uploads.create(body, options?)`

Cấp một slot upload và lấy một signed URL.

const upload = await client.uploads.create({
  filename: "song.mp3",
  contentType: "audio/mpeg",
  contentLength: 4_521_344,
});
// => { inputFileId, uploadUrl }

`client.uploads.upload(uploadUrl, body, options?)`

PUT các byte của tệp lên signed URL.

await client.uploads.upload(upload.uploadUrl, fileBuffer, {
  contentType: "audio/mpeg",
  signal: abortController.signal,
});

FetchBody

required

Bất kỳ body tương thích fetch: Blob, File, ArrayBuffer, Uint8Array, ReadableStream hoặc string.

Ném lỗi YoukaRequestError với code UPLOAD_FAILED nếu upload trả về status không thuộc 2xx.

`client.projects.get(projectId, options?)`

Lấy toàn bộ trạng thái project, bao gồm stem, lyrics và export.

const project = await client.projects.get("prj_abc123");
console.log(project.title, project.stems, project.lyrics);

`client.projects.update(projectId, body, options?)`

Patch metadata của project.

const project = await client.projects.update("prj_abc123", {
  title: "Updated title",
  artists: ["Artist name"],
});

Truyền ít nhất một trong title hoặc artists.

`client.projects.list(options?)`

Liệt kê mọi project thuộc tài khoản đã xác thực.

const projects = await client.projects.list();
projects.forEach((p) => console.log(p.id, p.title));

Trả về một mảng các project list item (shape gọn hơn so với getProject).

`client.projects.delete(projectId, options?)`

Xóa một project và toàn bộ stem, lyrics và export liên quan.

await client.projects.delete("prj_abc123", {
  idempotencyKey: "delete-prj_abc123",
});

Việc xóa là vĩnh viễn. Hãy dùng kèm idempotency key để việc retry được an toàn.

Stems — chạy lại tách stem
Lyrics sync — đồng bộ lại lyrics
Exports — render video hoàn chỉnh
Tasks — chờ các thao tác project với client.projects.wait

Tạo lyric-video và khám phá model

const capabilities = await client.capabilities.get();
const operation = await client.projects.create({
  kind: "lyric-video",
  source: { type: "path", path: "./song.wav" },
  lyricsSource: {
    type: "transcribe",
    syncModel: "elevenlabs-transcription",
    lyrics: "Optional reference lyrics",
  },
});
const { project } = await client.projects.wait(operation);
const versions = await client.projects.versions.list(project.id);

Các lựa chọn kind và xử lý lyrics tương tự cũng hoạt động với projects.quote. Báo giá lyric-video tính 0 separation credits. Quote và create xác thực cùng một yêu cầu về model, ngôn ngữ, tài khoản và source. Quote không giữ chỗ credit hoặc năng lực xử lý. Dùng lyricsSource: null để bỏ qua xử lý lyrics. Văn bản tham chiếu trong transcription chỉ mang tính định hướng và có thể khác với kết quả. Các model cần vocal đã được tách riêng không thể xử lý lyric video không tách stem. Xem Automate lyric videos để biết capabilities, cập nhật timing chính xác và các checkpoint catalogue.

Overview

How To

Customization

Audio

Settings

Exporting

Account

Tạo một project

Các loại source

Các trường khác

Các nguồn lyrics

`client.projects.create(input, options?)`

`client.projects.quote(input, options?)`

`client.uploads.create(body, options?)`

`client.uploads.upload(uploadUrl, body, options?)`

`client.projects.get(projectId, options?)`

`client.projects.update(projectId, body, options?)`

`client.projects.list(options?)`

`client.projects.delete(projectId, options?)`

Tiếp theo

Tạo lyric-video và khám phá model

​Tạo một project

​Các loại source

​Các trường khác

​Các nguồn lyrics

​client.projects.create(input, options?)

​client.projects.quote(input, options?)

​client.uploads.create(body, options?)

​client.uploads.upload(uploadUrl, body, options?)

​client.projects.get(projectId, options?)

​client.projects.update(projectId, body, options?)

​client.projects.list(options?)

​client.projects.delete(projectId, options?)

​Tiếp theo

​Tạo lyric-video và khám phá model

Tạo một project

Các loại source

Các trường khác

Các nguồn lyrics

`client.projects.create(input, options?)`

`client.projects.quote(input, options?)`

`client.uploads.create(body, options?)`

`client.uploads.upload(uploadUrl, body, options?)`

`client.projects.get(projectId, options?)`

`client.projects.update(projectId, body, options?)`

`client.projects.list(options?)`

`client.projects.delete(projectId, options?)`

Tiếp theo

Tạo lyric-video và khám phá model