# Estrazione dei sottotitoli

Utilizza questo flusso di lavoro per creare file di sottotitoli da un video. Weydub supporta due metodi di estrazione:

- Estrazione tramite OCR dei sottotitoli impressi già visibili nel fotogramma del video.
- Estrazione tramite ASR dei dialoghi parlati nella traccia audio.

Vuoi verificare la qualità dell'output prima di procedere? Prova il flusso di lavoro web Weydub corrispondente: [Genera sottotitoli](https://weydub.com/subtitle-generator/).

Per una spiegazione a livello di sistema del Video OCR temporale, del filtraggio del testo nelle scene e della segmentazione ASR pronta per i sottotitoli, consulta [Generazione di sottotitoli tramite IA con Video OCR e ASR](https://weydub.com/technology/ai-subtitle-generation-video-ocr-asr/).

## Endpoint

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

L'estrazione dei sottotitoli è asincrona. Salva `body.idProject` e `body.dataList[].id`, quindi utilizza [Modello per le attività asincrone](./async-task-model.md) per il polling, la gestione dei tentativi, il comportamento dei callback e la firma dei callback.

## Accesso e limiti

| Regola | Requisito |
| --- | --- |
| Accesso dell'account | L'accesso all'API video principale deve essere abilitato. L'estrazione OCR/ASR fa generalmente parte della famiglia di attività video, ma la policy dell'account può comunque limitare le dimensioni dei batch o le opzioni avanzate. |
| Video sorgente | Utilizza un URL pubblico e stabile tramite HTTPS. Gli attuali limiti massimi per i video sono di 15 minuti per file e 1000 MB per file. |
| Fatturazione | I flussi di lavoro video vengono fatturati in unità da 30 secondi. I clip di durata inferiore a 30 secondi vengono conteggiati come 30 secondi. |
| Attività non riuscita | Se al termine si verifica `processStatus > 1`, non viene detratto alcun credito. |
| Conservazione | I file dei sottotitoli e le risorse renderizzate seguono le regole di conservazione web di Weydub. Per impostazione predefinita, vengono conservate le risorse sorgente/renderizzate degli ultimi 30 giorni. Scarica copie permanenti dopo il callback. |

## Scegli OCR o ASR

| Modalità | Quando utilizzarla | Segnale richiesto | Output tipico |
| --- | --- | --- | --- |
| Estrazione di sottotitoli impressi con OCR | I sottotitoli sono impressi nell'immagine, generalmente nella parte inferiore del fotogramma. | `needChineseOcclude: 14`, `videoInpaintMasks`, `videoInpaintLang`, `lang`. | `srcSrtUrl`, `tgtSrtUrl`. |
| Estrazione del parlato tramite ASR | Il dialogo è presente nella traccia audio ed è necessaria una trascrizione con indicazioni temporali. | `needWanyin: 1`, `wyTaskType: "ONLY_ASR"`, `wyNeedText: 0`. | `srcSrtUrl`, `tgtSrtUrl`. |

Non utilizzare OCR per trascrivere video contenenti esclusivamente parlato. Non utilizzare ASR per leggere sottotitoli impressi in video privi di audio.

## Payload per l'estrazione OCR dei sottotitoli

Usa OCR quando i sottotitoli sono già incorporati nell'immagine 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"
}
```

Note:

- `needChineseOcclude` deve essere `14`.
- `videoInpaintMasks` è obbligatorio per l'estrazione OCR e dovrebbe essere una stringa JSON compatta prima della firma.
- `type` dovrebbe essere `trans_only_ocr`.
- Imposta `lang` uguale a `videoInpaintLang` quando non è necessaria alcuna traduzione.
- Le coordinate sono normalizzate da `0` a `1`, nell'ordine: angolo superiore sinistro, angolo superiore destro, angolo inferiore destro, angolo inferiore sinistro.

## Maschere OCR

Usa una o più maschere quando l'area visibile dei sottotitoli è nota. Le maschere delimitate temporalmente aiutano a evitare che indizi temporanei sulla trama o testi di registrazione vengano estratti come dialoghi.

| Campo | Tipo | Obbligatorio | Descrizione |
| --- | --- | --- | --- |
| `type` | string | Sì | Usa `trans_only_ocr` per l'estrazione OCR dei sottotitoli. |
| `region` | array | Sì | Quattro punti normalizzati: `[[x1,y1],[x2,y2],[x3,y3],[x4,y4]]`. |
| `start` | number | No | Tempo di inizio in secondi. Ometti il campo o usa `0` quando la maschera si applica fin dall'inizio. |
| `end` | number | No | Tempo di fine in secondi. Utile quando una maschera si applica solo all'introduzione. |
| `to_end` | number | No | Secondi prima della fine del video. Se noto, è preferibile specificare esplicitamente `end`. |

Aree comuni:

| Scenario | Area |
| --- | --- |
| Fascia verticale 16:9 per i sottotitoli | `[[0,0.56],[1,0.56],[1,0.76],[0,0.76]]` |
| Area standard orizzontale per i sottotitoli | `[[0,0.8],[1,0.8],[1,1],[0,1]]` |
| Fascia inferiore personalizzata | `[[0,0.7],[1,0.7],[1,0.95],[0,0.95]]` |

## Opzioni OCR

`extraOptions.extra_inpaint_config` consente di regolare la pulizia OCR:

| Opzione | Tipo | Descrizione |
| --- | --- | --- |
| `auto_correct_on` | boolean | Indica se correggere automaticamente il testo riconosciuto dei sottotitoli. |
| `strip_last_punct_on` | boolean | Indica se rimuovere la punteggiatura finale da ogni riga dei sottotitoli. |
| `scene_filter_on` | boolean | Indica se filtrare il testo di scena non appartenente ai dialoghi. Questa opzione è spesso disabilitata per l'estrazione dei sottotitoli in inglese e in altre lingue non CJK quando si desidera acquisire tutto il testo visibile dei sottotitoli. |

Mantieni `extraOptions` come stringa JSON compatta per i payload API pubblici, salvo diversa indicazione nel contratto del tuo account.

## Payload per l'estrazione dei sottotitoli ASR

Usa ASR quando il video contiene parlato e hai bisogno di una trascrizione temporizzata.

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

Note:

- `wyTaskType` deve essere `ONLY_ASR`.
- `wyNeedText: 0` indica di non eseguire il rendering dei sottotitoli in un nuovo video.
- `needWyEdit: 0` disabilita il flusso di modifica manuale/pro-draft per questa attività di estrazione.
- `sourceLang` è la lingua parlata. `lang` è la lingua di output dei sottotitoli; usa lo stesso codice quando non è necessaria alcuna traduzione.

## Opzioni ASR

| Opzione | Tipo | Descrizione |
| --- | --- | --- |
| `asr_speaker_detect_on` | boolean | Abilita il rilevamento dei parlanti, quando supportato. Utile per i dialoghi con più parlanti. |
| `extra_video_translate_config.remove_last_punct_on` | boolean | Rimuove la punteggiatura finale dalle righe generate dei sottotitoli. |

## Parametri

| Parametro | OCR | ASR | Descrizione |
| --- | --- | --- | --- |
| `urls` | Obbligatorio | Obbligatorio | URL pubblici dei video. In produzione, usa URL HTTPS stabili. |
| `needChineseOcclude` | `14` | Non utilizzato | Modalità di estrazione OCR dei sottotitoli. |
| `videoInpaintLang` | Obbligatorio | Non utilizzato | Lingua del testo visibile dei sottotitoli. |
| `videoInpaintMasks` | Obbligatorio | Non utilizzato | Stringa JSON compatta che descrive le regioni OCR. |
| `extraOptions` | Facoltativo | Facoltativo | Stringa JSON compatta per la pulizia OCR o per le opzioni ASR. |
| `needWanyin` | Non utilizzato | `1` | Abilita l'elaborazione del parlato per ASR. |
| `sourceLang` | Facoltativo | Obbligatorio | Lingua parlata/di origine. |
| `lang` | Obbligatorio | Obbligatorio | Lingua dei sottotitoli di output. Usa lo stesso valore della lingua di origine quando non è necessaria alcuna traduzione. |
| `wyTaskType` | Non utilizzato | `ONLY_ASR` | Tipo di attività esclusivamente ASR. |
| `needWyEdit` | Non utilizzato | `0` | Disabilita il flusso di modifica manuale/pro-draft per l'estrazione. |
| `wyNeedText` | Non utilizzato | `0` | Non eseguire il rendering dei sottotitoli in un nuovo video. |
| `callback` | Facoltativo | Facoltativo | URL del webhook per il completamento asincrono. |
| `uid` | Facoltativo | Facoltativo | Il tuo identificatore utente/cliente quando il tuo account utilizza il tracciamento dei sottoutenti. |

## Output

Le attività di estrazione completate correttamente possono restituire:

- `srcSrtUrl`
- `tgtSrtUrl`
- `processStatus`
- `processProgress`
- `paidPoint`
- metadati dell'attività inclusi nell'elemento di lavoro restituito

Le estrazioni OCR e ASR non richiedono il rendering di un nuovo video. Esegui il polling fino a quando `processStatus === 1`, prima di leggere `srcSrtUrl` o `tgtSrtUrl`.

I callback inviano direttamente il payload dell'elemento di lavoro, senza il wrapper esterno `code` / `msg` / `body` utilizzato nelle risposte di polling.

## Note per gli agenti

- Scegli OCR per il testo dei sottotitoli incorporato nel video; scegli ASR per i dialoghi parlati.
- Mantieni `videoInpaintMasks` e `extraOptions` in formato compatto e serializzati come stringhe prima della firma.
- Non inviare gli array di maschere OCR come array nativi, a meno che il contratto del tuo account non lo preveda.
- Usa la query enum (`POST /v-w-c/enum/query2`) per recuperare informazioni aggiornate sul supporto di `sourceLang` e `Lang`; questo endpoint enum non richiede la firma.
- Esegui il polling finché `processStatus` non è `1`, prima di leggere `srcSrtUrl` o `tgtSrtUrl`.
- Salva i file dei sottotitoli prima della pulizia prevista dai criteri di conservazione.