# Riferimento API

Questo riferimento offre a sviluppatori e agenti di automazione un unico punto di consultazione compatto in cui trovare gli endpoint API di Weydub, i controlli di accesso, la struttura delle richieste, il comportamento asincrono, le regole di fatturazione e conservazione e gli indicatori per la risoluzione dei problemi.

## Nozioni di base sulle richieste

| Elemento | Valore |
| --- | --- |
| URL di base | `https://api.zhaoli.com` |
| Protocollo | HTTPS |
| Metodo | `POST` per le chiamate API documentate |
| Codifica | UTF-8 |
| Tipo di contenuto | `application/json` |
| Autenticazione | Intestazioni `AppKey` e `AppSign`, tranne per gli endpoint esplicitamente contrassegnati come privi di firma |

Alcuni nomi dell'infrastruttura legacy potrebbero ancora comparire nelle risorse demo pubbliche o nei percorsi degli account meno recenti. Considerare questa documentazione API di Weydub come il contratto attualmente valido per il prodotto.

## Prima di effettuare una chiamata

| Controllo | Che cosa verificare | Perché è importante |
| --- | --- | --- |
| Accesso API | L'account Weydub con cui hai effettuato l'accesso può attivare gratuitamente l'accesso API; quando necessario, verifica le abilitazioni specifiche del flusso di lavoro. | Alcune famiglie di attività, in particolare la traduzione di immagini e il doppiaggio ad alta espressività emotiva, possono essere abilitate per singolo account. |
| Credenziali | Disponi di `AppKey` e `AppSecret`, archiviati come segreti del backend. | `AppSecret` non deve mai comparire nel codice frontend, nei repository pubblici, nei log, negli screenshot o nei prompt. |
| URL dei contenuti multimediali | I file di origine sono raggiungibili pubblicamente e stabili per l'intera finestra di elaborazione. | I sistemi di elaborazione di Weydub devono scaricare i contenuti multimediali di origine prima dell'elaborazione. |
| URL di callback | Le callback di produzione restituiscono HTTP 200 e un corpo non vuoto solo dopo l'archiviazione persistente. | Le attività asincrone possono completarsi dopo che la richiesta originale ha già ricevuto risposta. |
| Archiviazione dei risultati | Il tuo servizio archivia gli ID delle elaborazioni, gli ID delle attività, lo stato, gli URL dei risultati e gli errori. | Le risorse generate possono essere soggette ai criteri di conservazione, quindi copia rapidamente i riferimenti permanenti. |

## Autenticazione

La maggior parte delle richieste usa le seguenti intestazioni:

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

Firma il corpo JSON compatto esattamente come verrà inviato. Leggi [Autenticazione e firma](./auth-and-signing.md) prima di eseguire il debug degli errori di firma.

Eccezione senza firma:

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

L'endpoint di interrogazione delle enumerazioni viene utilizzato per gli elenchi dinamici di lingue e stati e non richiede la firma.

## Indice degli endpoint

| Metodo | Percorso | Famiglia | Scopo | Note sull'accesso |
| --- | --- | --- | --- | --- |
| `POST` | `/v-w-c/gateway/ve/work/free` | Video | Creare la maggior parte delle attività video: rimozione di sottotitoli/testo, traduzione video, estrazione OCR dei sottotitoli, estrazione ASR e rendering dei sottotitoli. | È richiesto l'accesso API di base. |
| `POST` | `/v-w-c/gateway/ve/work/status` | Video | Interrogare lo stato delle attività video e i campi dei risultati in base agli ID delle elaborazioni. | Utilizzare dopo la creazione dell'attività o come alternativa alla callback. |
| `POST` | `/v-w-c/gateway/ve/work/list` | Video | Consultare lo storico delle attività video. | Utile per dashboard interne e riconciliazione. |
| `POST` | `/v-w-c/gateway/ve/work/video/inpaint/redo` | Video | Ripetere la rimozione del testo o l'inpainting con maschere modificate. | Richiede un contesto di elaborazione/attività esistente. |
| `POST` | `/v-w-c/gateway/ve/work/translationPro/redo` | Video | Ripetere la traduzione o il doppiaggio con sottotitoli, tempistiche o impostazioni vocali modificati. | Richiede il contesto di un'attività di traduzione esistente. |
| `POST` | `/v-w-c/gateway/ve/work/voice/incorporate` | Video | Creare attività di clonazione vocale e doppiaggio ad alta espressività emotiva. | Verificare l'abilitazione dell'account prima di instradare il traffico di produzione. |
| `POST` | `/v-w-c/gateway/ve/image/translate` | Immagine | Creare un'attività di rimozione del testo da un'immagine o di traduzione di un'immagine. | Potrebbe essere necessaria l'abilitazione al flusso di lavoro per le immagini dopo aver ottenuto l'accesso gratuito API. |
| `POST` | `/v-w-c/gateway/ve/image/translate/redo` | Immagine | Rigenerare un'attività immagine dopo aver modificato il testo del risultato o i metadati dello stile. | Richiede l'ID di un'attività immagine esistente e il JSON del risultato. |
| `POST` | `/v-w-c/ve/image/translate/task/launch` | Immagine legacy/web | Creare una singola attività immagine nei flussi web o degli account meno recenti. | Utilizzare solo se confermato per l'account. |
| `POST` | `/v-w-c/ve/image/translate/task/launch2` | Immagine legacy/web | Creare un'attività batch per immagini nei flussi web o degli account meno recenti. | Verificare i limiti dei batch e la politica di callback. |
| `POST` | `/v-w-c/ve/image/translate/task/query` | Immagine legacy/web | Interrogare una singola attività immagine nei flussi web o degli account meno recenti. | Eseguire il polling fino al raggiungimento di uno stato finale prima di leggere i risultati. |
| `POST` | `/v-w-c/enum/query2` | Utilità | Interrogare enumerazioni dinamiche, ad esempio gli elenchi degli stati e delle lingue. | Non è richiesta alcuna firma. |

