# API-Referenz

Diese Referenz bietet Entwicklern und Automatisierungsagenten eine zentrale, kompakte Anlaufstelle für die Endpunkte der Weydub API, Zugriffsprüfungen, Anfragestruktur, asynchrones Verhalten, Abrechnungs- und Aufbewahrungsregeln sowie Hinweise zur Fehlerbehebung.

## Grundlagen zu Anfragen

| Element | Wert |
| --- | --- |
| Basis-URL | `https://api.zhaoli.com` |
| Protokoll | HTTPS |
| Methode | `POST` für die dokumentierten API-Aufrufe |
| Kodierung | UTF-8 |
| Inhaltstyp | `application/json` |
| Authentifizierung | Die Header `AppKey` und `AppSign`, außer bei Endpunkten, die ausdrücklich als nicht signiert gekennzeichnet sind |

Einige Bezeichnungen aus der Legacy-Infrastruktur können weiterhin in öffentlichen Demo-Assets oder älteren Kontopfaden erscheinen. Betrachten Sie diese Dokumentation zu Weydub API als die aktuell maßgebliche produktseitige Vertragsgrundlage.

## Vor dem Aufruf

| Prüfung | Was zu prüfen ist | Warum dies wichtig ist |
| --- | --- | --- |
| Zugriff auf API | Mit Ihrem angemeldeten Konto bei Weydub können Sie den Zugriff auf API kostenlos freischalten; prüfen Sie bei Bedarf die workflowspezifischen Berechtigungen. | Für einige Aufgabenfamilien, insbesondere Bildübersetzung und Synchronisation mit hoher Emotionalität, kann eine kontospezifische Freischaltung erforderlich sein. |
| Zugangsdaten | Sie verfügen über `AppKey` und `AppSecret`, die als geheime Werte im Backend gespeichert sind. | `AppSecret` darf niemals in Frontend-Code, öffentlichen Repositorys, Protokollen, Screenshots oder Prompts erscheinen. |
| Medien-URLs | Quelldateien sind während des Verarbeitungszeitraums öffentlich erreichbar und stabil verfügbar. | Worker von Weydub müssen die Quellmedien vor der Verarbeitung herunterladen. |
| Callback-URL | Callbacks im Produktivbetrieb geben HTTP 200 sowie einen nicht leeren Body erst nach dauerhafter Speicherung zurück. | Asynchrone Jobs können abgeschlossen werden, nachdem die ursprüngliche Anfrage bereits beantwortet wurde. |
| Ergebnisspeicherung | Ihr Dienst speichert Arbeits-IDs, Aufgaben-IDs, Status, Ergebnis-URLs und Fehler. | Generierte Assets können einer Aufbewahrungsrichtlinie unterliegen; sichern Sie daher dauerhafte Referenzen zeitnah. |

## Authentifizierung

Für die meisten Anfragen werden folgende Header verwendet:

```text
Content-Type: application/json
AppKey: $WEYDUB_APP_KEY
AppSign: md5(md5(request_body) + $WEYDUB_APP_SECRET)
```

Signieren Sie exakt den kompakten JSON-Body, der gesendet wird. Lesen Sie [Authentifizierung und Signierung](./auth-and-signing.md), bevor Sie Signaturfehler untersuchen.

Ausnahme ohne Signatur:

```text
POST /v-w-c/enum/query2
```

Der Enum-Abfrageendpunkt wird für dynamische Sprach- und Statuslisten verwendet und erfordert keine Signatur.

## Endpunktübersicht

