프로젝트

프로젝트는 Youka의 최상위 리소스입니다. 각 프로젝트는 소스 파일, 가사, 내보내기 결과물, 프로젝트 설정을 소유합니다. 가라오케 프로젝트에는 분리된 스템도 포함됩니다.

프로젝트 생성

대부분의 경우 client.projects.create()를 사용하세요 — 업로드까지 자동으로 처리해 줍니다.

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

소스 타입

path
bytes
url

디스크에서 파일을 읽습니다.

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

메모리 내 Blob, File, ArrayBuffer, 또는 Uint8Array.

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

원격 HTTP 또는 HTTPS URL.지원되는 호스팅 페이지는 yt-dlp에 따라 달라집니다. 지원 URL 목록을 참고하세요.

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

maxVideoQuality는 URL 소스에 대해 다운로드할 동영상의 최대 품질을 제어합니다. 기본값은 1080p입니다. SDK는 해당 한도 내에서 사용 가능한 최고 품질을 사용하며, 플랫폼에서 상한이 있는 스트림을 제공하지 않는 경우 사용 가능한 최적의 포맷으로 폴백합니다. 제한 없이 사용하려면 best를 사용하세요.

Node.js 및 Bun에서는 SDK가 최초 사용 시 필요한 URL 의존성 바이너리(ffmpeg, ffprobe, yt-dlp)를 자동으로 보장합니다. CLI에서의 동등한 명령은 youka deps ensure --for url입니다.

기타 필드

string

프로젝트 제목입니다. 기본값은 소스 파일명입니다.

karaoke | lyric-video

워크플로우입니다. 기본값은 karaoke입니다. lyric-video는 스템 분리 없이 원본 오디오를 사용합니다.

SplitModel

가라오케용 스템 분리 모델입니다. 기본값은 mdx23c입니다. lyric-video에서는 거부됩니다. Split model reference를 참고하세요.

string

생성 시 재사용 가능한 프리셋을 적용합니다.

LyricsSource

가사 동기화를 구성합니다. 아래를 참고하세요.

가사 소스

// 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?)`

이미 업로드된 inputFileId가 있는 경우, client.projects.create()는 더 로우레벨의 inputFile 소스도 받을 수 있습니다.

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?)`

프로젝트를 실제로 생성하지 않고, 생성에 필요한 크레딧을 견적 냅니다.

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(...)는 URL maxVideoQuality를 포함해 client.projects.create(...)와 동일한 source 형태를 받습니다. 미디어 길이를 이미 알고 있고 견적을 위해 파일을 업로드하고 싶지 않다면, 로우레벨 REST 형태를 전달하세요:

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

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

업로드 슬롯을 할당하고 서명된 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?)`

서명된 URL로 파일 바이트를 PUT 합니다.

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

FetchBody

required

fetch 호환 body라면 무엇이든 가능합니다: Blob, File, ArrayBuffer, Uint8Array, ReadableStream, 또는 string.

업로드가 2xx가 아닌 상태를 반환하면 코드가 UPLOAD_FAILED인 YoukaRequestError를 던집니다.

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

스템, 가사, 내보내기를 포함한 전체 프로젝트 상태를 가져옵니다.

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

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

프로젝트 메타데이터를 패치합니다.

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

title 또는 artists 중 최소 하나를 전달하세요.

`client.projects.list(options?)`

인증된 계정이 소유한 모든 프로젝트를 나열합니다.

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

프로젝트 목록 항목 배열을 반환합니다(getProject보다 더 간소한 형태).

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

프로젝트와 관련된 모든 스템, 가사, 내보내기를 삭제합니다.

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

삭제는 영구적입니다. 재시도가 안전하도록 멱등성 키와 함께 사용하세요.

다음 단계

Stems — 스템 분리를 다시 실행
Lyrics sync — 가사를 다시 동기화
Exports — 완성된 비디오 렌더링
Tasks — client.projects.wait로 프로젝트 작업을 대기

리릭 비디오 생성 및 모델 탐색

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);

동일한 kind 및 가사 처리 선택지는 projects.quote에서도 동작합니다. 리릭 비디오 견적은 분리 크레딧을 0으로 청구합니다. 견적과 생성은 동일한 모델, 언어, 계정, 소스 요구사항을 검증합니다. 견적은 크레딧이나 용량을 예약하지 않습니다. 가사 처리를 건너뛰려면 lyricsSource: null을 사용하세요. 전사에서의 참조 텍스트는 가이드이며 결과와 다를 수 있습니다. 보컬 분리가 필요한 모델은 분리 없는 리릭 비디오를 처리할 수 없습니다. 기능, 정확한 타이밍 업데이트, 카탈로그 체크포인트는 Automate lyric videos를 참고하세요.

Overview

How To

Customization

Audio

Settings

Exporting

Account

프로젝트 생성

소스 타입

기타 필드

가사 소스

`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?)`

다음 단계

리릭 비디오 생성 및 모델 탐색

​프로젝트 생성

​소스 타입

​기타 필드

​가사 소스

​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?)

​다음 단계

​리릭 비디오 생성 및 모델 탐색

프로젝트 생성

소스 타입

기타 필드

가사 소스

`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?)`

다음 단계

리릭 비디오 생성 및 모델 탐색