Skip to main content
Jobs, materials, and cloned voices created through the App-Synced API live in your VMEG website account: jobs show up in My tasks, and you can keep editing and re-export them in the editor. Not sure which API to use? See Standalone vs App-Synced.

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 in language.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 finished or failed is 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 stays running far longer than usual, contact support with the taskId.
  • Results can change — re-exporting on the website sets the job back to running and puts the new output at result.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.
See the full API reference for every field. Guides linked from the reference are written for the Standalone API; the steps are the same with the /openapi/v1/app prefix.

Field details

  • The API key must belong to a VMEG website account; other keys get 401.
  • Voice cloning requires a plan with voice cloning; otherwise 403.
  • options is optional; defaults match a website job with automatic voice cloning.
  • source accepts exactly one of materialId, youtubeUrl, or sourceUrl (a public HTTPS file URL such as CDN or public S3). sourceUrl returns a task immediately and downloads in the background. If the account cannot cover one minute, the request returns 402. If the probed duration costs more than the remaining credits, the task becomes failed and the webhook uses 402 with message insufficient quota. taskType must match the material: vt for video, at for audio.
  • title sets 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 .srt materials.
  • options.voiceClone.style also accepts auto, tutorial, drama, and smart.
  • Manual voice picking (voiceSpeakers.selectedVoicesList) accepts sv_* system voices and cv_* voices from List cloned voices. It cannot be combined with voiceClone, and dubbingVersion: V2 cannot be combined with either.
  • Burned-in subtitles use options.subtitle (type plus an optional templateId from List subtitle templates) instead of options.text. With type but no templateId, the website’s default style is used.
  • options.lipsync requires a video of at least 360 × 360 px; lower resolutions return 400. YouTube sources are not pre-checked.
  • options.text, output, extraData, and the material mimeType filter return 400. Other unknown fields are ignored.
  • 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.
  • The acceptance response and job detail include editorUrl.
  • result.outputs is newest first; result.outputs[0] is the latest successful render.
  • finished is not permanent: re-exporting sets the job back to running, and a failed re-export ends in failed while earlier outputs stay in the list.
  • source accepts exactly one of materialId (an audio or video material; other types return 400) or youtubeUrl. sourceUrl, output, and extraData return 400.
  • language.source is required: one language code, auto to detect the language, or several codes (array or comma-separated, up to 10) for multilingual transcription of mixed-language audio. auto cannot be combined with other codes, and multilingual transcription requires options.asr.quality standard, as on the website. title is optional and defaults to the file name or YouTube video title.
  • options.asr.quality is standard (default) or quick; options.speakers is auto (default) or a positive integer such as "2". Other values return 400.
  • List jobs with taskType=transcription. Transcription jobs have empty result.outputs; once status is finished, result.srtEndpoint holds the download path (a relative path on https://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=json returns data.segments (index, start, end in milliseconds, text, speaker) in the usual JSON envelope.
  • Errors use the JSON envelope with HTTP 200: 400 invalid format, speakers, content, or missing taskId; 404 not a transcription job in your account; 409 not finished yet, or no finished translation for content=translation. Omit the Accept header or send Accept: */*.
  • Translation: POST /openapi/v1/app/tasks/transcription/translate translates the whole transcript into one targetLanguage, 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 returns 409, and asking for the same language again re-translates and replaces the previous translation. An insufficient credit balance returns 402.
  • The job detail of a finished transcription job includes result.translation (status: none, running, or finished, plus targetLanguage). Download the translation with content=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 with content=source and content=translation.
  • Timestamps are per sentence segment, with millisecond precision. Word-level timestamps are not available.
  • Uses the webhook URL and secret from API Configuration on the website, shared with the Standalone API. Verify signatures as in Webhook verification.
  • event is openapi-app-media-translation for every App-Synced job, transcription included; use data.taskType (vt, at, or transcription) to tell them apart. pipelineKey is openapi-app-{taskId}.
  • For a finished transcription job, data.result.srtEndpoint is the transcript download path and data.result.translation its translation status (usually none at that point). Translation progress is not pushed by webhook; poll the job detail.
  • data has the same fields as Query job status (taskId, taskType, status, editorUrl, result).
  • code is 200 when the job finished and 500 when it failed; on failure message holds the reason.
  • Sent once per job, for its first finished or failed. Failed deliveries are retried a few times within about 40 minutes; after that, poll. Deduplicate by pipelineKey.
  • extraData is not supported, so it is always empty.
  • The call is synchronous and returns the new cv_* voice; it can take tens of seconds.
  • Accepts refAudioMaterialId (an uploaded material) as an alternative to refAudio; voiceName and sampleText are required.