| Methode | Pfad | Kategorie | Zweck | Zugriffshinweise |
| --- | --- | --- | --- | --- |
| `POST` | `/v-w-c/gateway/ve/work/free` | Video | Die meisten Videoaufgaben erstellen: Untertitel- und Textentfernung, Videoübersetzung, OCR-Untertitelextraktion, ASR-Extraktion und das Rendern von Untertiteln. | Grundlegender API-Zugriff erforderlich. |
| `POST` | `/v-w-c/gateway/ve/work/status` | Video | Status und Ergebnisfelder von Videoaufgaben anhand von Work-IDs abfragen. | Nach der Aufgabenerstellung oder als Callback-Fallback verwenden. |
| `POST` | `/v-w-c/gateway/ve/work/list` | Video | Historische Videoaufgaben abfragen. | Für interne Dashboards und den Abgleich nützlich. |
| `POST` | `/v-w-c/gateway/ve/work/video/inpaint/redo` | Video | Textentfernung/Inpainting mit angepassten Masken erneut ausführen. | Erfordert einen vorhandenen Work- oder Aufgabenkontext. |
| `POST` | `/v-w-c/gateway/ve/work/translationPro/redo` | Video | Übersetzung/Synchronisation mit angepassten Untertiteln, Timing oder Stimmeinstellungen erneut ausführen. | Erfordert den Kontext einer bestehenden Übersetzungsaufgabe. |
| `POST` | `/v-w-c/gateway/ve/work/voice/incorporate` | Video | Aufgaben zum Klonen hochemotionaler Stimmen und zur Synchronisation erstellen. | Prüfen Sie die Kontofreischaltung, bevor Sie Produktivdatenverkehr aufschalten. |
| `POST` | `/v-w-c/gateway/ve/image/translate` | Bild | Eine Aufgabe zur Entfernung von Text aus Bildern oder zur Bildübersetzung erstellen. | Nach dem kostenlosen API-Zugriff ist möglicherweise eine Freischaltung für Bild-Workflows erforderlich. |
| `POST` | `/v-w-c/gateway/ve/image/translate/redo` | Bild | Eine Bildaufgabe nach Bearbeitung der Text-/Stilmetadaten des Ergebnisses neu generieren. | Erfordert eine vorhandene Bildaufgaben-ID und das Ergebnis-JSON. |
| `POST` | `/v-w-c/ve/image/translate/task/launch` | Bild (Legacy/Web) | Eine einzelne Bildaufgabe in älteren Konto- oder Web-Workflows erstellen. | Nur verwenden, wenn dies für das Konto bestätigt wurde. |
| `POST` | `/v-w-c/ve/image/translate/task/launch2` | Bild (Legacy/Web) | Eine Batch-Bildaufgabe in älteren Konto- oder Web-Workflows erstellen. | Batch-Limits und Callback-Richtlinie bestätigen. |
| `POST` | `/v-w-c/ve/image/translate/task/query` | Bild (Legacy/Web) | Eine einzelne Bildaufgabe in älteren Konto- oder Web-Workflows abfragen. | Vor dem Lesen der Ausgaben wiederholt abfragen, bis ein Endstatus erreicht ist. |
| `POST` | `/v-w-c/enum/query2` | Hilfsfunktion | Dynamische Enums wie Statuswerte und Sprachlisten abfragen. | Keine Signatur erforderlich. |

## Videoaufgabe erstellen

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

Häufige Workflows mit diesem Endpunkt:

| Workflow | Erforderliches Signal | Einstiegsseite |
| --- | --- | --- |
| Entfernung von Untertiteln/Texten | `needChineseOcclude: 1`, `2` oder `3`; Advanced Lite/Pro über `extraOptions.extra_inpaint_config` | [Entfernung von Untertiteln und Text aus Videos](./video-subtitle-removal.md) |
| Videoübersetzung/Synchronisation | `needWanyin: 1`, `sourceLang`, `lang`, `wyTaskType` | [Videoübersetzung](./video-translation.md) |
| Übersetzung von eingeblendetem Text | `needChineseOcclude: 11`, `sourceLang`, `lang`, `videoInpaintLang` | [Videoübersetzung](./video-translation.md) |
| OCR-Untertitelextraktion | `needChineseOcclude: 14`, `videoInpaintMasks`, `videoInpaintLang` | [Untertitelextraktion](./subtitle-extraction.md) |
| ASR-Untertitelextraktion | `needWanyin: 1`, `wyTaskType: "ONLY_ASR"`, `wyNeedText: 0` | [Untertitelextraktion](./subtitle-extraction.md) |

Minimalanfrage:

```json
{
  "urls": ["https://example.com/demo.mp4"],
  "needChineseOcclude": 1,
  "videoInpaintLang": "all",
  "callback": "https://your-domain.example/webhooks/weydub"
}
```

Typische Felder der Erstellungsantwort:

| Feld | Bedeutung |
| --- | --- |
| `idProject` | Batch-/Projekt-ID. |
| `dataList[].id` | Arbeits-ID für Statusabfragen und die Callback-Zuordnung. |
| `dataList[].url` | Für die Verarbeitung akzeptierte Quell-URL. |

## Videostatus abfragen

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

```json
{
  "idWorks": [488026661]
}
```

Statuswerte:

