# Referensi API

Referensi ini menyediakan satu tempat ringkas bagi pengembang dan agen otomatisasi untuk menemukan endpoint Weydub API, pemeriksaan akses, struktur permintaan, perilaku asinkron, aturan penagihan/retensi, dan indikator pemecahan masalah.

## Dasar-Dasar Permintaan

| Item | Nilai |
| --- | --- |
| URL Dasar | `https://api.zhaoli.com` |
| Protokol | HTTPS |
| Metode | `POST` untuk panggilan API yang didokumentasikan |
| Pengodean | UTF-8 |
| Jenis konten | `application/json` |
| Autentikasi | Header `AppKey` dan `AppSign`, kecuali endpoint yang secara eksplisit ditandai sebagai tidak memerlukan tanda tangan |

Beberapa nama infrastruktur lama mungkin masih muncul dalam aset demo publik atau jalur akun lama. Perlakukan dokumentasi Weydub API ini sebagai kontrak produk yang berlaku saat ini.

## Sebelum Melakukan Panggilan

| Pemeriksaan | Yang Perlu Dipastikan | Mengapa Penting |
| --- | --- | --- |
| Akses API | Akun Weydub Anda yang sudah masuk dapat membuka akses API secara gratis; pastikan hak akses khusus alur kerja bila diperlukan. | Beberapa jenis tugas, terutama penerjemahan gambar dan dubbing dengan emosi tinggi, mungkin disediakan per akun. |
| Kredensial | Anda memiliki `AppKey` dan `AppSecret`, yang disimpan sebagai rahasia backend. | `AppSecret` tidak boleh muncul dalam kode frontend, repositori publik, log, tangkapan layar, atau prompt. |
| URL media | File sumber dapat diakses secara publik dan tetap stabil selama jangka waktu pemrosesan. | Worker Weydub perlu mengunduh media sumber sebelum pemrosesan. |
| URL callback | Callback produksi hanya mengembalikan HTTP 200 beserta body yang tidak kosong setelah penyimpanan persisten selesai. | Tugas asinkron dapat selesai setelah permintaan awal mengembalikan respons. |
| Penyimpanan hasil | Layanan Anda menyimpan ID pekerjaan, ID tugas, status, URL hasil, dan kesalahan. | Aset yang dihasilkan mungkin mengikuti kebijakan retensi, jadi segera salin referensi ke penyimpanan persisten. |

## Autentikasi

Sebagian besar permintaan menggunakan header:

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

Tandatangani isi JSON ringkas persis seperti yang akan dikirim. Baca [Autentikasi dan penandatanganan](./auth-and-signing.md) sebelum menelusuri kegagalan tanda tangan.

Pengecualian tanpa tanda tangan:

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

Endpoint kueri enum digunakan untuk daftar bahasa/status dinamis dan tidak memerlukan penandatanganan.

## Indeks Endpoint

| Metode | Jalur | Kelompok | Tujuan | Catatan Akses |
| --- | --- | --- | --- | --- |
| `POST` | `/v-w-c/gateway/ve/work/free` | Video | Membuat sebagian besar tugas video: penghapusan subtitel/teks, penerjemahan video, ekstraksi subtitel OCR, ekstraksi ASR, dan rendering subtitel. | Memerlukan akses inti API. |
| `POST` | `/v-w-c/gateway/ve/work/status` | Video | Melakukan kueri atas status tugas video dan kolom hasil berdasarkan ID pekerjaan. | Gunakan setelah pembuatan tugas atau sebagai alternatif callback. |
| `POST` | `/v-w-c/gateway/ve/work/list` | Video | Melakukan kueri atas riwayat tugas video. | Berguna untuk dasbor internal dan rekonsiliasi. |
| `POST` | `/v-w-c/gateway/ve/work/video/inpaint/redo` | Video | Mengulang penghapusan teks/inpainting dengan mask yang disesuaikan. | Memerlukan konteks pekerjaan/tugas yang sudah ada. |
| `POST` | `/v-w-c/gateway/ve/work/translationPro/redo` | Video | Mengulang penerjemahan/dubbing dengan subtitel, pengaturan waktu, atau pengaturan suara yang disesuaikan. | Memerlukan konteks tugas penerjemahan yang sudah ada. |
| `POST` | `/v-w-c/gateway/ve/work/voice/incorporate` | Video | Membuat tugas kloning suara dan dubbing dengan emosi tinggi. | Pastikan hak akses akun sebelum mengarahkan lalu lintas produksi. |
| `POST` | `/v-w-c/gateway/ve/image/translate` | Gambar | Membuat tugas penghapusan teks gambar atau penerjemahan gambar. | Hak akses alur kerja gambar mungkin diperlukan setelah memperoleh akses API gratis. |
| `POST` | `/v-w-c/gateway/ve/image/translate/redo` | Gambar | Membuat ulang tugas gambar setelah mengedit metadata teks/gaya hasil. | Memerlukan ID tugas gambar yang sudah ada dan JSON hasil. |
| `POST` | `/v-w-c/ve/image/translate/task/launch` | Gambar lama/web | Membuat satu tugas gambar dalam alur akun lama atau alur web. | Gunakan hanya jika telah dikonfirmasi untuk akun tersebut. |
| `POST` | `/v-w-c/ve/image/translate/task/launch2` | Gambar lama/web | Membuat tugas gambar batch dalam alur akun lama atau alur web. | Pastikan batas batch dan kebijakan callback. |
| `POST` | `/v-w-c/ve/image/translate/task/query` | Gambar lama/web | Melakukan kueri atas satu tugas gambar dalam alur akun lama atau alur web. | Lakukan polling hingga mencapai status terminal sebelum membaca hasil keluaran. |
| `POST` | `/v-w-c/enum/query2` | Utilitas | Melakukan kueri atas enum dinamis seperti status dan daftar bahasa. | Tidak memerlukan tanda tangan. |

