Skip to main content
项目是 Youka 中的顶层资源。每个项目都拥有其源文件、分离的 stem、同步歌词、导出结果以及项目设置。

​
创建项目

在大多数情况下，使用 client.projects.create() ——它会为你处理上传。 
const operation = await client.projects.create({
  source: { type: "path", path: "./song.mp3" },
  lyricsSource: { type: "transcribe" },
});
// => ProjectOperation

​
Source 类型

从磁盘读取文件。
source: {
  type: "path",
  path: "./song.mp3",
  contentType: "audio/mpeg", // optional, inferred if omitted
}

​
其他字段

​
title
string
项目标题。默认使用源文件名。
​
splitModel
SplitModel
Stem 分离模型。默认值为 mdx23c。参见 Split model 参考。
​
presetId
string
在创建时应用可复用的预设。
​
lyricsSource
LyricsSource
配置歌词同步。见下文。

​
Lyrics source

// 从音频转写歌词
lyricsSource: {
  type: "transcribe",
  syncModel: "audioshake-transcription", // optional
  language: "en",                        // optional
}

// 将精确歌词与音频对齐
lyricsSource: {
  type: "align",
  lyrics: "First line\nSecond line\n...",
  syncModel: "audioshake-alignment",
}

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

当你已经有上传好的 inputFileId 时，client.projects.create() 也接受更底层的 inputFile source。 
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?)

在不创建项目的情况下，报价创建项目所需的 credits。 
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(...) 接受与 client.projects.create(...) 相同的 source 形式，包括 URL 的 maxVideoQuality。如果你已经知道媒体时长，并且不想为了报价而上传文件，可以传入更底层的 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?)

将文件字节以 PUT 方式上传到签名 URL。 
await client.uploads.upload(upload.uploadUrl, fileBuffer, {
  contentType: "audio/mpeg",
  signal: abortController.signal,
});
​
body
FetchBody
required
任何与 fetch 兼容的 body：Blob、File、ArrayBuffer、Uint8Array、ReadableStream 或 string。
如果上传返回非 2xx 状态，会抛出 code 为 UPLOAD_FAILED 的 YoukaRequestError。

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

获取完整的项目状态，包括 stem、歌词和导出结果。 
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?)

删除项目以及其关联的所有 stem、歌词和导出结果。 
await client.projects.delete("prj_abc123", {
  idempotencyKey: "delete-prj_abc123",
});
删除是永久性的。请配合幂等键使用，以便重试时安全。

​
接下来

  • Stems — 重新运行 stem 分离
  • Lyrics sync — 重新同步歌词
  • Exports — 渲染最终视频
  • Tasks — 使用 client.projects.wait 等待项目操作完成