| `processStatus` | Bedeutung | Clientverhalten |
| --- | --- | --- |
| `< 1` | Wird verarbeitet. | Später erneut abfragen oder auf den Callback warten. |
| `1` | Erfolgreich. | Ergebnis-URLs auslesen und dauerhaft speichern. |
| `> 1` | Fehlgeschlagen. | `errorDetail` anzeigen. Für fehlgeschlagene Aufgaben werden keine Credits abgezogen. |

Erfolgreiche Videoaufgaben können `videoUrl`, `coverUrl`, `srcSrtUrl`, `tgtSrtUrl`, `sourceVideoUrl`, `ttsMetaResult`, `wyVoiceParam` und Aufgabenmetadaten enthalten.

## Bildaufgaben

Aktueller öffentlicher Endpunkt zum Erstellen:

```text
POST /v-w-c/gateway/ve/image/translate
```

Endpunkt für die erneute Verarbeitung:

```text
POST /v-w-c/gateway/ve/image/translate/redo
```

Anfrage zur Bildübersetzung:

```json
{
  "srcLang": "en",
  "tgtLang": "es",
  "translateOn": 1,
  "synthesisOn": 1,
  "commodityFilterOn": 0,
  "downloadInfo": "{\"url\":\"https://example.com/product.png\",\"fileName\":\"product.png\",\"id\":12345,\"materialName\":\"product.png\"}",
  "app": "WD"
}
```

Anfrage zur Entfernung von Bildtext:

```json
{
  "srcLang": "en",
  "tgtLang": "en",
  "translateOn": 0,
  "synthesisOn": 1,
  "commodityFilterOn": 0,
  "downloadInfo": "{\"url\":\"https://example.com/banner.png\",\"fileName\":\"banner.png\",\"id\":12346,\"materialName\":\"banner.png\"}",
  "app": "WD"
}
```

Lesen Sie [Bildübersetzung](./image-translation.md), bevor Sie Bildaufgaben implementieren, da `downloadInfo`, `downloadInfos` und bei erneuter Verarbeitung `result` ihr jeweils dokumentiertes Zeichenfolgenformat beibehalten müssen.

## Enum-Abfrage

```text
POST /v-w-c/enum/query2
```

Für diesen Endpunkt ist `AppSign` nicht erforderlich.

```json
{
  "text": "Lang"
}
```

Gängige Enum-Namen:

| `text` | Zweck |
| --- | --- |
| `ProcessStatus` | Statuscodes für Videoaufgaben. |
| `ImageTaskStatus` | Statuscodes für Bildaufgaben. |
| `sourceLang` | Liste der Ausgangssprachen für Videoübersetzungen. |
| `Lang` | Liste der Zielsprachen für Videoübersetzungen. |
| `musicRegion` | Liste der Smart-Music-Regionen, sofern unterstützt. |

## Abrechnung, Grenzwerte und Aufbewahrung

| Thema | Regel |
| --- | --- |
| Videodauer | Die derzeitige feste Obergrenze beträgt 15 Minuten pro Videodatei. Teilen Sie längere Medien in Segmente von weniger als 15 Minuten auf, beispielsweise 14:59, um Probleme durch die Rundung der Dauer zu vermeiden. |
| Videogröße | Die derzeitige feste Obergrenze beträgt 1000 MB pro Videodatei. Komprimieren Sie zu große Dateien vor der Übermittlung. |
| Bildgrenzwerte | Maximal `2000*2000 px`, maximal `50 MB`, unterstützte Formate: `png`, `jpeg`, `jpg`, `bmp`, `webp`; Bild-URLs dürfen keine chinesischen Zeichen enthalten. |
| Abrechnungseinheit | Video-Workflows werden in Einheiten von 30 Sekunden abgerechnet. Ein Video mit einer Dauer von weniger als 30 Sekunden wird mit 30 Sekunden angesetzt. |
| Kombinierte Dienste | Bei der Kombination von Diensten wie Textentfernung und Sprachübersetzung können sich die Kosten summieren. |
| Fehlgeschlagene Aufgaben | Endgültig fehlgeschlagene Aufgaben (`processStatus > 1`) ziehen keine Credits ab. |
| Aufbewahrung | Für von API generierte Daten gelten die Web-Aufbewahrungsregeln von Weydub. Standardmäßig werden Quelldateien und gerenderte Ausgaben der letzten 30 Tage aufbewahrt. Laden Sie wichtige Assets nach dem Callback herunter und speichern Sie sie. |
| CRF | Der standardmäßige Video-CRF-Wert beträgt `17` und ist für die meisten Formen der Verbreitung visuell verlustfrei. Niedrigere Werte wie `15` oder `16` sind möglicherweise über `extraOptions.write_options` verfügbar und können zusätzliche Bandbreiten- und Speichergebühren verursachen. |

