克隆并保存音色

curl --request POST 'https://api.voicecheap.ai/v1/actions/voices_clone' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"33333333-3333-4333-8333-333333333333","name":"Studio narrator","samples":[{"fileKey":"uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav"}],"hasPermission":true,"trimToMaxDuration":false}'

const input = {
  requestId: '33333333-3333-4333-8333-333333333333',
  name: 'Studio narrator',
  samples: [
    {
      fileKey: 'uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav',
    },
  ],
  hasPermission: true,
  trimToMaxDuration: false,
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/voices_clone', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.VOICECHEAP_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);

import os
import requests

response = requests.post(
    "https://api.voicecheap.ai/v1/actions/voices_clone",
    headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
    json={"requestId": "33333333-3333-4333-8333-333333333333", "name": "Studio narrator", "samples": [{"fileKey": "uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav"}], "hasPermission": True, "trimToMaxDuration": False},
    timeout=120,
)
body = response.json()
if not response.ok:
    raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)

{
  "data": {
    "requestId": "33333333-3333-4333-8333-333333333333",
    "status": "running",
    "pollAction": "action_request_get",
    "pollAfterSeconds": 5
  },
  "requestId": "33333333-3333-4333-8333-333333333333"
}

{
  "data": {
    "voice": {
      "accent": "original",
      "id": "clone:33333333-3333-4333-8333-333333333333",
      "name": "Studio narrator",
      "previewUrl": "https://files.example.com/saved-narrator.mp3",
      "source": "clone"
    },
    "cloneUsage": {
      "canClone": true,
      "limit": 10,
      "remaining": 9,
      "used": 1
    }
  },
  "requestId": "33333333-3333-4333-8333-333333333333"
}

{
  "data": {
    "requestId": "33333333-3333-4333-8333-333333333333",
    "operation": "voices_clone",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "status": "running",
    "pollAfterSeconds": 5
  },
  "requestId": "33333333-3333-4333-8333-333333333333"
}

{
  "data": {
    "requestId": "33333333-3333-4333-8333-333333333333",
    "operation": "voices_clone",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "status": "completed",
    "resultStored": false,
    "message": "The action completed. Retrieve its output from the corresponding history or resource action."
  },
  "requestId": "33333333-3333-4333-8333-333333333333"
}

POST

actions

voices_clone

curl --request POST 'https://api.voicecheap.ai/v1/actions/voices_clone' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"33333333-3333-4333-8333-333333333333","name":"Studio narrator","samples":[{"fileKey":"uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav"}],"hasPermission":true,"trimToMaxDuration":false}'

const input = {
  requestId: '33333333-3333-4333-8333-333333333333',
  name: 'Studio narrator',
  samples: [
    {
      fileKey: 'uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav',
    },
  ],
  hasPermission: true,
  trimToMaxDuration: false,
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/voices_clone', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.VOICECHEAP_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);

import os
import requests

response = requests.post(
    "https://api.voicecheap.ai/v1/actions/voices_clone",
    headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
    json={"requestId": "33333333-3333-4333-8333-333333333333", "name": "Studio narrator", "samples": [{"fileKey": "uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav"}], "hasPermission": True, "trimToMaxDuration": False},
    timeout=120,
)
body = response.json()
if not response.ok:
    raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)

{
  "data": {
    "requestId": "33333333-3333-4333-8333-333333333333",
    "status": "running",
    "pollAction": "action_request_get",
    "pollAfterSeconds": 5
  },
  "requestId": "33333333-3333-4333-8333-333333333333"
}

{
  "data": {
    "voice": {
      "accent": "original",
      "id": "clone:33333333-3333-4333-8333-333333333333",
      "name": "Studio narrator",
      "previewUrl": "https://files.example.com/saved-narrator.mp3",
      "source": "clone"
    },
    "cloneUsage": {
      "canClone": true,
      "limit": 10,
      "remaining": 9,
      "used": 1
    }
  },
  "requestId": "33333333-3333-4333-8333-333333333333"
}

{
  "data": {
    "requestId": "33333333-3333-4333-8333-333333333333",
    "operation": "voices_clone",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "status": "running",
    "pollAfterSeconds": 5
  },
  "requestId": "33333333-3333-4333-8333-333333333333"
}

{
  "data": {
    "requestId": "33333333-3333-4333-8333-333333333333",
    "operation": "voices_clone",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "status": "completed",
    "resultStored": false,
    "message": "The action completed. Retrieve its output from the corresponding history or resource action."
  },
  "requestId": "33333333-3333-4333-8333-333333333333"
}

使用 1–3 个当前账户拥有的已上传音频克隆并保存自定义音色。必须获得明确授权。样本总时长必须为 10–120 秒，且每个文件不超过 20 MB。套餐音色数量限制仍适用。