## Membuat Tugas Video

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

Alur kerja umum yang menggunakan endpoint ini:

| Alur Kerja | Sinyal yang Diperlukan | Halaman Awal |
| --- | --- | --- |
| Penghapusan subtitel/teks | `needChineseOcclude: 1`, `2`, atau `3`; Advanced Lite/Pro melalui `extraOptions.extra_inpaint_config` | [Penghapusan subtitel dan teks video](./video-subtitle-removal.md) |
| Penerjemahan/dubbing video | `needWanyin: 1`, `sourceLang`, `lang`, `wyTaskType` | [Penerjemahan video](./video-translation.md) |
| Penerjemahan teks di layar | `needChineseOcclude: 11`, `sourceLang`, `lang`, `videoInpaintLang` | [Penerjemahan video](./video-translation.md) |
| Ekstraksi subtitel OCR | `needChineseOcclude: 14`, `videoInpaintMasks`, `videoInpaintLang` | [Ekstraksi subtitel](./subtitle-extraction.md) |
| Ekstraksi subtitel ASR | `needWanyin: 1`, `wyTaskType: "ONLY_ASR"`, `wyNeedText: 0` | [Ekstraksi subtitel](./subtitle-extraction.md) |

Permintaan minimal:

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

Kolom yang umum dalam respons pembuatan:

| Kolom | Makna |
| --- | --- |
| `idProject` | ID batch/proyek. |
| `dataList[].id` | ID pekerjaan untuk polling status dan pencocokan callback. |
| `dataList[].url` | URL sumber yang diterima untuk diproses. |

## Kueri Status Video

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

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

Nilai status:

| `processStatus` | Makna | Perilaku Klien |
| --- | --- | --- |
| `< 1` | Sedang diproses. | Lakukan polling lagi nanti atau tunggu callback. |
| `1` | Berhasil. | Baca URL hasil dan simpan secara persisten. |
| `> 1` | Gagal. | Tampilkan `errorDetail`. Tugas yang gagal tidak mengurangi kredit apa pun. |

Tugas video yang berhasil dapat menyertakan `videoUrl`, `coverUrl`, `srcSrtUrl`, `tgtSrtUrl`, `sourceVideoUrl`, `ttsMetaResult`, `wyVoiceParam`, dan metadata tugas.

## Tugas Gambar

Endpoint pembuatan publik saat ini:

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

Endpoint pengerjaan ulang:

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

Permintaan penerjemahan gambar:

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

Permintaan penghapusan teks gambar:

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

Baca [Penerjemahan gambar](./image-translation.md) sebelum mengimplementasikan tugas gambar karena `downloadInfo`, `downloadInfos`, dan `result` untuk pengerjaan ulang harus mempertahankan format string yang didokumentasikan.

## Kueri Enum

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

Endpoint ini tidak memerlukan `AppSign`.

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

Nama enum yang umum:

| `text` | Tujuan |
| --- | --- |
| `ProcessStatus` | Kode status tugas video. |
| `ImageTaskStatus` | Kode status tugas gambar. |
| `sourceLang` | Daftar bahasa sumber untuk penerjemahan video. |
| `Lang` | Daftar bahasa target untuk penerjemahan video. |
| `musicRegion` | Daftar wilayah musik cerdas jika didukung. |

## Penagihan, Batas, dan Retensi