## Callback-Zusammenfassung

Übergeben Sie bei unterstützten Erstellungsanfragen eine `callback`-URL. Weydub sendet das abgeschlossene Arbeitselement direkt an Ihren Server, ohne den äußeren `code`- / `msg`- / `body`-Wrapper, der bei Polling-Antworten verwendet wird.

Regeln für die Callback-Verarbeitung:

- Verifizieren Sie `Callback-Sign` mithilfe des unveränderten Bodys der Callback-Anfrage und Ihres `AppSecret`.
- Geben Sie HTTP 200 zusammen mit einem beliebigen nicht leeren Body erst zurück, nachdem die dauerhafte Speicherung erfolgreich war.
- Stellen Sie anhand der Work-/Task-ID sicher, dass Handler idempotent sind.
- Bei fehlgeschlagenen Callbacks für Aufgaben, die innerhalb der letzten 24 Stunden erstellt wurden, erfolgt etwa alle 30 Minuten ein erneuter Zustellversuch.
- Wenn eine erneute Ausführung Video- oder Bildinhalte ändert, kann sich die Ausgabe-URL ändern; speichern Sie die neueste Ergebnis-URL.

Weitere Einzelheiten zu Callbacks finden Sie unter [Asynchrones Aufgabenmodell](./async-task-model.md).

## Fehlerbehebung

| Symptom | Wahrscheinliche Ursache | Prüfung |
| --- | --- | --- |
| Signaturfehler | Die Body-Bytes wurden nach dem Signieren geändert, oder es wurde lesbar formatiertes JSON signiert, aber kompaktes JSON gesendet. | Protokollieren Sie einen nicht geheimen Body-Hash und vergleichen Sie die Codepfade für Signierung und Versand. |
| Aufgabe erstellt, aber kein Ergebnis | Die asynchrone Verarbeitung läuft noch. | Fragen Sie `/v-w-c/gateway/ve/work/status` per Polling ab oder warten Sie auf den Callback. |
| Ausgabe-URL fehlt | Falscher Workflow-Modus oder die Aufgabe hat noch keinen Endstatus erreicht. | Prüfen Sie, ob `processStatus === 1` gilt, und untersuchen Sie die workflowspezifischen Ausgabefelder. |
| Callback erscheint nicht in Ihrer App | Der Handler hat vor der dauerhaften Speicherung eine Antwort zurückgegeben, die Signaturprüfung ist fehlgeschlagen oder die Work-ID stimmte nicht überein. | Speichern Sie die unveränderte Callback-Nutzlast, vergleichen Sie `Callback-Sign` und gestalten Sie Aktualisierungen idempotent. |
| Endpunkt nicht verfügbar | Die Kontoberechtigung ist nicht aktiviert. | Prüfen Sie den API-Zugriff für die jeweilige Aufgabenfamilie. |
| Fehler wegen Überschreitung der Video-Höchstgrenze | Das Video ist länger als 15 Minuten oder größer als 1000 MB. | Teilen Sie das Video vor dem Übermitteln in Segmente auf oder komprimieren Sie es. |
| Fehler wegen Überschreitung des Bildlimits | Das Bild überschreitet `2000*2000 px` und `50 MB`, wird nicht unterstützt oder URL enthält chinesische Zeichen. | Größe ändern, erneut komprimieren, URL umbenennen/kodieren und erneut versuchen. |

## Agentenvertrag

Automatisierungsagenten sollten:

- Laden Sie [llms.txt](./llms.txt) und [Weydub API Skill](./weydub-api-skill.md).
- Verwenden Sie [Demoszenarien](./demo-scenarios.md) vor Kundenmedien.
- Bewahren Sie Zugangsdaten in Umgebungsvariablen oder einem Secret-Manager auf.
- Speichern Sie IDs dauerhaft, bevor Sie den Benutzern den Erfolg melden.
- Modellieren Sie Jobs als `submitted -> processing -> succeeded | failed | timed_out`.
- Legen Sie `AppSecret` niemals offen und erfinden Sie keine freigeschalteten Endpunkte.