## Creare un'attività video

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

Flussi di lavoro comuni che utilizzano questo endpoint:

| Flusso di lavoro | Segnale richiesto | Pagina iniziale |
| --- | --- | --- |
| Rimozione di sottotitoli/testo | `needChineseOcclude: 1`, `2` o `3`; Advanced Lite/Pro tramite `extraOptions.extra_inpaint_config` | [Rimozione di sottotitoli e testo dai video](./video-subtitle-removal.md) |
| Traduzione/doppiaggio video | `needWanyin: 1`, `sourceLang`, `lang`, `wyTaskType` | [Traduzione video](./video-translation.md) |
| Traduzione del testo sullo schermo | `needChineseOcclude: 11`, `sourceLang`, `lang`, `videoInpaintLang` | [Traduzione video](./video-translation.md) |
| Estrazione dei sottotitoli tramite OCR | `needChineseOcclude: 14`, `videoInpaintMasks`, `videoInpaintLang` | [Estrazione dei sottotitoli](./subtitle-extraction.md) |
| Estrazione dei sottotitoli tramite ASR | `needWanyin: 1`, `wyTaskType: "ONLY_ASR"`, `wyNeedText: 0` | [Estrazione dei sottotitoli](./subtitle-extraction.md) |

Richiesta minima:

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

Campi tipici della risposta alla creazione:

| Campo | Significato |
| --- | --- |
| `idProject` | ID del batch/progetto. |
| `dataList[].id` | ID del lavoro per il polling dello stato e la correlazione con la callback. |
| `dataList[].url` | URL di origine accettato per l'elaborazione. |

## Interrogazione dello stato del video

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

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

Valori di stato:

| `processStatus` | Significato | Comportamento del client |
| --- | --- | --- |
| `< 1` | In elaborazione. | Eseguire il polling in seguito o attendere la callback. |
| `1` | Operazione riuscita. | Leggere gli URL dei risultati e salvarli in modo persistente. |
| `> 1` | Operazione non riuscita. | Mostrare `errorDetail`. Le attività non riuscite non comportano alcuna detrazione di crediti. |

Le attività video completate correttamente possono includere `videoUrl`, `coverUrl`, `srcSrtUrl`, `tgtSrtUrl`, `sourceVideoUrl`, `ttsMetaResult`, `wyVoiceParam` e i metadati dell'attività.

## Attività relative alle immagini

Endpoint pubblico attuale per la creazione:

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

Endpoint di riesecuzione:

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

Richiesta di traduzione dell'immagine:

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

Richiesta di rimozione del testo dall'immagine:

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

Leggere [Traduzione delle immagini](./image-translation.md) prima di implementare le attività relative alle immagini, poiché `downloadInfo`, `downloadInfos` e `result` per la riesecuzione devono mantenere il formato stringa documentato.

## Interrogazione degli enum

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

Questo endpoint non richiede `AppSign`.

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

Nomi comuni degli enum:

| `text` | Scopo |
| --- | --- |
| `ProcessStatus` | Codici di stato delle attività video. |
| `ImageTaskStatus` | Codici di stato delle attività relative alle immagini. |
| `sourceLang` | Elenco delle lingue di origine per la traduzione video. |
| `Lang` | Elenco delle lingue di destinazione per la traduzione video. |
| `musicRegion` | Elenco delle regioni per la musica intelligente, laddove supportata. |

## Fatturazione, limiti e conservazione

