Skip to main content
项目是单首卡拉 OK 曲目的进行中资源。它包含源媒体、同步歌词、分离音轨（stems）、渲染设置，以及由此创建的导出内容。

​
project create

从本地文件或 URL 创建一个新项目。 
youka project create <source> [options]
​
source
string
required
本地文件路径（./song.mp3）或 HTTP/HTTPS URL （https://example.com/song.mp4）。

​
Options

OptionDescription
--title <title>项目标题
--mode <mode>none、transcribe 或 align
--lyrics <text>歌词文本
--lang <code>语言代码
--sync-model <model>歌词同步模型
--split-model <model>音轨分离模型
--max-video-quality <quality>URL 来源的最高视频质量：720p、1080p、4k 或 best
--preset <presetId>创建项目时应用预设
--export项目就绪后创建一个导出
--download创建一个导出，等待完成并下载
--output <path>--download 的输出路径

​
Examples

youka project create ./song.mp3 \
  --title "My Song" \
  --mode transcribe \
  --lang en \
  --wait \
  --json
规则：
  • 如果你传入了歌词但省略 --mode，CLI 默认使用 align
  • align 需要歌词
  • transcribe 和 none 不接受歌词
  • --download 隐含 --export
  • --max-video-quality 仅适用于 HTTP/HTTPS URL 来源。默认值为 1080p，会在该上限内使用可用的最佳质量；当平台不提供受限码流时，会回退到可用的最佳格式。

​
project list

列出已认证账号下的所有项目。 
youka project list
youka project list --json

​
project quote

在不创建项目的情况下，估算创建项目所需的 credits。 
youka project quote <source> [options]
source 接受与 project create 相同的本地文件路径或 HTTP/HTTPS URL 形式。不带 --duration 时，CLI 会上传源文件以便服务器精确测量媒体时长，但不会创建项目。

​
Options

OptionDescription
--title <title>项目标题
--mode <mode>none、transcribe 或 align
--lyrics <text>align 使用的歌词文本
--lang <code>语言代码
--sync-model <model>歌词同步模型
--split-model <model>音轨分离模型
--max-video-quality <quality>URL 来源的最高视频质量：720p、1080p、4k 或 best
--duration <seconds>在已知时长的情况下直接估算，无需上传源文件
Examples: 
youka project quote ./song.mp3 --mode transcribe --json
youka project quote https://example.com/song.mp4 --max-video-quality 4k --mode transcribe --json
youka project quote ./song.mp3 --duration 210 --mode none --json

​
project show

获取当前项目状态，包括标准化后的 state、pendingOperation、stems、settings 和 exports。 
youka project show <projectId>
​
projectId
string
required
project create 返回的项目 ID。

​
project wait

轮询项目，直到它达到终态。 
youka project wait <projectId> --json

​
project delete

删除项目及其关联的所有 stems、lyrics 和 exports。 
youka project delete <projectId> --idempotency-key delete-<projectId>
删除是永久性的。传入 --idempotency-key 可确保重试是安全的。

​
project sync

在现有项目上重新运行歌词转写或对齐。 
youka project sync <projectId> [options]
OptionDescription
--mode <mode>transcribe 或 align
--text <text>歌词文本
--lang <code>语言代码
--sync-model <model>歌词同步模型
Example: 
youka project sync $PROJECT_ID \
  --mode align \
  --text "$(cat lyrics.txt)" \
  --wait \
  --json

​
project separate

在现有项目上重新运行音轨分离。 
youka project separate <projectId> [--split-model <model>]
Example: 
youka project separate $PROJECT_ID --split-model audioshakeai --wait --json

​
project settings

读取或更新当前项目设置。 
youka project settings <projectId>
youka project settings <projectId> --preset <presetId> --body ./settings.json
如果 --preset 和 --body 都不存在，该命令会返回当前设置；如果存在任意一个，则会执行更新。 Examples: 
youka project settings $PROJECT_ID --json

​
project stem list

列出项目的 stems。 
youka project stem list <projectId>
youka project stem list <projectId> --json

​
project stem download

将一个或多个 stem 文件下载到磁盘。stems 会以其原始存储格式下载；CLI 不会对其进行转码。 
youka project stem download <projectId> <stemId> --output ./stems
youka project stem download <projectId> --type instrumental --output ./stems
youka project stem download <projectId> --type original --type backing-vocals --type vocals --output ./stems
youka project stem download <projectId> --all --output ./stems
支持的 --type 值为 original、instrumental、vocals 和 backing_vocals。CLI 也接受 backing-vocals、backingVocals 和 backingvocals 作为别名。

​
下一步