# 可灵 3.0 声音复刻 API

> 可灵 3.0 声音复刻（voice cloning）：克隆一段音源的音色，产出可复用的 voice_id，按次计费

声音复刻用一段音源**克隆音色**，产出一个可复用的 `voice_id`，可直接作为[数字人](/api-capabilities/kling/video-generation#数字人)的 `audio_id` 使用。它是**非视频**的独立任务，计费模型恒为 `kling-3.0-voice`。

<Warning>
声音复刻与视频任务在三处不同，接入时请注意：

1. **专用端点、扁平请求体**：`POST /general/custom-voices`，顶层直接放字段，不使用 `settings` / `contents`。
2. **响应字段名不同**：提交与查询响应用 `data.task_id` / `data.task_status`（**不是**视频的 `id` / `status`）；成功状态是 **`succeed`**（注意**不是**视频的 `succeeded`）。
3. **独立查询端点**：单条结果走 `GET /general/custom-voices/{task_id}`，列表走 `GET /general/custom-voices`，都**不走** `GET /tasks`。
4. **路径可选 `/v1` 前缀**：三个端点均可写成 `/v1/general/custom-voices...`，带与不带行为一致。
</Warning>

## 提交复刻任务

`POST /general/custom-voices` · 模型 `kling-3.0-voice`

```bash cURL
curl -X POST "https://api.looprouter.com/general/custom-voices" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "voice_name": "my-anchor-voice",
    "voice_url": "https://example.com/sample-voice.mp3"
  }'
```

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `voice_name` | string | 是 | 音色名称，长度 ≤ 20 |
| `voice_url` | string | 否 | 音源文件 URL（`.mp3` / `.wav` / `.mp4` / `.mov`，建议 5–30 秒） |

提交成功返回 ack 信封，`data.task_id` 为网关任务 ID（后续查询用它）：

```json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "202608101429431085002008268d9d6gxQi3MuZ",
  "data": {
    "task_id": "task_xxxx",
    "task_status": "submitted",
    "created_at": 1786372183136,
    "updated_at": 1786372183136
  }
}
```

## 查询复刻任务

`GET /general/custom-voices/{task_id}`

用提交返回的 `task_id` 查询进度。任务状态机：`submitted → processing → succeed / failed`。

```bash cURL
curl "https://api.looprouter.com/general/custom-voices/task_xxxx" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

响应 `data` 字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `task_id` | string | 任务 ID |
| `task_status` | string | `submitted` / `processing` / `succeed` / `failed` |
| `task_status_msg` | string | 失败原因（若有） |
| `task_result` | object | 成功时出现，含 `voices[]` |
| `created_at` / `updated_at` | int | Unix 毫秒时间戳 |

`task_result.voices[]` 元素：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `voice_id` | string | 复刻出的音色 ID，可作为数字人的 `audio_id` 复用 |
| `voice_name` | string | 音色名称 |
| `trial_url` | string | 试听音频链接（限时） |
| `owned_by` | string | 归属标识 |

成功响应示例：

```json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "202608101430078425945008268d9d6ZEra2TSv",
  "data": {
    "task_id": "task_xxxx",
    "task_status": "succeed",
    "task_result": {
      "voices": [
        {
          "voice_id": "voice-voicetask-1",
          "voice_name": "demo-cloned",
          "trial_url": "https://api.looprouter.com/voice/voicetask-1.mp3",
          "owned_by": "looprouter"
        }
      ]
    },
    "created_at": 1786372183000,
    "updated_at": 1786372184000
  }
}
```

## 列出已复刻音色

`GET /general/custom-voices`

列出当前令牌下已复刻的音色。`data` 恒为**数组**，每项是一条复刻任务的 ack 信封（`task_id` / `task_status` / 成功时的 `task_result.voices[]`），成功态同为 `succeed`。无查询参数。

```bash cURL
curl "https://api.looprouter.com/general/custom-voices" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

```json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "202608101431556730001008268d9d6ListVz",
  "data": [
    {
      "task_id": "task_xxxx",
      "task_status": "succeed",
      "task_result": {
        "voices": [
          {
            "voice_id": "voice-voicetask-1",
            "voice_name": "demo-cloned",
            "trial_url": "https://api.looprouter.com/voice/voicetask-1.mp3",
            "owned_by": "looprouter"
          }
        ]
      },
      "created_at": 1786372183000,
      "updated_at": 1786372184000
    }
  ]
}
```

## 计费

<Info>
声音复刻**按次计费**（flat）：每次提交按固定单价一次性扣费，无预扣回收、无二次结算，任务失败不额外扣费。单价以控制台「模型广场」与「日志中心」展示为准；实际扣费还会应用 API Key 所在[分组](/user-groups)的计费倍率。
</Info>

与视频任务的「提交预扣、完成结算」两段式计费不同，声音复刻在提交时一次性扣费。详见[能力总览 · 模型定价](/api-capabilities/kling/overview#模型定价)。

## 与数字人联动

复刻成功后拿到的 `voice_id`，可直接作为[数字人](/api-capabilities/kling/video-generation#数字人) `POST /videos/avatar/image2video` 的 `audio_id`，用复刻音色驱动人像说话：

```json
{
  "image": "https://example.com/face.png",
  "audio_id": "voice-voicetask-1",
  "mode": "std"
}
```

<Note>
本渠道不提供文本转语音（TTS，`POST /audio/tts` 返回 `501`）。要「用指定音色说一段话」，请走这里的「声音复刻 → 数字人」组合：先复刻拿到 `voice_id`，再用数字人以该音色驱动人像开口，而非直接合成语音。
</Note>

## 在线调试（试一试）

<CardGroup cols={2}>
  <Card title="提交复刻任务" icon="flask" href="/api-reference/kling/create-voice">
    POST /general/custom-voices
  </Card>
  <Card title="查询复刻任务" icon="flask" href="/api-reference/kling/get-voice">
    GET /general/custom-voices/{task_id}
  </Card>
  <Card title="列出已复刻音色" icon="flask" href="/api-reference/kling/list-voices">
    GET /general/custom-voices
  </Card>
</CardGroup>

## 相关文档

<CardGroup cols={2}>
  <Card title="能力总览与定价" icon="circle-info" href="/api-capabilities/kling/overview">
    模型清单、技术规格、计费规则
  </Card>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/kling/video-generation">
    文 / 图 / Omni / 动作控制 / 数字人生成
  </Card>
</CardGroup>