应用同源版概览 - VMEG Open API

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

流程

上传素材

POST /openapi/v1/app/assets/material/upload/gen-upload-url，PUT 文件，再调 .../upload/complete（大文件用分片接口）。YouTube 视频可不上传，直接传 source.youtubeUrl。

选音色（可选）

调 .../assets/voice/basic/list、.../assets/voice/clone/list，或用 .../task/clone-voice/create 克隆一个。不选时自动克隆原声，和网站默认一致。

创建任务

POST /openapi/v1/app/task/media-translation/create-async，带 X-Idempotency-Key。

查询结果

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

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 参考。参考中链接的指南按独立版编写，步骤相同，把路径前缀换成 /openapi/v1/app 即可。

字段细节

访问与权限

API Key 必须属于某个 VMEG 网站账号，否则返回 401。
声音克隆需要套餐包含克隆权益，否则返回 403。

创建任务

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

素材上传

单文件上传按 fileHash 去重：网站素材库里已有的同一文件会直接返回已有素材。分片上传不去重。

任务结果

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

声音克隆

接口是同步的，直接返回新的 cv_* 音色，可能需要几十秒。
可用 refAudioMaterialId（已上传的素材）代替 refAudio；voiceName 和 sampleText 必填。

​流程

​和独立版的主要不同

​字段细节

流程

和独立版的主要不同

字段细节