POST https://api.voicecheap.ai/v1/actions/voices_clone

身份验证和权限

string

必填

在此请求头中发送 VoiceCheap API 密钥。也支持通过 Authorization: Bearer 发送同一 API 密钥。OAuth 访问令牌仅适用于 MCP，此 REST 端点不接受 OAuth 访问令牌。

所需权限: voices:write. 需要有效的付费订阅。权限不会改变团队角色、资源归属、媒体额度或套餐限制。

参数

string

在传输层可选：如果省略，服务器会在验证前注入标识符。请自行提供稳定的 UUID v4，以便在响应丢失后安全恢复。格式: “uuid”. 匹配模式: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$.

string

必填

文本值。最小长度: 1. 最大长度: 80.

array

必填

值列表。项目结构请参阅完整输入架构。最少项目数: 1. 最多项目数: 3.

boolean

必填

请确认你有权克隆每个样本中人物的音色。指定值: true.

boolean

布尔值。默认值: false.

string

文本值。最大长度: 35. 匹配模式: ^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$.

完整输入架构

以下 JSON Schema 保留了发现接口公开的确切字段名、嵌套类型、默认值、范围和可接受值。其他跨字段规则列于操作说明中。

{
  "type": "object",
  "properties": {
    "requestId": {
      "description": "UUID v4 for this action. Reuse the same ID with identical arguments on retries.",
      "type": "string",
      "format": "uuid",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "samples": {
      "minItems": 1,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fileKey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1024,
            "description": "An uploaded audio fileKey returned by voices_upload_complete for this account."
          }
        },
        "required": ["fileKey"],
        "additionalProperties": false
      }
    },
    "hasPermission": {
      "type": "boolean",
      "const": true,
      "description": "Confirm that you have permission to clone the person whose voice is in every sample."
    },
    "trimToMaxDuration": {
      "default": false,
      "type": "boolean"
    },
    "language": {
      "type": "string",
      "maxLength": 35,
      "pattern": "^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$"
    }
  },
  "required": ["name", "samples", "hasPermission"],
  "additionalProperties": false
}

幂等性

为每次修改操作在 requestId 或 Idempotency-Key HTTP 请求头中提供 UUID v4。网络故障后，请使用相同标识符和完全相同的参数重试。如果同时提供这两个值，它们必须一致。重放已保存的请求不会重复执行操作，也不会再次扣除月度调用次数。失败或中断的请求不会自动重新执行。对于每次修改操作，如果重试时发现同一请求仍在运行，即使首次执行通常为同步操作，也可能返回 HTTP 202。如果执行已完成但 resultStored 为 false，重试会返回 HTTP 200 和已保存的请求状态，而非原始结果。请通过对应领域的历史记录、结果或下载操作获取输出。

请求示例

请将示例资源标识符和媒体键替换为账户返回的值。重试同一次修改操作时，请保持请求标识符不变。

curl --request POST 'https://api.voicecheap.ai/v1/actions/voices_clone' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"33333333-3333-4333-8333-333333333333","name":"Studio narrator","samples":[{"fileKey":"uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav"}],"hasPermission":true,"trimToMaxDuration":false}'

const input = {
  requestId: '33333333-3333-4333-8333-333333333333',
  name: 'Studio narrator',
  samples: [
    {
      fileKey: 'uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav',
    },
  ],
  hasPermission: true,
  trimToMaxDuration: false,
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/voices_clone', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.VOICECHEAP_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);

import os
import requests

response = requests.post(
    "https://api.voicecheap.ai/v1/actions/voices_clone",
    headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
    json={"requestId": "33333333-3333-4333-8333-333333333333", "name": "Studio narrator", "samples": [{"fileKey": "uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav"}], "hasPermission": True, "trimToMaxDuration": False},
    timeout=120,
)
body = response.json()
if not response.ok:
    raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)

响应

此操作在运行期间返回 HTTP 202。请保存 requestId，并使用该标识符和原始操作名称轮询 action_request_get。轮询状态包括 running、completed、failed 和 interrupted。已完成的结果可能指向独立的媒体任务；请继续使用该操作对应的状态或输出操作。已保存且可重复使用的自定义 TTS 音色，以及更新后的保存槽位限额。

{
  "data": {
    "requestId": "33333333-3333-4333-8333-333333333333",
    "status": "running",
    "pollAction": "action_request_get",
    "pollAfterSeconds": 5
  },
  "requestId": "33333333-3333-4333-8333-333333333333"
}

