Workflow
1
Upload
POST /openapi/v1/app/assets/material/upload/gen-upload-url, PUT the file, then .../upload/complete (or the multipart endpoints for large files). For YouTube videos, skip upload and pass source.youtubeUrl.2
Pick voices (optional)
List
.../assets/voice/basic/list and .../assets/voice/clone/list, or clone one with .../task/clone-voice/create. Without a choice, the original voices are cloned automatically, as on the website.3
Create the job
POST /openapi/v1/app/task/media-translation/create-async with X-Idempotency-Key.4
Get the result
With a webhook configured, VMEG POSTs the first result to your URL. Otherwise poll
GET /openapi/v1/app/tasks/detail?taskId=... until status is finished or failed. The latest output is result.outputs[0]; open editorUrl to keep editing and re-export.Transcription
Transcription jobs follow the same pattern: upload (or use a YouTube link), create the job, then get the result. The job opens in the website transcription editor, and the transcript you download always reflects the latest edits there.1
Create the job
POST /openapi/v1/app/task/transcription/create-async with X-Idempotency-Key. Pass exactly one of source.materialId (audio or video) or source.youtubeUrl, plus language.source.2
Wait for it to finish
Use the webhook (
data.taskType is transcription) or poll GET /openapi/v1/app/tasks/detail?taskId=.... When status is finished, result.srtEndpoint is set.3
Download the transcript
GET /openapi/v1/app/tasks/transcription/srt?taskId=... returns SRT text. Add speakers=true for [Speaker N] labels, or format=json for segments with millisecond times.4
Translate (optional)
POST /openapi/v1/app/tasks/transcription/translate with { "taskId": "...", "targetLanguage": "en-US" }. When result.translation.status in the job detail is finished, download the translation with content=translation.Mixed-language recordings to English
For a recording that switches between languages, pass every spoken language inlanguage.source. The job uses multilingual transcription (the website’s multi-language mode), so each line stays in the language it was spoken in. Then translate the whole conversation into English. The English lines keep the original start/end times and speaker labels.
Key differences from the Standalone API
- Website account key — only API keys created on the VMEG website work, and jobs use website credits.
- Webhook for the first result only — the job’s first
finishedorfailedis delivered once to the same webhook URL as the Standalone API; re-exports on the website are not delivered, so poll if you need them. Without a webhook, poll and set a timeout; if a job staysrunningfar longer than usual, contact support with thetaskId. - Results can change — re-exporting on the website sets the job back to
runningand puts the new output atresult.outputs[0]; earlier outputs stay in the list. - Transcription is App-Synced only — the Standalone API has no transcription endpoint.
- Options match the website form — burned-in subtitles use subtitle templates and are off by default; lip sync needs at least 360p video. Subtitle removal and on-screen text translation are not supported yet.
- Materials are shared with the website — the same file reuses the existing website material, and deleting a material through the API also removes it from My assets.
/openapi/v1/app prefix.
Field details
Access
Access
- The API key must belong to a VMEG website account; other keys get
401. - Voice cloning requires a plan with voice cloning; otherwise
403.
Creating a job
Creating a job
optionsis optional; defaults match a website job with automatic voice cloning.sourceaccepts exactly one ofmaterialId,youtubeUrl, orsourceUrl(a public HTTPS file URL such as CDN or public S3).sourceUrlreturns a task immediately and downloads in the background. If the account cannot cover one minute, the request returns402. If the probed duration costs more than the remaining credits, the task becomesfailedand the webhook uses402with messageinsufficient quota.taskTypemust match the material:vtfor video,atfor audio.titlesets the job name in My tasks; it defaults to the file name or YouTube video title.- Optional subtitle files (
source.subtitleMaterialId,source.targetSubtitleMaterialId) must be.srtmaterials. options.voiceClone.stylealso acceptsauto,tutorial,drama, andsmart.- Manual voice picking (
voiceSpeakers.selectedVoicesList) acceptssv_*system voices andcv_*voices from List cloned voices. It cannot be combined withvoiceClone, anddubbingVersion: V2cannot be combined with either. - Burned-in subtitles use
options.subtitle(typeplus an optionaltemplateIdfrom List subtitle templates) instead ofoptions.text. Withtypebut notemplateId, the website’s default style is used. options.lipsyncrequires a video of at least 360 × 360 px; lower resolutions return400. YouTube sources are not pre-checked.options.text,output,extraData, and the materialmimeTypefilter return400. Other unknown fields are ignored.
Uploading materials
Uploading materials
- Single-file uploads are de-duplicated by
fileHash: a file already in your website library returns the existing material. Multipart uploads are not de-duplicated.
Results
Results
- The acceptance response and job detail include
editorUrl. result.outputsis newest first;result.outputs[0]is the latest successful render.finishedis not permanent: re-exporting sets the job back torunning, and a failed re-export ends infailedwhile earlier outputs stay in the list.
Transcription
Transcription
sourceaccepts exactly one ofmaterialId(an audio or video material; other types return400) oryoutubeUrl.sourceUrl,output, andextraDatareturn400.language.sourceis required: one language code,autoto detect the language, or several codes (array or comma-separated, up to 10) for multilingual transcription of mixed-language audio.autocannot be combined with other codes, and multilingual transcription requiresoptions.asr.qualitystandard, as on the website.titleis optional and defaults to the file name or YouTube video title.options.asr.qualityisstandard(default) orquick;options.speakersisauto(default) or a positive integer such as"2". Other values return400.- List jobs with
taskType=transcription. Transcription jobs have emptyresult.outputs; oncestatusisfinished,result.srtEndpointholds the download path (a relative path onhttps://api.vmeg.ai, called with the same API key). It is absent for running or failed jobs and for translation jobs. - The transcript is the latest version in the website editor, including your edits. SRT (
application/x-subrip) is returned as plain text;format=jsonreturnsdata.segments(index,start,endin milliseconds,text,speaker) in the usual JSON envelope. - Errors use the JSON envelope with HTTP 200:
400invalidformat,speakers,content, or missingtaskId;404not a transcription job in your account;409not finished yet, or no finished translation forcontent=translation. Omit theAcceptheader or sendAccept: */*. - Translation:
POST /openapi/v1/app/tasks/transcription/translatetranslates the whole transcript into onetargetLanguage, the same as the Translate button in the website editor. Each job has one target language; asking for a different language once a translation exists returns409, and asking for the same language again re-translates and replaces the previous translation. An insufficient credit balance returns402. - The job detail of a finished transcription job includes
result.translation(status:none,running, orfinished, plustargetLanguage). Download the translation withcontent=translation; it has the same timing and speakers as the original. The JSON format does not combine original and translated text in one response; download each withcontent=sourceandcontent=translation. - Timestamps are per sentence segment, with millisecond precision. Word-level timestamps are not available.
Webhook
Webhook
- Uses the webhook URL and secret from API Configuration on the website, shared with the Standalone API. Verify signatures as in Webhook verification.
eventisopenapi-app-media-translationfor every App-Synced job, transcription included; usedata.taskType(vt,at, ortranscription) to tell them apart.pipelineKeyisopenapi-app-{taskId}.- For a finished transcription job,
data.result.srtEndpointis the transcript download path anddata.result.translationits translation status (usuallynoneat that point). Translation progress is not pushed by webhook; poll the job detail. datahas the same fields as Query job status (taskId,taskType,status,editorUrl,result).codeis200when the job finished and500when it failed; on failuremessageholds the reason.- Sent once per job, for its first
finishedorfailed. Failed deliveries are retried a few times within about 40 minutes; after that, poll. Deduplicate bypipelineKey. extraDatais not supported, so it is always empty.
Voice cloning
Voice cloning
- The call is synchronous and returns the new
cv_*voice; it can take tens of seconds. - Accepts
refAudioMaterialId(an uploaded material) as an alternative torefAudio;voiceNameandsampleTextare required.

