# Extracción de subtítulos

Usa este flujo de trabajo para crear archivos de subtítulos a partir de un video. Weydub admite dos vías de extracción:

- Extracción mediante OCR para subtítulos incrustados que ya son visibles en el fotograma del video.
- Extracción mediante ASR para diálogos hablados en la pista de audio.

¿Quieres inspeccionar la calidad de la salida antes de crear una integración? Prueba el flujo web correspondiente de Weydub: [Generar subtítulos](https://weydub.com/subtitle-generator/).

Para conocer la explicación a nivel de sistema del OCR temporal de video, el filtrado de texto de escenas y la segmentación ASR preparada para subtítulos, lee [Generación de subtítulos con OCR de video y ASR](https://weydub.com/technology/ai-subtitle-generation-video-ocr-asr/).

## Endpoint

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

La extracción de subtítulos es asíncrona. Guarda `body.idProject` y `body.dataList[].id`, y después usa el [modelo de tareas asíncronas](./async-task-model.md) para la consulta periódica, los callbacks, el comportamiento de reintento y la firma de callbacks.

## Acceso y límites

| Regla | Requisito |
| --- | --- |
| Acceso de la cuenta | El acceso a la API de video principal debe estar habilitado. La extracción OCR/ASR suele formar parte de la familia de tareas de video, pero la política de la cuenta aún puede limitar el tamaño de los lotes o las opciones avanzadas. |
| Video de origen | Usa una URL HTTPS pública y estable. Los límites máximos actuales son 15 minutos por archivo y 1000 MB por archivo. |
| Facturación | Los flujos de video se facturan en unidades de 30 segundos. Los clips de menos de 30 segundos cuentan como 30 segundos. |
| Tarea fallida | Cuando se cumple la condición final `processStatus > 1`, no se descuentan créditos. |
| Retención | Los archivos de subtítulos y los recursos renderizados siguen las reglas de retención web de Weydub. De forma predeterminada, se conservan los recursos de origen y renderizados de los últimos 30 días. Descarga copias duraderas después del callback. |

## Elige OCR o ASR

| Modo | Úsalo cuando | Señal requerida | Salida habitual |
| --- | --- | --- | --- |
| Extracción OCR de subtítulos incrustados | Los subtítulos están incrustados en la imagen, normalmente en la parte inferior del fotograma. | `needChineseOcclude: 14`, `videoInpaintMasks`, `videoInpaintLang`, `lang`. | `srcSrtUrl`, `tgtSrtUrl`. |
| Extracción ASR del habla | Hay diálogo en la pista de audio y necesitas una transcripción sincronizada. | `needWanyin: 1`, `wyTaskType: "ONLY_ASR"`, `wyNeedText: 0`. | `srcSrtUrl`, `tgtSrtUrl`. |

No uses OCR para transcribir videos que solo contienen habla. No uses ASR para leer subtítulos incrustados en videos sin diálogo.

## Carga útil de extracción OCR

Usa OCR cuando los subtítulos ya estén incrustados en la imagen del video.

```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"
}
```

Notas:

- `needChineseOcclude` debe ser `14`.
- `videoInpaintMasks` es obligatorio para la extracción OCR y debe ser una cadena JSON compacta antes de firmar.
- `type` debe ser `trans_only_ocr`.
- Establece `lang` igual a `videoInpaintLang` cuando no se necesite traducción.
- Las coordenadas están normalizadas de `0` a `1` y ordenadas como esquina superior izquierda, esquina superior derecha, esquina inferior derecha y esquina inferior izquierda.

## Máscaras OCR

Usa una o más máscaras cuando conozcas el área visible de los subtítulos. Las máscaras delimitadas por tiempo ayudan a evitar la extracción de indicios temporales de la trama o texto de registro como si fueran diálogos.

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `type` | string | Sí | Usa `trans_only_ocr` para la extracción OCR de subtítulos. |
| `region` | array | Sí | Cuatro puntos normalizados: `[[x1,y1],[x2,y2],[x3,y3],[x4,y4]]`. |
| `start` | number | No | Tiempo inicial en segundos. Omítelo o usa `0` cuando la máscara se aplique desde el principio. |
| `end` | number | No | Tiempo final en segundos. Es útil cuando una máscara solo se aplica a la introducción. |
| `to_end` | number | No | Segundos antes del final del video. Prefiere un `end` explícito cuando se conozca. |

Regiones habituales:

| Escenario | Región |
| --- | --- |
| Banda de subtítulos verticales 16:9 | `[[0,0.56],[1,0.56],[1,0.76],[0,0.76]]` |
| Área de subtítulos horizontal estándar | `[[0,0.8],[1,0.8],[1,1],[0,1]]` |
| Banda inferior personalizada | `[[0,0.7],[1,0.7],[1,0.95],[0,0.95]]` |

## Opciones de OCR

`extraOptions.extra_inpaint_config` permite ajustar la limpieza del OCR:

| Opción | Tipo | Descripción |
| --- | --- | --- |
| `auto_correct_on` | boolean | Indica si se debe corregir automáticamente el texto de subtítulos reconocido. |
| `strip_last_punct_on` | boolean | Indica si se debe eliminar la puntuación final de cada línea de subtítulos. |
| `scene_filter_on` | boolean | Indica si se debe filtrar el texto de escenas que no sea diálogo. Suele desactivarse para la extracción de subtítulos en inglés y otros idiomas no CJK cuando quieres todo el texto visible de los subtítulos. |

Mantén `extraOptions` como una cadena JSON compacta en las cargas útiles de la API pública, salvo que el contrato de tu cuenta indique lo contrario.

## Carga útil de extracción ASR

Usa ASR cuando el video contenga habla y necesites una transcripción sincronizada.

```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"
}
```

Notas:

- `wyTaskType` debe ser `ONLY_ASR`.
- `wyNeedText: 0` significa que no se deben renderizar subtítulos en un video nuevo.
- `needWyEdit: 0` desactiva el comportamiento de edición manual/borrador profesional para esta tarea de extracción.
- `sourceLang` es el idioma hablado. `lang` es el idioma de salida de los subtítulos; usa el mismo código cuando no se necesite traducción.

## Opciones de ASR

| Opción | Tipo | Descripción |
| --- | --- | --- |
| `asr_speaker_detect_on` | boolean | Activa la detección de hablantes cuando es compatible. Es útil para diálogos con varios hablantes. |
| `extra_video_translate_config.remove_last_punct_on` | boolean | Elimina la puntuación final de las líneas de subtítulos generadas. |

## Parámetros

| Parámetro | OCR | ASR | Descripción |
| --- | --- | --- | --- |
| `urls` | Obligatorio | Obligatorio | URL públicas de videos. Usa URL HTTPS estables en producción. |
| `needChineseOcclude` | `14` | No se usa | Modo de extracción OCR de subtítulos. |
| `videoInpaintLang` | Obligatorio | No se usa | Idioma del texto de subtítulos visible. |
| `videoInpaintMasks` | Obligatorio | No se usa | Cadena JSON compacta que describe las regiones OCR. |
| `extraOptions` | Opcional | Opcional | Cadena JSON compacta para la limpieza OCR o las opciones ASR. |
| `needWanyin` | No se usa | `1` | Activa el procesamiento del habla para ASR. |
| `sourceLang` | Opcional | Obligatorio | Idioma hablado/de origen. |
| `lang` | Obligatorio | Obligatorio | Idioma de salida de los subtítulos. Usa el mismo valor que el origen cuando no se necesite traducción. |
| `wyTaskType` | No se usa | `ONLY_ASR` | Tipo de tarea exclusiva de ASR. |
| `needWyEdit` | No se usa | `0` | Desactiva el flujo de edición manual/borrador profesional para la extracción. |
| `wyNeedText` | No se usa | `0` | No renderiza subtítulos en un video nuevo. |
| `callback` | Opcional | Opcional | URL del webhook para la finalización asíncrona. |
| `uid` | Opcional | Opcional | Identificador de usuario/cliente cuando tu cuenta usa seguimiento de subusuarios. |

## Resultados

Las tareas de extracción completadas correctamente pueden devolver:

- `srcSrtUrl`
- `tgtSrtUrl`
- `processStatus`
- `processProgress`
- `paidPoint`
- metadatos de la tarea dentro del elemento de trabajo devuelto

La extracción OCR y ASR no necesita renderizar un video nuevo. Consulta periódicamente hasta que `processStatus === 1` antes de leer `srcSrtUrl` o `tgtSrtUrl`.

Los callbacks envían directamente la carga útil del elemento de trabajo, sin el envoltorio externo `code` / `msg` / `body` que usan las respuestas de consulta periódica.

## Notas para agentes

- Elige OCR para texto de subtítulos incrustados; elige ASR para diálogos hablados.
- Mantén `videoInpaintMasks` y `extraOptions` compactos y convertidos en cadenas antes de firmar.
- No envíes las matrices de máscaras OCR como matrices nativas salvo que el contrato de tu cuenta lo indique.
- Usa la consulta de enumeraciones (`POST /v-w-c/enum/query2`) para obtener la compatibilidad actual de `sourceLang` y `Lang`; este endpoint de enumeración no requiere firma.
- Consulta periódicamente hasta que `processStatus` sea `1` antes de leer `srcSrtUrl` o `tgtSrtUrl`.
- Guarda los archivos de subtítulos antes de la limpieza por retención.