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

# 音视频翻译

> 异步视频与音频本地化

export const apiKeyUrl = "https://www.vmeg.ai/open-api-setting";

对已上传视频或音频执行完整的 **翻译配音** 流水线：语音识别、文稿翻译、AI 配音（克隆或预设音色）与渲染输出。可选字幕与口型同步。**仅异步** — 配音文件通过 [Webhook](/zh/guides/webhooks) 投递。

<Info>
  本接口会在目标语言下 **重新配音** 你的媒体。它不是纯文本翻译，也不会只返回字幕 — 你会得到新的配音视频或音频文件。
</Info>

## 任务类型

| 请求 `taskType` | 含义   |
| ------------- | ---- |
| `vt`          | 视频翻译 |
| `at`          | 音频翻译 |

若请求 `at` 但素材为视频，服务端可能按 **视频翻译（`vt`）** 执行。请以受理响应与 Webhook 中的 `taskType` 为准。

## 流程

<Steps>
  <Step title="上传素材">
    走完完整的 [素材上传](/zh/guides/assets/material-upload) 流程（含 complete / 瞬时上传）后，再使用已注册的 `materialId`
  </Step>

  <Step title="配置 Webhook">
    在 <a href={apiKeyUrl}>API 配置</a> 设置 Webhook URL，并复制页面展示的 Secret 用于验签
  </Step>

  <Step title="提交任务">
    `POST /openapi/v1/task/media-translation/create-async`，携带 `X-Idempotency-Key`
  </Step>

  <Step title="接收结果">
    `event` 为 `openapi-media-translation` 的 [Webhook 请求体](/zh/guides/webhook-request)
  </Step>
</Steps>

## 请求概要

必填包括 `taskType`、`source.materialId`、`language`（源/目标 locale）、`options`（配音、ASR、翻译等）。

`source.materialId` 必须来自 **已走完完整流程** 的 [素材上传](/zh/guides/assets/material-upload)（或上传成功后的 [素材列表](/zh/guides/assets/materials)）。不要使用仅出现在 gen-upload-url / 分片发起响应中的进行中 `materialId`。

区域代码见 [支持的语言](/zh/guides/supported-languages)。完整 `options` 树见 [创建媒体翻译（异步）](/api-reference/media-translation/create-media-translation-async) 的请求体。

## 响应

* **HTTP Response**（立即）：受理信息 — `taskId`、`status`、`createdAt`、实际 `taskType`
* **Webhook**（完成时）：`data.result` 中的交付物 CDN URL

不要在 `create-async` 的 HTTP 响应中等待最终音视频 URL。

## Webhook 结果中的音色字段

翻译脚本逐句结果与逐句 TTS 结果可能包含 **`voiceId`** 与 **`provider`**。请 **原样复制** API 返回值，不要自行拼接或猜测。

| 字段         | 含义                                     |
| ---------- | -------------------------------------- |
| `voiceId`  | 稳定音色 ID（预设为 `sv_…`，克隆为 `cv_…`）         |
| `provider` | 该句对应的预设档位（`S1`、`S2`、…）或克隆引擎（`V1`–`V5`） |

若支持用户改句并再次提交，**请成对保存并回传 `voiceId` 与 `provider`**。见 [音色](/zh/guides/assets/voices)。

## 任务管理

可轮询 `GET /openapi/v1/tasks/detail` 作为兜底。见 [产品概览](/zh/guides/products/overview)。