# Untertitelextraktion

Verwenden Sie diesen Workflow, um Untertiteldateien aus Videos zu erstellen. Weydub unterstützt zwei Extraktionswege:

- OCR-Extraktion für fest eingebrannte Untertitel, die bereits im Videobild sichtbar sind.
- ASR-Extraktion für gesprochene Dialoge in der Audiospur.

Möchten Sie die Ausgabequalität prüfen, bevor Sie mit der Entwicklung beginnen? Probieren Sie den entsprechenden Weydub-Web-Workflow aus: [Untertitel generieren](https://weydub.com/subtitle-generator/).

Eine Erklärung auf Systemebene zur temporalen Video-OCR, zur Filterung von Szenentext und zur untertitelgerechten ASR-Segmentierung finden Sie unter [KI-Untertitelerstellung mit Video-OCR und ASR](https://weydub.com/technology/ai-subtitle-generation-video-ocr-asr/).

## Endpunkt

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

Die Untertitelextraktion erfolgt asynchron. Speichern Sie `body.idProject` und `body.dataList[].id`, und verwenden Sie anschließend das [Modell für asynchrone Aufgaben](./async-task-model.md) für Polling, Callbacks, das Verhalten bei Wiederholungsversuchen und die Signierung von Callbacks.

## Zugriff und Beschränkungen

| Regel | Anforderung |
| --- | --- |
| Kontozugriff | Der grundlegende Video-API-Zugriff muss aktiviert sein. Die OCR-/ASR-Extraktion gehört üblicherweise zur Familie der Videoaufgaben, die Kontorichtlinie kann jedoch weiterhin die Batchgröße oder erweiterte Optionen beschränken. |
| Quellvideo | Verwenden Sie eine stabile, öffentlich zugängliche HTTPS-URL. Die derzeitigen festen Obergrenzen für Videos betragen 15 Minuten pro Datei und 1000 MB pro Datei. |
| Abrechnung | Video-Workflows werden in Einheiten von 30 Sekunden abgerechnet. Clips, die kürzer als 30 Sekunden sind, werden als 30 Sekunden abgerechnet. |
| Fehlgeschlagene Aufgabe | Wenn für den endgültigen Status `processStatus > 1` gilt, werden keine Credits abgezogen. |
| Aufbewahrung | Untertiteldateien und gerenderte Assets unterliegen den Web-Aufbewahrungsregeln von Weydub. Standardmäßig werden Quell- und gerenderte Assets aus den letzten 30 Tagen aufbewahrt. Laden Sie nach dem Callback Kopien zur dauerhaften Aufbewahrung herunter. |

## Zwischen OCR und ASR wählen

| Modus | Verwenden, wenn | Erforderliches Signal | Typische Ausgabe |
| --- | --- | --- | --- |
| OCR-Extraktion fest eingebrannter Untertitel | Untertitel sind in das Bild eingebrannt, üblicherweise am unteren Rand des Bildes. | `needChineseOcclude: 14`, `videoInpaintMasks`, `videoInpaintLang`, `lang`. | `srcSrtUrl`, `tgtSrtUrl`. |
| ASR-Sprachextraktion | Dialoge sind in der Audiospur vorhanden und Sie benötigen ein Transkript mit Zeitstempeln. | `needWanyin: 1`, `wyTaskType: "ONLY_ASR"`, `wyNeedText: 0`. | `srcSrtUrl`, `tgtSrtUrl`. |

Verwenden Sie OCR nicht, um Videos zu transkribieren, die ausschließlich Sprache enthalten. Verwenden Sie ASR nicht, um lautlose, fest eingebrannte Untertitel auszulesen.

## Payload für die OCR-Untertitelextraktion

Verwenden Sie OCR, wenn Untertitel bereits in das Videobild eingebettet sind.

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

Hinweise:

- `needChineseOcclude` muss `14` sein.
- `videoInpaintMasks` ist für die OCR-Extraktion erforderlich und sollte vor dem Signieren eine kompakte JSON-Zeichenfolge sein.
- `type` sollte `trans_only_ocr` sein.
- Setzen Sie `lang` auf denselben Wert wie `videoInpaintLang`, wenn keine Übersetzung erforderlich ist.
- Die Koordinaten sind auf den Bereich von `0` bis `1` normiert und in folgender Reihenfolge angeordnet: oben links, oben rechts, unten rechts, unten links.

## OCR-Masken

Verwenden Sie eine oder mehrere Masken, wenn der sichtbare Untertitelbereich bekannt ist. Zeitlich begrenzte Masken tragen dazu bei, dass vorübergehende Handlungshinweise oder Registrierungstexte nicht als Dialog extrahiert werden.

| Feld | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `type` | string | Ja | Verwenden Sie `trans_only_ocr` für die OCR-Untertitelextraktion. |
| `region` | array | Ja | Vier normalisierte Punkte: `[[x1,y1],[x2,y2],[x3,y3],[x4,y4]]`. |
| `start` | number | Nein | Startzeit in Sekunden. Lassen Sie das Feld weg oder verwenden Sie `0`, wenn die Maske von Anfang an gilt. |
| `end` | number | Nein | Endzeit in Sekunden. Nützlich, wenn eine Maske nur für das Intro gilt. |
| `to_end` | number | Nein | Anzahl der Sekunden vor dem Videoende. Bevorzugen Sie eine explizite Angabe für `end`, sofern diese bekannt ist. |

Häufig verwendete Bereiche:

| Szenario | Bereich |
| --- | --- |
| Vertikales 16:9-Untertitelband | `[[0,0.56],[1,0.56],[1,0.76],[0,0.76]]` |
| Standardmäßiger horizontaler Untertitelbereich | `[[0,0.8],[1,0.8],[1,1],[0,1]]` |
| Benutzerdefiniertes unteres Band | `[[0,0.7],[1,0.7],[1,0.95],[0,0.95]]` |

## OCR-Optionen

Mit `extraOptions.extra_inpaint_config` lässt sich die OCR-Bereinigung anpassen:

| Option | Typ | Beschreibung |
| --- | --- | --- |
| `auto_correct_on` | boolean | Gibt an, ob erkannter Untertiteltext automatisch korrigiert werden soll. |
| `strip_last_punct_on` | boolean | Gibt an, ob abschließende Satzzeichen aus jeder Untertitelzeile entfernt werden sollen. |
| `scene_filter_on` | boolean | Gibt an, ob Szenentext, der kein Dialog ist, herausgefiltert werden soll. Diese Option ist bei der Untertitelextraktion für Englisch und andere Nicht-CJK-Sprachen häufig deaktiviert, wenn der gesamte sichtbare Untertiteltext erfasst werden soll. |

Belassen Sie `extraOptions` als kompakten JSON-String für öffentliche API-Payloads, sofern Ihr Kontovertrag nichts anderes vorsieht.

## ASR-Payload für die Untertitelextraktion

Verwenden Sie ASR, wenn das Video Sprachinhalte enthält und Sie ein zeitcodiertes Transkript benötigen.

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

Hinweise:

- `wyTaskType` muss `ONLY_ASR` sein.
- `wyNeedText: 0` bedeutet, dass Untertitel nicht in ein neues Video gerendert werden.
- `needWyEdit: 0` deaktiviert für diesen Extraktionsauftrag das Verhalten für die manuelle Bearbeitung/Pro-Draft-Erstellung.
- `sourceLang` ist die gesprochene Sprache. `lang` ist die Ausgabesprache der Untertitel; verwenden Sie denselben Code, wenn keine Übersetzung erforderlich ist.

## ASR-Optionen

| Option | Typ | Beschreibung |
| --- | --- | --- |
| `asr_speaker_detect_on` | boolean | Aktiviert die Sprechererkennung, sofern sie unterstützt wird. Nützlich für Dialoge mit mehreren Sprechern. |
| `extra_video_translate_config.remove_last_punct_on` | boolean | Entfernt abschließende Satzzeichen aus erzeugten Untertitelzeilen. |

## Parameter

| Parameter | OCR | ASR | Beschreibung |
| --- | --- | --- | --- |
| `urls` | Erforderlich | Erforderlich | Öffentliche Video-URLs. Verwenden Sie im Produktivbetrieb stabile HTTPS-URLs. |
| `needChineseOcclude` | `14` | Nicht verwendet | OCR-Modus zur Untertitelextraktion. |
| `videoInpaintLang` | Erforderlich | Nicht verwendet | Sprache des sichtbaren Untertiteltexts. |
| `videoInpaintMasks` | Erforderlich | Nicht verwendet | Kompakte JSON-Zeichenfolge zur Beschreibung von OCR-Regionen. |
| `extraOptions` | Optional | Optional | Kompakte JSON-Zeichenfolge für die OCR-Bereinigung oder ASR-Optionen. |
| `needWanyin` | Nicht verwendet | `1` | Aktiviert die Sprachverarbeitung für ASR. |
| `sourceLang` | Optional | Erforderlich | Gesprochene Sprache/Quellsprache. |
| `lang` | Erforderlich | Erforderlich | Ausgabesprache der Untertitel. Verwenden Sie denselben Wert wie für die Quellsprache, wenn keine Übersetzung erforderlich ist. |
| `wyTaskType` | Nicht verwendet | `ONLY_ASR` | Aufgabentyp ausschließlich für ASR. |
| `needWyEdit` | Nicht verwendet | `0` | Deaktiviert den Ablauf für manuelle Bearbeitung/Pro-Entwürfe bei der Extraktion. |
| `wyNeedText` | Nicht verwendet | `0` | Untertitel nicht in ein neues Video rendern. |
| `callback` | Optional | Optional | Webhook-URL für den asynchronen Abschluss. |
| `uid` | Optional | Optional | Ihre Benutzer-/Kundenkennung, wenn für Ihr Konto die Nachverfolgung von Unterbenutzern verwendet wird. |

## Ausgaben

Erfolgreiche Extraktionsaufgaben können Folgendes zurückgeben:

- `srcSrtUrl`
- `tgtSrtUrl`
- `processStatus`
- `processProgress`
- `paidPoint`
- Metadaten zur Aufgabe unter dem zurückgegebenen Arbeitselement

Für die Extraktion mit OCR und ASR muss kein neues Video gerendert werden. Fragen Sie den Status ab, bis `processStatus === 1` erreicht ist, bevor Sie `srcSrtUrl` oder `tgtSrtUrl` lesen.

Callbacks senden die Nutzlast des Arbeitselements direkt, ohne den äußeren `code` / `msg` / `body`-Wrapper, der bei Polling-Antworten verwendet wird.

## Hinweise für Agenten

- Wählen Sie OCR für eingebrannten Untertiteltext und ASR für gesprochene Dialoge.
- Halten Sie `videoInpaintMasks` und `extraOptions` vor dem Signieren kompakt und als Zeichenfolgen serialisiert.
- Senden Sie OCR-Maskenarrays nur dann als native Arrays, wenn Ihr Kontovertrag dies vorsieht.
- Verwenden Sie die Enum-Abfrage (`POST /v-w-c/enum/query2`), um die derzeit unterstützten Werte für `sourceLang` und `Lang` abzurufen; dieser Enum-Endpunkt erfordert keine Signierung.
- Fragen Sie den Status ab, bis `processStatus` den Wert `1` hat, bevor Sie `srcSrtUrl` oder `tgtSrtUrl` lesen.
- Speichern Sie die Untertiteldateien vor der Aufbewahrungsbereinigung.