> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 导出

> 在云端或本地渲染卡拉OK视频

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

## `client.exports.create(projectId, input, options?)`

使用 `target: "cloud" | "local"` 选择导出目标。

```ts theme={null}
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" \| "4k"` | 输出分辨率。                             |
| `quality`          | `"low" \| "average" \| "high"`        | 编码质量。                              |
| `fps`              | `30 \| 60`                            | 每秒帧数。默认是 `30`。如果需要更流畅的动态，请使用 `60`。 |
| `playbackRate`     | `number`                              | 速度倍率（例如 `0.9`）。                    |
| `toneFrequency`    | `number`                              | 以半音为单位的音高偏移。                       |
| `transparent`      | `boolean`                             | 使用透明背景渲染。                          |
| `presetId`         | `string`                              | 在渲染前应用预设。                          |
| `stemVolumes`      | `Record<string, number>`              | 按 stem id 进行逐 stem 音量覆盖。           |
| `settingsOverride` | `object`                              | 仅为本次导出补丁式覆盖项目设置。                   |

使用 `fps: 60` 可以获得更流畅的动态。云端报价在 `60 fps` 时会应用 `1.5x` 的 credits 倍率。当所选时长和分辨率符合云端限制时，可以使用透明 60 fps 云端导出。

### 带 stem 音量的示例

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

### 带设置覆盖的示例

```ts theme={null}
const result = await client.exports.create("prj_abc123", {
  resolution: "1080p",
  settingsOverride: {
    trim: { startSeconds: 5, endSeconds: 180 },
    style: {
      background: { type: "color", color: "#101010" },
    },
  },
});
```

完整的 `settingsOverride` 结构请参见 [渲染设置参考](/en/render-settings-reference)。

## `client.exports.quote(projectId, input, options?)`

在不启动导出的情况下，预估一次云端导出所需的 credits。

```ts theme={null}
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?)`

列出某个项目的导出，并支持分页。

```ts theme={null}
const exports = await client.exports.list("prj_abc123", {
  page: 1,
  pageSize: 50,
});
```

<ParamField path="page" type="number">
  页码。服务端默认是 `1`。
</ParamField>

<ParamField path="pageSize" type="number">
  每页数量。默认是 `100`。最大 `100`。
</ParamField>

## `client.exports.get(exportId, options?)`

仅通过 ID 获取一个导出，无需知道其父项目。

```ts theme={null}
const exported = await client.exports.get("exp_xyz");
```

## 本地导出

```ts theme={null}
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 以及渲染参数，而不会将云端渲染加入队列。

```ts theme={null}
const payload = await client.exports.prepareLocal("prj_abc123", {
  resolution: "1080p",
  quality: "high",
});

// Hand payload off to your local renderer
await renderLocally(payload);
```

<Note>
  `client.exports.prepareLocal(...)` 不会启动云端渲染。Youka 侧不会消耗任何计费计算资源。
</Note>

## 等待导出完成

云端导出是异步的。使用 `client.exports.wait(...)`：

```ts theme={null}
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` 可选：

```ts theme={null}
await client.exports.download(finalized, {
  output: "./exports",
});
```

## 下一步

* [任务](/zh/sdk/tasks) — 操作句柄与高级任务轮询
* [预设](/zh/sdk/presets) — 可复用的渲染配置
* [项目设置](/zh/sdk/project-settings) — 补丁式更新项目的当前活动设置