| Topik | Aturan |
| --- | --- |
| Durasi video | Batas mutlak saat ini adalah 15 menit per file video. Bagi media yang lebih panjang menjadi segmen dengan durasi kurang dari 15 menit, misalnya 14:59, untuk menghindari masalah pembulatan durasi. |
| Ukuran video | Batas mutlak saat ini adalah 1000 MB per file video. Kompres file yang terlalu besar sebelum dikirimkan. |
| Batas gambar | Maksimum `2000*2000 px`, maksimum `50 MB`, format yang didukung `png`, `jpeg`, `jpg`, `bmp`, `webp`; URL gambar tidak boleh berisi aksara Tionghoa. |
| Unit penagihan | Alur kerja video ditagih dalam unit 30 detik. Video yang lebih pendek dari 30 detik dihitung sebagai 30 detik. |
| Layanan gabungan | Menggabungkan layanan seperti penghapusan teks dan penerjemahan suara dapat menyebabkan biaya terakumulasi. |
| Tugas yang akhirnya gagal | Tugas yang akhirnya gagal (`processStatus > 1`) tidak mengurangi kredit. |
| Retensi | Data yang dihasilkan oleh API mengikuti aturan retensi web Weydub. Secara default, file sumber dan output hasil render dari 30 hari terakhir disimpan. Unduh dan simpan aset penting setelah callback. |
| CRF | CRF video default adalah `17`, tanpa kehilangan kualitas yang terlihat untuk sebagian besar kebutuhan distribusi. Nilai yang lebih rendah seperti `15` atau `16` mungkin tersedia melalui `extraOptions.write_options` dan dapat menambah biaya bandwidth/penyimpanan. |

## Ringkasan callback

Sertakan URL `callback` dalam permintaan pembuatan jika didukung. Weydub mengirimkan item pekerjaan yang telah selesai langsung ke server Anda, tanpa pembungkus luar `code` / `msg` / `body` yang digunakan oleh respons polling.

Aturan penanganan callback:

- Verifikasi `Callback-Sign` menggunakan body mentah permintaan callback dan `AppSecret` Anda.
- Kembalikan HTTP 200 beserta body apa pun yang tidak kosong hanya setelah penyimpanan persisten berhasil.
- Buat handler idempoten berdasarkan ID pekerjaan/tugas.
- Callback yang gagal untuk tugas yang dibuat dalam 24 jam terakhir dicoba ulang kira-kira setiap 30 menit.
- Jika proses ulang mengubah konten video atau gambar, URL output dapat berubah; simpan URL hasil terbaru.

Baca [Model tugas asinkron](./async-task-model.md) untuk mengetahui detail callback.

## Pemecahan masalah

| Gejala | Kemungkinan penyebab | Yang perlu diperiksa |
| --- | --- | --- |
| Kesalahan tanda tangan | Byte body berubah setelah penandatanganan, atau JSON berformat rapi ditandatangani tetapi JSON ringkas dikirim. | Catat hash body yang tidak bersifat rahasia dan bandingkan jalur kode penandatanganan dan pengiriman. |
| Tugas dibuat tetapi tidak ada hasil | Pemrosesan asinkron masih berlangsung. | Lakukan polling terhadap `/v-w-c/gateway/ve/work/status` atau tunggu callback. |
| URL output tidak ada | Mode alur kerja salah atau tugas belum mencapai status terminal. | Konfirmasikan `processStatus === 1` dan periksa kolom output khusus alur kerja. |
| Callback tidak tercermin di aplikasi Anda | Handler mengembalikan respons sebelum penyimpanan persisten, verifikasi tanda tangan gagal, atau tidak cocok dengan ID pekerjaan. | Simpan payload callback mentah, bandingkan `Callback-Sign`, dan buat pembaruan idempoten. |
| Endpoint tidak tersedia | Hak akses akun belum diaktifkan. | Konfirmasikan akses API untuk jenis tugas tertentu. |
| Kesalahan karena batas mutlak video | Video lebih panjang dari 15 menit atau lebih besar dari 1000 MB. | Bagi menjadi beberapa segmen atau kompres sebelum dikirim. |
| Kesalahan karena batas mutlak gambar | Gambar melebihi `2000*2000 px`, melebihi `50 MB`, tidak didukung, atau URL berisi karakter Tionghoa. | Ubah ukuran, kompres ulang, ganti nama/enkode URL, lalu coba lagi. |

## Kontrak Agen

Agen otomasi harus:

- Muat [llms.txt](./llms.txt) dan [Weydub API Keahlian](./weydub-api-skill.md).
- Gunakan [Skenario demo](./demo-scenarios.md) sebelum menggunakan media pelanggan.
- Simpan kredensial dalam variabel lingkungan atau pengelola rahasia.
- Simpan ID secara persisten sebelum melaporkan keberhasilan kepada pengguna.
- Modelkan pekerjaan sebagai `submitted -> processing -> succeeded | failed | timed_out`.
- Jangan pernah mengekspos `AppSecret` atau mengada-adakan endpoint yang aktif.