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

流程

1

上传素材

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

选音色(可选)

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

创建任务

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

查询结果

配置了 Webhook 时,VMEG 会把首次结果 POST 到你的地址;否则轮询 GET /openapi/v1/app/tasks/detail?taskId=...,直到 status 为 finished 或 failed。最新成片在 result.outputs[0];打开 editorUrl 可继续编辑并重新导出。

转写

转写任务的流程相同:上传素材(或使用 YouTube 链接)、创建任务、获取结果。任务可在网站转写编辑器中打开,下载的转写稿始终是编辑器里的最新版本。
1

创建任务

POST /openapi/v1/app/task/transcription/create-async,带 X-Idempotency-Key。source.materialId(音频或视频)与 source.youtubeUrl 二选一,并传 language.source。
2

等待完成

通过 Webhook(data.taskType 为 transcription)或轮询 GET /openapi/v1/app/tasks/detail?taskId=...。status 为 finished 时会返回 result.srtEndpoint。
3

下载转写稿

GET /openapi/v1/app/tasks/transcription/srt?taskId=... 返回 SRT 文本。加 speakers=true 会带 [Speaker N] 标签;加 format=json 返回带毫秒时间的句段。
4

翻译(可选)

POST /openapi/v1/app/tasks/transcription/translate,传 { "taskId": "...", "targetLanguage": "en-US" }。任务详情里 result.translation.status 为 finished 后,加 content=translation 下载译文。

混合语言录音转成英文

一段录音里切换多种语言时,把说到的语言都传进 language.source。任务会使用多语言转写(对应网站的多语言模式),每句保留原本说的语言。再把整段对话翻译成英文,英文每句的起止时间和说话人与原文一致。

和独立版的主要不同

  • 需要网站账号的 API Key:在 VMEG 网站创建的 Key 才能调用,任务按网站积分计费。
  • Webhook 只推首次结果:任务第一次进入 finished 或 failed 时,向与独立版相同的 Webhook 地址推送一次;之后在网站重新导出不再推送,需要时请轮询。不配置 Webhook 时靠轮询获取结果,请设置超时;长时间停在 running 时,带上 taskId 联系客服。
  • 结果会更新:在网站重新导出后,任务会回到 running,新成片排在 result.outputs[0],旧成片仍保留。
  • 转写仅应用同源版提供:独立版没有转写接口。
  • 选项与网站翻译表单一致:烧录字幕用字幕模板,默认不烧录;唇形同步要求视频不低于 360p。暂不支持字幕擦除和画面翻译。
  • 素材与网站共享:同一文件会复用网站上已有的素材,在 API 里删除素材,网站我的资产里也会消失。
完整字段见 API 参考。参考中链接的指南按独立版编写,步骤相同,把路径前缀换成 /openapi/v1/app 即可。

字段细节

  • API Key 必须属于某个 VMEG 网站账号,否则返回 401。
  • 声音克隆需要套餐包含克隆权益,否则返回 403。
  • options 可省略,默认等同网站上自动克隆音色的任务。
  • source 需在 materialId、youtubeUrl、sourceUrl 中三选一。sourceUrl 是可公开访问的 HTTPS 直链(CDN 或公开 S3),接口立即返回任务并在后台下载。账号不够 1 分钟时直接返回 402;探测出时长后仍不够,任务变为 failed,Webhook 的 code 为 402,message 为 insufficient quota。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 来源不做预校验。
  • 传 options.text、output、extraData 或素材列表的 mimeType 过滤返回 400。其他未知字段会被忽略。
  • 单文件上传按 fileHash 去重:网站素材库里已有的同一文件会直接返回已有素材。分片上传不去重。
  • 受理响应和任务详情包含 editorUrl。
  • result.outputs 按时间倒序,result.outputs[0] 是最近一次成功导出的成片。
  • finished 不是最终状态:重新导出会把任务置回 running,导出失败则变为 failed,之前的成片仍保留在列表中。
  • source 需在 materialId(音频或视频素材,其他类型返回 400)与 youtubeUrl 中二选一。传 sourceUrl、output、extraData 返回 400。
  • language.source 必填:传一个语言代码;传 auto 自动识别语言;或传多个代码(数组或逗号分隔,最多 10 个)对混合语言音频做多语言转写。auto 不能和其他代码一起传;与网站一致,多语言转写需要 options.asr.quality 为 standard。title 可选,不传时取文件名或 YouTube 视频标题。
  • options.asr.quality 为 standard(默认)或 quick;options.speakers 为 auto(默认)或正整数,如 "2"。其他值返回 400。
  • 用 taskType=transcription 列出转写任务。转写任务的 result.outputs 为空;status 为 finished 后,result.srtEndpoint 为下载路径(https://api.vmeg.ai 上的相对路径,用同一个 API Key 调用)。运行中、失败的任务以及翻译任务不返回该字段。
  • 转写稿为网站编辑器中的最新版本,包含你的修改。SRT(application/x-subrip)以纯文本返回;format=json 时在常规 JSON 结构中返回 data.segments(index、毫秒 start / end、text、speaker)。
  • 出错时返回 JSON 结构,HTTP 状态为 200:400 为 format、speakers、content 不合法或缺少 taskId;404 为不是你账号下的转写任务;409 为尚未完成,或 content=translation 时还没有完成的译文。请不要设置 Accept 请求头,或设为 Accept: */*。
  • 翻译:POST /openapi/v1/app/tasks/transcription/translate 把整篇转写稿翻译成一种 targetLanguage,与网站编辑器的翻译按钮相同。每个任务只有一种目标语言:已有译文时请求其他语言返回 409,请求同一语言会重新翻译并覆盖之前的译文。积分余额不足返回 402。
  • 已完成的转写任务详情包含 result.translation(status 为 none、running 或 finished,以及 targetLanguage)。译文用 content=translation 下载,时间和说话人与原文相同。JSON 格式不会在一次响应里同时返回原文和译文,请分别用 content=source 和 content=translation 下载。
  • 时间戳为句级,精确到毫秒,暂不提供词级时间戳。
  • 使用网站 API 配置页里的 Webhook 地址和密钥,与独立版共用。验签方式见 Webhook 签名校验。
  • 所有应用同源版任务(包括转写)的 event 都是 openapi-app-media-translation,请用 data.taskType(vt、at 或 transcription)区分。pipelineKey 为 openapi-app-{taskId}。
  • 转写任务完成时,data.result.srtEndpoint 为转写稿下载路径,data.result.translation 为翻译状态(此时通常为 none)。翻译进度不通过 Webhook 推送,请轮询任务详情。
  • data 字段与查询任务状态一致(taskId、taskType、status、editorUrl、result)。
  • 任务完成时 code 为 200,失败时为 500,失败原因在 message 中。
  • 每个任务只推一次,对应它第一次进入 finished 或 failed。投递失败会在约 40 分钟内重试几次,之后请改为轮询。请按 pipelineKey 去重。
  • 不支持 extraData,该字段始终为空。
  • 接口是同步的,直接返回新的 cv_* 音色,可能需要几十秒。
  • 可用 refAudioMaterialId(已上传的素材)代替 refAudio;voiceName 和 sampleText 必填。