{
  "data": {
    "voice": {
      "accent": "original",
      "id": "clone:33333333-3333-4333-8333-333333333333",
      "name": "Studio narrator",
      "previewUrl": "https://files.example.com/saved-narrator.mp3",
      "source": "clone"
    },
    "cloneUsage": {
      "canClone": true,
      "limit": 10,
      "remaining": 9,
      "used": 1
    }
  },
  "requestId": "33333333-3333-4333-8333-333333333333"
}

{
  "data": {
    "requestId": "33333333-3333-4333-8333-333333333333",
    "operation": "voices_clone",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "status": "running",
    "pollAfterSeconds": 5
  },
  "requestId": "33333333-3333-4333-8333-333333333333"
}

{
  "data": {
    "requestId": "33333333-3333-4333-8333-333333333333",
    "operation": "voices_clone",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "status": "completed",
    "resultStored": false,
    "message": "The action completed. Retrieve its output from the corresponding history or resource action."
  },
  "requestId": "33333333-3333-4333-8333-333333333333"
}

结果字段

字段	说明
`data.voice.id`	可复用的 TTS 选择 ID 为 clone:<UUID>。tts_generate 使用完整值，voices_delete 仅使用 UUID。
`data.voice.name`	已保存音色的显示名称。
`data.voice.accent`	已保存的自定义音色使用 original。
`data.voice.source`	已保存的自定义音色使用 clone。
`data.voice.previewUrl`	已保存音色的临时音频预览 URL。
`data.cloneUsage.canClone`	当前套餐是否允许保存自定义 TTS 音色；请检查 remaining 了解可用名额。
`data.cloneUsage.limit`	套餐允许保存的自定义 TTS 音色槽位限额。
`data.cloneUsage.used`	已占用的 TTS 音色名额，包括已预留的创建操作。
`data.cloneUsage.remaining`	可用的已保存 TTS 音色槽位。

恢复并轮询此请求

即使连接丢失，也应使用同一标识符。如果 resultStored 为 false，请通过相应的历史记录、结果或下载操作获取输出。切勿仅为查看进度而启动第二次生成。

curl --request POST 'https://api.voicecheap.ai/v1/actions/action_request_get' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"33333333-3333-4333-8333-333333333333","operation":"voices_clone"}'

HTTP 200

{
  "data": {
    "requestId": "33333333-3333-4333-8333-333333333333",
    "operation": "voices_clone",
    "status": "completed",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "resultStored": true,
    "result": {
      "voice": {
        "accent": "original",
        "id": "clone:33333333-3333-4333-8333-333333333333",
        "name": "Studio narrator",
        "previewUrl": "https://files.example.com/saved-narrator.mp3",
        "source": "clone"
      },
      "cloneUsage": {
        "canClone": true,
        "limit": 10,
        "remaining": 9,
        "used": 1
      }
    }
  }
}

操作说明

为此写入操作使用 UUID v4 格式的 requestId，重试时使用相同参数复用该 ID。长时间运行的操作首先返回 running 请求；此示例是可通过 action_request_get 获取的已完成处理程序结果。
上传 1–3 个当前账户拥有的音频样本，并使用其已完成上传的 fileKey 值。支持的样本格式为 MP3、WAV、M4A、OGG 和 Opus；每个文件必须非空，且最大为 20 MiB（20,971,520 字节）。远程 URL 和其他账户的上传文件均会被拒绝。
样本的可读取音频总时长必须至少为 10 秒，最多为 120 秒。trimToMaxDuration 默认为 false；设为 true 可按比例裁剪总时长超过 120 秒的样本。
hasPermission 必须为 JSON 布尔值 true，以确认每个样本均已获授权。字符串值（如 “true”）会被拒绝。
name 去除首尾空白后必须包含 1–80 个字符。可选的 language 支持 2–3 个字母的代码，可带子标签，最长为 35 个字符。
此操作会直接保存克隆音色，并占用一个已保存 TTS 音色名额。它不会消耗一次性的克隆预览试用限额。
请在 tts_generate 中使用返回的 voice.id。对于直接克隆，其 UUID 即为 requestId；voices_delete 接受该 UUID，不带 clone: 前缀。
接受的 language 字段不会改变直接保存克隆音色的工作流。需要特定语言的预览脚本时，请选择 voices_preview_clone。
语音历史记录和自定义音色归已认证账户所有。使用团队计费并不授予访问其他成员语音或音色的权限。

用量

每次成功调用消耗一次月度 API/MCP 调用额度。媒体额度和操作本身的生成限额也适用。

错误

