Skip to main content
导出会将完成的卡拉OK渲染为视频文件。使用 client.exports.create(...) 作为主要入口点。当你希望 SDK 直接在当前机器上渲染时选择 target: "local"；否则默认是云端导出。

​
client.exports.create(projectId, input, options?)

使用 target: "cloud" | "local" 选择导出目标。 
const cloud = await client.exports.create("prj_abc123", {
  resolution: "1080p",
  quality: "high",
});
// => ExportOperation

const local = await client.exports.create("prj_abc123", {
  target: "local",
  resolution: "1080p",
  quality: "high",
  outputPath: "./karaoke.mp4",
});
// => { outputPath, fileSize, duration, ... }
当你需要托管式的异步导出时使用云端。当你希望直接在调用方机器上渲染时使用本地。

​
通用字段

字段类型说明
resolution"540p" | "720p" | "1080p"输出分辨率。
quality"low" | "average" | "high"编码质量。
playbackRatenumber速度倍率（例如 0.9）。
toneFrequencynumber以半音为单位的音高偏移。
transparentboolean使用透明背景渲染。
presetIdstring在渲染前应用预设。
stemVolumesRecord<string, number>按 stem id 进行逐 stem 音量覆盖。
settingsOverrideobject仅为本次导出补丁式覆盖项目设置。

​
带 stem 音量的示例

const result = await client.exports.create("prj_abc123", {
  resolution: "1080p",
  quality: "high",
  stemVolumes: {
    vocals: 0,
    instrumental: 1,
    backing: 0.5,
  },
});

​
带设置覆盖的示例

const result = await client.exports.create("prj_abc123", {
  resolution: "1080p",
  settingsOverride: {
    trim: { startSeconds: 5, endSeconds: 180 },
    style: {
      background: { type: "color", color: "#101010" },
    },
  },
});
完整的 settingsOverride 结构请参见 渲染设置参考。

​
client.exports.quote(projectId, input, options?)

在不启动导出的情况下，预估一次云端导出所需的 credits。 
const quote = await client.exports.quote("prj_abc123", {
  resolution: "1080p",
  quality: "high",
  transparent: false,
});

console.log(quote.creditsRequired, quote.sufficientBalance);
本地导出在调用方机器上运行，不会使用云端导出 credits，因此 quote(...) 仅适用于云端导出。

​
client.exports.list(projectId, input?, options?)

列出某个项目的导出，并支持分页。 
const exports = await client.exports.list("prj_abc123", {
  page: 1,
  pageSize: 50,
});
​
page
number
页码。服务端默认是 1。
​
pageSize
number
每页数量。默认是 100。最大 100。

​
client.exports.get(exportId, options?)

仅通过 ID 获取一个导出，无需知道其父项目。 
const exported = await client.exports.get("exp_xyz");

​
本地导出

const result = await client.exports.create("prj_abc123", {
  target: "local",
  resolution: "1080p",
  quality: "high",
  outputPath: "./karaoke.mp4",
  onProgress(progress) {
    console.log(progress.stage, progress.percent);
  },
});

console.log(result.outputPath);
如果你希望在本地渲染工具链安装或验证过程中也获得更新，请使用 onDependencyProgress。

​
client.exports.prepareLocal(projectId, body, options?)

返回在本地渲染导出所需的已准备 payload。与 @youka/remotion 或其他本地渲染器集成时使用。服务端会返回 composition 输入、资源 URL 以及渲染参数，而不会将云端渲染加入队列。 
const payload = await client.exports.prepareLocal("prj_abc123", {
  resolution: "1080p",
  quality: "high",
});

// Hand payload off to your local renderer
await renderLocally(payload);
client.exports.prepareLocal(...) 不会启动云端渲染。Youka 侧不会消耗任何计费计算资源。

​
等待导出完成

云端导出是异步的。使用 client.exports.wait(...)： 
const operation = await client.exports.create("prj_abc123", {
  resolution: "1080p",
});

const finalized = await client.exports.wait(operation, {
  pollIntervalMs: 3_000,
});
console.log("Download from", finalized.url);

​
下载结果

云端导出完成后会提供一个签名 url。使用内置 helper 将文件流式写入磁盘。output 可以是目录或完整文件路径，filename 可选： 
await client.exports.download(finalized, {
  output: "./exports",
});

​
下一步

  • 任务 — 操作句柄与高级任务轮询
  • 预设 — 可复用的渲染配置
  • 项目设置 — 补丁式更新项目的当前活动设置