POST https://mediakit.cn-beijing.volces.com/api/v1/tools/edit-speech

本 API 用于提交一个异步的音频内容编辑任务。上传一段音频或包含有效音频流的视频后，您只需通过自然语言指令（如“把‘喝酒’替换成‘喝茶’”）描述要修改的内容，工具即可自动定位目标片段，生成与原音频音色、情绪、韵律连贯的新语音并无缝替换，同时保持时序基本对齐，无需重录整段。该工具适用于短视频、播客、有声内容、课程及广告等多种场景的口误修正、文案更新与局部改词。当前仅支持中文。

请求参数

参数	类型	是否必选	示例值	描述
Authorization	String	是	Bearer {Your_API_Key}	格式为 Bearer {Your_API_Key}。请参考基础概念及准备工作获取 API Key。

Body 参数

参数	类型	是否必选	示例值	描述
video_url	String	否	https://example.com/your_video.mp4	待编辑视频源 URL。与 audio_url 二选一，必须且只能提供其中一个。视频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式。内容要求：必须包含有效音频流。
audio_url	String	否	https://example.com/your_audio.mp3	待编辑音频源 URL。与 video_url 二选一，必须且只能提供其中一个。音频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp3、m4a、wav、wma、amr、aac、ogg、flac 等主流音频格式。
edits	Array of Object	是	见下方请求示例	编辑任务列表，至少包含 1 项，最多 10 项。每项用一句自然语言描述要修改的内容；包含多项时，系统将按数组顺序依次处理。数组元素结构详见下方 Edit 对象。
media_output_destination	String	否	tos://<您的桶名>	指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶。存储至 VOD：设为 vod://<您的空间名> 存储至 TOS：设为 tos://<您的桶名> 设置本参数后，任务结果中的 url 相关字段将返回形如 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。说明首次使用此功能前，您需要先前往 AI MediaKit 控制台基础配置 > 授权管理页面，授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。更多信息，请参阅开发指南处理产物存储至 VOD 或 TOS。
client_token	String	否	your_unique_request_id_135	用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 可打印字符。不传时不做幂等控制，每次请求均创建新任务。详情请参考幂等性控制。
callback_args	String	否	your_custom_callback_args	自定义回调参数。您提供的内容将在任务完成时，通过事件回调原样返回，方便您关联业务。字段长度最大为 512 字节。不传时回调中不携带自定义参数。
callback_url	String	否	https://example.com/callback	用于接收该任务结果回调的 URL 地址。如提供此参数，其优先级高于控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。不传时使用控制台全局回调地址；若均未配置则不发送回调。请参考事件回调了解回调接收机制和回调消息结构。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考按项目或 API Key 分账。

Edit 对象

edits 数组中每个元素的结构如下：

参数	类型	是否必选	示例值	描述
instruction	String	是	把'喝酒'替换成'喝茶'	自然语言编辑指令。当前仅支持固定“两段式替换”语义，即将音频中出现的原文片段替换为新文案片段。推荐指令格式：把“原文”替换成“新文案” 将“原文”改为“新文案” 编写规范：必须使用中文双引号 “”（或英文双引号 ""）将“原文”和“新文案”分别括起来，以避免歧义与解析失败。 “原文” 与 “新文案” 建议尽量短，建议控制在 10 个汉字以内。修改越短，定位与替换越精准。较长改动建议拆分为多条指令。单条指令长度不超过 200 个字符；当前仅支持中文。效果不佳的写法示例：未加引号：把买耳机吗替换成买十味地黄茶吗过度自定义/带复杂定位描述：对第一句“xxx”里的“xx”替换为“xx” 如同一段“原文”在音频中多次出现，建议配合 search_range 限定搜索时间范围以提升命中准确性。
search_range	Object	否	{"start_time": 5, "end_time": 12}	限定在此时间范围内定位待修改内容，以提升定位精度。当同一段文本在音频中多次出现时，建议设置此参数以确保修改的准确性。不传时，工具在完整音频范围内搜索。结构详见下方 Search range 对象。

Search range 对象

用于限定单条编辑指令的定位范围。

参数	类型	是否必选	示例值	描述
start_time	Number	是	5	搜索起始时间，单位为秒。取值范围为 ≥ 0，且须小于 end_time。
end_time	Number	是	12	搜索结束时间，单位为秒。取值范围为 ≥ 0，且须大于 start_time。

请求示例

以下示例演示了如何提交一个音频内容编辑任务：对一段音频执行两处改词，其中第一处限定在 5~12 秒范围内定位，第二处在完整音频范围内定位。

响应说明

调用 API 提交任务后，接口会立即返回一个同步响应，表明任务是否成功进入后台处理队列。请保存 task_id 用于后续查询。

响应参数

参数	类型	描述
success	Boolean	任务是否成功提交。 true：任务已成功提交到后台处理队列。 false：请求存在错误，任务提交失败。请检查 error 字段以获取详细信息。
task_id	String	任务的唯一标识符。仅在 success 为 true 时返回有效值，用于后续查询任务进度和结果。
request_id	String	本次 API 请求的唯一标识符，可用于问题排查。
error	Object	错误详情对象，仅在 success 为 false 时返回。详见下方 Error 对象。

Error 对象

参数	类型	描述
code	String	具体的错误码。关于各错误码的详细信息，请参阅错误码。
type	String	错误的宏观类型。例如 BadRequest。
message	String	对错误的详细描述，可用于开发调试。
param	String	（可选）指出导致错误的具体参数。

响应示例

成功响应

失败响应

异步任务结果

音频内容编辑是一个异步任务，任务的执行状态和最终结果不会在提交时同步返回。您可以通过以下两种方式获取任务结果：

方法一：使用提交任务时获取的 task_id，定期调用查询任务信息 API，直到 status 字段变为 completed 或 failed。

方法二：在 AI MediaKit 控制台预先配置一个接收回调的 URL，或在提交任务时通过 callback_url 参数为单次任务指定回调地址。任务完成后，系统会将包含最终结果的详细信息 POST 到您指定的地址。详情请参阅事件回调。

当任务成功完成后，您获取到的任务信息中的 result 字段将包含以下内容。输出模态与输入模态一致：视频输入时仅返回 video_url，音频输入时仅返回 audio_url。

参数	类型	示例	描述
video_url	String	https://example.volcvideo.com/edit_speech_output.mp4?auth_key=...	编辑后视频的下载地址，仅视频输入时返回。地址类型根据请求时是否设置 media_output_destination 而不同：默认情况（未设置 media_output_destination）：返回一个 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存。设置 media_output_destination 后：返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。
audio_url	String	https://example.volcvideo.com/edit_speech_output.mp3?auth_key=...	编辑后音频的下载地址，仅音频输入时返回。地址类型根据请求时是否设置 media_output_destination 而不同：默认情况（未设置 media_output_destination）：返回一个 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存。设置 media_output_destination 后：返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。
duration	Number	60.5	计费时长，单位为秒。
input_duration	Number	60.5	输入媒体时长，单位为秒。
edited_duration	Number	3.2	实际编辑的音频时长，单位为秒；编辑多处时为各处求和。

以下是一个任务执行完成后的完整任务信息示例（以音频输入为例）：

AI MediaKit