| Argomento | Regola |
| --- | --- |
| Durata del video | Il limite massimo attuale è di 15 minuti per file video. Suddividere i contenuti multimediali più lunghi in segmenti di durata inferiore a 15 minuti, ad esempio 14:59, per evitare problemi di arrotondamento della durata. |
| Dimensione del video | Il limite massimo attuale è di 1000 MB per file video. Comprimere i file di dimensioni eccessive prima dell'invio. |
| Limiti delle immagini | Limite massimo `2000*2000 px`, limite massimo `50 MB`, formati supportati `png`, `jpeg`, `jpg`, `bmp`, `webp`; gli URL delle immagini non devono contenere caratteri cinesi. |
| Unità di fatturazione | I flussi di lavoro video sono fatturati in unità da 30 secondi. Un video di durata inferiore a 30 secondi viene conteggiato come 30 secondi. |
| Servizi combinati | La combinazione di servizi, come la rimozione del testo e la traduzione vocale, può comportare costi cumulativi. |
| Attività non riuscite | Le attività con esito negativo definitivo (`processStatus > 1`) non detraggono alcun credito. |
| Conservazione | I dati generati dall'API seguono le regole di conservazione web di Weydub. Per impostazione predefinita, vengono conservati i file sorgente e gli output renderizzati degli ultimi 30 giorni. Scaricare e archiviare le risorse importanti dopo il callback. |
| CRF | Il CRF video predefinito è `17`, senza perdite visibili nella maggior parte dei contesti di distribuzione. Valori inferiori, come `15` o `16`, potrebbero essere disponibili tramite `extraOptions.write_options` e possono comportare costi aggiuntivi per larghezza di banda/archiviazione. |

## Riepilogo dei callback

Specificare un URL di `callback` nelle richieste di creazione, quando supportato. Weydub invia l'elemento di lavoro completato direttamente al server, senza la struttura esterna `code` / `msg` / `body` utilizzata dalle risposte di polling.

Regole per la gestione dei callback:

- Verificare `Callback-Sign` utilizzando il corpo non elaborato della richiesta di callback e il proprio `AppSecret`.
- Restituire HTTP 200 insieme a un qualsiasi corpo non vuoto solo dopo che l'archiviazione persistente è stata completata correttamente.
- Rendere i gestori idempotenti in base all'ID del lavoro o dell'attività.
- I callback non riusciti relativi ad attività create nelle ultime 24 ore vengono ritentati all'incirca ogni 30 minuti.
- Se una riesecuzione modifica il contenuto del video o dell'immagine, l'URL di output può cambiare; archiviare l'URL più recente del risultato.

Consultare [Modello delle attività asincrone](./async-task-model.md) per i dettagli sui callback.

## Risoluzione dei problemi

| Sintomo | Causa probabile | Verifica |
| --- | --- | --- |
| Errore di firma | I byte del corpo sono cambiati dopo la firma oppure è stato firmato un JSON formattato, ma è stato inviato un JSON compatto. | Registrare un hash non segreto del corpo e confrontare i percorsi di codice per la firma e l'invio. |
| Attività creata ma nessun risultato | L'elaborazione asincrona è ancora in corso. | Eseguire il polling di `/v-w-c/gateway/ve/work/status` oppure attendere il callback. |
| URL di output mancante | Modalità del flusso di lavoro errata oppure attività non ancora in uno stato terminale. | Verificare `processStatus === 1` ed esaminare i campi di output specifici del flusso di lavoro. |
| Callback non riportato nell'applicazione | Il gestore ha restituito una risposta prima dell'archiviazione persistente, la verifica della firma non è riuscita oppure l'ID del lavoro non corrispondeva. | Archiviare il payload non elaborato del callback, confrontare `Callback-Sign` e rendere gli aggiornamenti idempotenti. |
| Endpoint non disponibile | L'account non dispone dell'abilitazione necessaria. | Verificare l'accesso API per la specifica famiglia di attività. |
| Errore relativo al limite massimo del video | Il video dura più di 15 minuti o supera 1000 MB. | Suddividere in segmenti o comprimere prima dell'invio. |
| Errore relativo al limite massimo dell'immagine | L'immagine supera `2000*2000 px`, supera `50 MB`, ha un formato non supportato oppure il relativo URL contiene caratteri cinesi. | Ridimensionare, ricomprimere e rinominare/codificare l'URL, quindi riprovare. |

## Contratto per gli agenti

Gli agenti di automazione dovrebbero:

- Caricare [llms.txt](./llms.txt) e [Skill API di Weydub](./weydub-api-skill.md).
- Utilizzare [Scenari demo](./demo-scenarios.md) prima di usare contenuti multimediali dei clienti.
- Conservare le credenziali nelle variabili di ambiente o in un gestore di segreti.
- Salvare in modo persistente gli ID prima di comunicare agli utenti l'esito positivo.
- Modellare le attività come `submitted -> processing -> succeeded | failed | timed_out`.
- Non esporre mai `AppSecret` né inventare endpoint abilitati.