HTTP 状态	代码	含义或恢复方式
400	`CREDENTIAL_IN_QUERY`	凭证通过 access_token 或 api_key 查询参数提供。请在标头中发送凭证。
400	`IDEMPOTENCY_CONFLICT`	Idempotency-Key 请求头必须与请求体中的 requestId 字段一致。
400	`INVALID_REQUEST_ID`	请在 requestId 或 Idempotency-Key 中提供 UUID v4。
400	`VALIDATION_ERROR`	输入不符合操作架构；请查看 details 了解字段错误。
400	`VOICE_CLONE_INVALID_AUDIO`	某个已上传样本无法读取到大于零的音频时长。
400	`VOICE_CLONE_INVALID_FILE_SIZE`	已存储的样本为空或超过 20 MiB。
400	`VOICE_CLONE_INVALID_FILE_TYPE`	某个样本不是 MP3、WAV、M4A、OGG 或 Opus 音频。
400	`VOICE_CLONE_SAMPLE_TOO_LONG`	样本合计超过 120 秒，且未启用裁剪。
400	`VOICE_CLONE_SAMPLE_TOO_SHORT`	样本合计音频时长不足 10 秒。
400	`VOICE_SAMPLE_NOT_OWNED`	某个样本键不安全或不属于通过身份验证的账户。
401	`API_KEY_EXPIRED`	API 密钥已过期。
401	`INVALID_API_KEY`	请提供有效且未过期的 API 密钥。
401	`INVALID_CREDENTIAL`	Authorization 标头格式错误或与 x-api-key 冲突。
401	`MISSING_CREDENTIAL`	未提供可用的请求头凭据，或其长度超过 4096 个字符。
401	`USER_NOT_FOUND`	该凭据对应的账户已不存在。
403	`ACCOUNT_UNAVAILABLE`	调用者账户或计费账户不可用，或正在删除。
403	`AMBIGUOUS_TEAM_API_KEY`	此凭据对应的用户属于多个团队，因此计费上下文不明确。
403	`INSUFFICIENT_SCOPE`	请授予全部所需权限，或选择其他凭据。
403	`INTEGRATION_PLAN_UNSUPPORTED`	无法验证该账户的集成限制。
403	`SUBSCRIPTION_REQUIRED`	请使用有效的付费订阅。
403	`TEAM_OWNER_NOT_FOUND`	找不到实际生效的团队所有者账户。
403	`VOICE_CLONING_REQUIRES_PAID_PLAN`	当前套餐不允许保存自定义 TTS 音色。
404	`VOICE_CLONE_NOT_FOUND`	该克隆请求不属于已认证账户，或已不可用。
409	`CONCURRENT_ACTION_LIMIT_REACHED`	此账户已有 10 个集成操作正在运行。请先轮询现有请求，再启动另一个操作。
409	`IDEMPOTENCY_CONFLICT`	只有操作和参数完全相同时，才能复用标识符。
409	`VOICE_CLONE_IN_PROGRESS`	使用此 requestId 的克隆音色仍在创建中。
409	`VOICE_CLONE_LIMIT_REACHED`	所有可保存的自定义 TTS 音色名额均已占用。
409	`VOICE_CREATION_IN_PROGRESS`	账户删除流程运行期间，音色更改会被阻止。
429	`INTEGRATION_MONTHLY_LIMIT_REACHED`	请等待月度额度重置，或更改套餐。
429	`INTEGRATION_RATE_LIMIT_REACHED`	如果提供了 Retry-After，请等待其指定的时间，并采用退避重试。
500	`INTERNAL_ERROR`	在决定是否重试修改操作前，请检查已保存的请求状态和资源历史记录。
502	`INTERNAL_ERROR`	无法完成操作或确认其结果。启动另一次生成前，请检查请求状态和资源历史记录。
503	`ACTION_RESULT_UNAVAILABLE`	操作已执行，但未能保存结果。在启动新的生成前，请检查已保存的请求状态和资源历史记录。
503	`SERVER_RESTARTING`	服务器正在重启。请稍后重试；对于修改操作，请保持请求标识符不变。

{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This credential does not permit the requested action.",
  "status": 403,
  "details": {
    "requiredScopes": ["voices:write"]
  }
}

概述

发现接口

账户

用量和活动

设置和通知

团队

项目

翻译和配音

转写文本和编辑

文本转语音

语音音色

配音音色

转写

字幕

图像

缩略图

文件夹

术语表

Webhook

发布

请求状态

OAuth 和 MCP 协议

身份验证和权限

参数

幂等性

请求示例

响应

结果字段

恢复并轮询此请求

操作说明

用量

错误

​身份验证和权限

​参数

​幂等性

​请求示例

​响应

​结果字段

​恢复并轮询此请求

​操作说明

​用量

​错误

身份验证和权限

参数

幂等性

请求示例

响应

结果字段

恢复并轮询此请求

操作说明

用量

错误