Use this workflow to create subtitle files from video. Weydub supports two extraction paths:

OCR extraction for hardcoded subtitles already visible in the video frame.
ASR extraction for spoken dialogue in the audio track.

Want to inspect output quality before building? Try the matching Weydub web workflow: Generate subtitles.

For the system-level explanation of temporal Video OCR, scene-text filtering, and subtitle-ready ASR segmentation, read AI subtitle generation with Video OCR and ASR.

Endpoint

text

POST /v-w-c/gateway/ve/work/free

Subtitle extraction is asynchronous. Save body.idProject and body.dataList[].id, then use Async task model for polling, callbacks, retry behavior, and callback signing.

Access And Limits

Rule	Requirement
Account access	Core video API access must be enabled. OCR/ASR extraction is usually part of the video task family, but account policy may still limit batch size or advanced options.
Source video	Use a stable public HTTPS URL. Current video hard limits are 15 minutes per file and 1000 MB per file.
Billing	Video workflows are billed in 30-second units. Clips shorter than 30 seconds count as 30 seconds.
Failed task	If the final `processStatus > 1`, zero credits are deducted.
Retention	Subtitle files and rendered assets follow Weydub web retention rules. By default, source/rendered assets for the last 30 days are retained. Download durable copies after callback.

Choose OCR Or ASR

Mode	Use It When	Required Signal	Typical Output
OCR hard-sub extraction	Subtitles are burned into the image, usually at the bottom of the frame.	`needChineseOcclude: 14`, `videoInpaintMasks`, `videoInpaintLang`, `lang`.	`srcSrtUrl`, `tgtSrtUrl`.
ASR speech extraction	Dialogue exists in the audio track and you need a timed transcript.	`needWanyin: 1`, `wyTaskType: "ONLY_ASR"`, `wyNeedText: 0`.	`srcSrtUrl`, `tgtSrtUrl`.

Do not use OCR to transcribe speech-only videos. Do not use ASR to read silent hardcoded captions.

OCR Subtitle Extraction Payload

Use OCR when subtitles are already embedded in the video image.

json

{
  "urls": ["https://example.com/video.mp4"],
  "needChineseOcclude": 14,
  "videoInpaintLang": "en",
  "lang": "en",
  "videoInpaintMasks": "[{\"type\":\"trans_only_ocr\",\"region\":[[0,0.8],[1,0.8],[1,1],[0,1]]}]",
  "extraOptions": "{\"extra_inpaint_config\":{\"auto_correct_on\":false,\"strip_last_punct_on\":true,\"scene_filter_on\":false}}",
  "callback": "https://your-domain.example/webhooks/weydub"
}

Notes:

needChineseOcclude must be 14.
videoInpaintMasks is required for OCR extraction and should be a compact JSON string before signing.
type should be trans_only_ocr.
Set lang equal to videoInpaintLang when no translation is needed.
Coordinates are normalized from 0 to 1, ordered as top-left, top-right, bottom-right, bottom-left.

OCR Masks

Use one or more masks when the visible subtitle area is known. Time-bounded masks help avoid extracting temporary plot hints or registration text as dialogue.

Field	Type	Required	Description
`type`	string	Yes	Use `trans_only_ocr` for OCR subtitle extraction.
`region`	array	Yes	Four normalized points: `[[x1,y1],[x2,y2],[x3,y3],[x4,y4]]`.
`start`	number	No	Start time in seconds. Omit or use `0` when the mask applies from the beginning.
`end`	number	No	End time in seconds. Useful when a mask only applies to the intro.
`to_end`	number	No	Seconds before the video end. Prefer explicit `end` when known.

Common regions:

Scenario	Region
Vertical 16:9 subtitle band	`[[0,0.56],[1,0.56],[1,0.76],[0,0.76]]`
Horizontal standard subtitle area	`[[0,0.8],[1,0.8],[1,1],[0,1]]`
Custom lower band	`[[0,0.7],[1,0.7],[1,0.95],[0,0.95]]`

OCR Options

extraOptions.extra_inpaint_config can tune OCR cleanup:

Option	Type	Description
`auto_correct_on`	boolean	Whether to auto-correct recognized subtitle text.
`strip_last_punct_on`	boolean	Whether to remove trailing punctuation from each subtitle line.
`scene_filter_on`	boolean	Whether to filter non-dialogue scene text. This is often disabled for English and other non-CJK subtitle extraction when you want all visible subtitle text.

Keep extraOptions as a compact JSON string for public API payloads unless your account contract says otherwise.

ASR Subtitle Extraction Payload

Use ASR when the video has speech and you need a timed transcript.

json

{
  "urls": ["https://example.com/video.mp4"],
  "needWanyin": 1,
  "sourceLang": "en",
  "lang": "en",
  "wyTaskType": "ONLY_ASR",
  "needWyEdit": 0,
  "wyNeedText": 0,
  "extraOptions": "{\"asr_speaker_detect_on\":true,\"extra_video_translate_config\":{\"remove_last_punct_on\":true}}",
  "callback": "https://your-domain.example/webhooks/weydub"
}

Notes:

wyTaskType must be ONLY_ASR.
wyNeedText: 0 means do not render subtitles into a new video.
needWyEdit: 0 disables manual editing/pro-draft behavior for this extraction job.
sourceLang is the spoken language. lang is the subtitle output language; use the same code when no translation is needed.

ASR Options

Option	Type	Description
`asr_speaker_detect_on`	boolean	Enables speaker detection when supported. Useful for multi-speaker dialogue.
`extra_video_translate_config.remove_last_punct_on`	boolean	Removes trailing punctuation from generated subtitle lines.

Parameters

Parameter	OCR	ASR	Description
`urls`	Required	Required	Public video URLs. Use stable HTTPS URLs in production.
`needChineseOcclude`	`14`	Not used	OCR subtitle extraction mode.
`videoInpaintLang`	Required	Not used	Language of visible subtitle text.
`videoInpaintMasks`	Required	Not used	Compact JSON string describing OCR regions.
`extraOptions`	Optional	Optional	Compact JSON string for OCR cleanup or ASR options.
`needWanyin`	Not used	`1`	Enables speech processing for ASR.
`sourceLang`	Optional	Required	Spoken/source language.
`lang`	Required	Required	Output subtitle language. Use the same value as source when no translation is needed.
`wyTaskType`	Not used	`ONLY_ASR`	ASR-only task type.
`needWyEdit`	Not used	`0`	Disables manual edit/pro-draft flow for extraction.
`wyNeedText`	Not used	`0`	Do not render subtitles into a new video.
`callback`	Optional	Optional	Webhook URL for async completion.
`uid`	Optional	Optional	Your user/customer identifier when your account uses sub-user tracking.

Outputs

Successful extraction tasks can return:

srcSrtUrl
tgtSrtUrl
processStatus
processProgress
paidPoint
task metadata under the returned work item

OCR and ASR extraction do not need to render a new video. Poll until processStatus === 1 before reading srcSrtUrl or tgtSrtUrl.

Callbacks send the work item payload directly, without the outer code / msg / body wrapper used by polling responses.

Agent Notes

Choose OCR for burned-in subtitle text; choose ASR for spoken dialogue.
Keep videoInpaintMasks and extraOptions compact and stringified before signing.
Do not send OCR mask arrays as native arrays unless your account contract says so.
Use enum query (POST /v-w-c/enum/query2) to fetch current sourceLang and Lang support; this enum endpoint does not require signing.
Poll until processStatus is 1 before reading srcSrtUrl or tgtSrtUrl.
Store subtitle files before retention cleanup.