> ## 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.

# 应用同源版概览

> 用 API 提交翻译任务，在 VMEG 网站继续编辑和导出

应用同源版 API 创建的任务、上传的素材和克隆的音色都在你的 VMEG 网站账号里：任务出现在**我的任务**，可以在编辑器里继续调整并重新导出。还没决定用哪套 API？先看[独立版与应用同源版](/zh/guides/choose-api)。

## 流程

<Steps>
  <Step title="上传素材">
    `POST /openapi/v1/app/assets/material/upload/gen-upload-url`，PUT 文件，再调 `.../upload/complete`（大文件用分片接口）。YouTube 视频可不上传，直接传 `source.youtubeUrl`。
  </Step>

  <Step title="选音色（可选）">
    调 `.../assets/voice/basic/list`、`.../assets/voice/clone/list`，或用 `.../task/clone-voice/create` 克隆一个。不选时自动克隆原声，和网站默认一致。
  </Step>

  <Step title="创建任务">
    `POST /openapi/v1/app/task/media-translation/create-async`，带 `X-Idempotency-Key`。
  </Step>

  <Step title="查询结果">
    轮询 `GET /openapi/v1/app/tasks/detail?taskId=...`，直到 `status` 为 `finished` 或 `failed`。最新成片在 `result.outputs[0]`；打开 `editorUrl` 可继续编辑并重新导出。
  </Step>
</Steps>

```bash theme={null}
curl -X POST "https://api.vmeg.ai/openapi/v1/app/task/media-translation/create-async" \
  -H "Authorization: Bearer $VMEG_API_KEY" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "vt",
    "source": { "materialId": "YOUR_MATERIAL_ID" },
    "language": { "target": "en-US" },
    "title": "产品演示（英文）"
  }'
```

## 和独立版的主要不同

* **需要网站账号的 API Key**：在 VMEG 网站创建的 Key 才能调用，任务按网站积分计费。
* **没有 Webhook**：结果靠轮询获取。任务状态与网站一致，请为轮询设置超时；长时间停在 `running` 时，带上 `taskId` 联系客服。
* **结果会更新**：在网站重新导出后，任务会回到 `running`，新成片排在 `result.outputs[0]`，旧成片仍保留。
* **选项与网站翻译表单一致**：烧录字幕用字幕模板，默认不烧录；唇形同步要求视频不低于 360p。暂不支持字幕擦除和画面翻译。
* **素材与网站共享**：同一文件会复用网站上已有的素材，在 API 里删除素材，网站**我的资产**里也会消失。

完整字段见 [API 参考](/zh/api-reference/app-synced/media-translation/create-media-translation-async)。参考中链接的指南按独立版编写，步骤相同，把路径前缀换成 `/openapi/v1/app` 即可。

## 字段细节

<AccordionGroup>
  <Accordion title="访问与权限">
    * API Key 必须属于某个 VMEG 网站账号，否则返回 `401`。
    * 声音克隆需要套餐包含克隆权益，否则返回 `403`。
  </Accordion>

  <Accordion title="创建任务">
    * `options` 可省略，默认等同网站上自动克隆音色的任务。
    * `source` 需在 `materialId` 与 `youtubeUrl` 中二选一。`taskType` 必须与素材一致：视频用 `vt`，音频用 `at`。
    * `title` 设置**我的任务**中显示的任务名，不传时取文件名或 YouTube 视频标题。
    * 可选的字幕文件（`source.subtitleMaterialId`、`source.targetSubtitleMaterialId`）必须是 `.srt` 素材。
    * `options.voiceClone.style` 额外支持 `auto`、`tutorial`、`drama`、`smart`。
    * 手动选音色（`voiceSpeakers.selectedVoicesList`）支持 `sv_*` 系统音色和[克隆音色列表](/zh/api-reference/app-synced/assets/voices/list-cloned-voices)中的 `cv_*` 音色；不能与 `voiceClone` 同时传，`dubbingVersion: V2` 也不能与这两者同时使用。
    * 烧录字幕用 `options.subtitle`（`type` 加可选的 `templateId`，模板来自[字幕模板列表](/zh/api-reference/app-synced/media-translation/list-subtitle-templates)），替代 `options.text`。只传 `type` 不传 `templateId` 时使用网站默认样式。
    * `options.lipsync` 要求视频宽、高均不低于 360 像素，否则返回 `400`。YouTube 来源不做预校验。
    * 传 `source.sourceUrl`、`options.text`、`output`、`extraData` 或素材列表的 `mimeType` 过滤返回 `400`。其他未知字段会被忽略。
  </Accordion>

  <Accordion title="素材上传">
    * 单文件上传按 `fileHash` 去重：网站素材库里已有的同一文件会直接返回已有素材。分片上传不去重。
  </Accordion>

  <Accordion title="任务结果">
    * 受理响应和任务详情包含 `editorUrl`。
    * `result.outputs` 按时间倒序，`result.outputs[0]` 是最近一次成功导出的成片。
    * `finished` 不是最终状态：重新导出会把任务置回 `running`，导出失败则变为 `failed`，之前的成片仍保留在列表中。
  </Accordion>

  <Accordion title="声音克隆">
    * 接口是同步的，直接返回新的 `cv_*` 音色，可能需要几十秒。
    * 可用 `refAudioMaterialId`（已上传的素材）代替 `refAudio`；`voiceName` 和 `sampleText` 必填。
  </Accordion>
</AccordionGroup>