# Referencia de la API

Esta referencia ofrece a desarrolladores y agentes de automatización un único lugar conciso donde consultar los endpoints de la API de Weydub, las comprobaciones de acceso, la estructura de las solicitudes, el comportamiento asíncrono, las reglas de facturación y retención y las señales para solucionar problemas.

## Fundamentos de las solicitudes

| Elemento | Valor |
| --- | --- |
| URL base | `https://api.zhaoli.com` |
| Protocolo | HTTPS |
| Método | `POST` para las llamadas a la API documentadas |
| Codificación | UTF-8 |
| Tipo de contenido | `application/json` |
| Autenticación | Encabezados `AppKey` y `AppSign`, excepto en los endpoints marcados explícitamente como no firmados |

Es posible que algunos nombres de infraestructura heredada sigan apareciendo en recursos públicos de demostración o en rutas antiguas de cuentas. Considera esta documentación de la API de Weydub como el contrato vigente de cara al producto.

## Antes de realizar una llamada

| Comprobación | Qué debes confirmar | Por qué es importante |
| --- | --- | --- |
| Acceso a la API | Tu cuenta de Weydub con sesión iniciada puede activar gratis el acceso a la API; confirma los permisos específicos del flujo cuando sea necesario. | Algunas familias de tareas, especialmente la traducción de imágenes y el doblaje de gran carga emocional, pueden habilitarse por cuenta. |
| Credenciales | Tienes `AppKey` y `AppSecret`, almacenados como secretos del backend. | `AppSecret` nunca debe aparecer en código frontend, repositorios públicos, registros, capturas de pantalla ni prompts. |
| URL de contenido multimedia | Los archivos de origen son accesibles públicamente y permanecen estables durante el periodo de procesamiento. | Los workers de Weydub necesitan descargar el contenido multimedia de origen antes de procesarlo. |
| URL de callback | Los callbacks de producción devuelven HTTP 200 y un cuerpo no vacío solo después de completar el almacenamiento duradero. | Las tareas asíncronas pueden finalizar después de que se haya devuelto la solicitud original. |
| Almacenamiento de resultados | Tu servicio almacena los ID de trabajo, los ID de tarea, el estado, las URL de resultados y los errores. | Los recursos generados pueden estar sujetos a la política de retención, así que copia rápidamente las referencias duraderas. |

## Autenticación

La mayoría de las solicitudes usan estos encabezados:

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

Firma el cuerpo JSON compacto exacto que se enviará. Lee [Autenticación y firma](./auth-and-signing.md) antes de depurar errores de firma.

Excepción sin firma:

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

El endpoint de consulta de enumeraciones se utiliza para obtener listas dinámicas de idiomas y estados y no requiere firma.

## Índice de endpoints

| Método | Ruta | Familia | Finalidad | Notas de acceso |
| --- | --- | --- | --- | --- |
| `POST` | `/v-w-c/gateway/ve/work/free` | Vídeo | Crea la mayoría de las tareas de vídeo: eliminación de subtítulos/texto, traducción de vídeo, extracción OCR de subtítulos, extracción ASR y renderizado de subtítulos. | Requiere acceso principal a la API. |
| `POST` | `/v-w-c/gateway/ve/work/status` | Vídeo | Consulta el estado y los campos de resultados de tareas de vídeo mediante ID de trabajo. | Úsalo después de crear una tarea o como alternativa al callback. |
| `POST` | `/v-w-c/gateway/ve/work/list` | Vídeo | Consulta el historial de tareas de vídeo. | Útil para paneles internos y conciliación. |
| `POST` | `/v-w-c/gateway/ve/work/video/inpaint/redo` | Vídeo | Repite la eliminación de texto/relleno generativo con máscaras ajustadas. | Requiere el contexto de un trabajo o una tarea existente. |
| `POST` | `/v-w-c/gateway/ve/work/translationPro/redo` | Vídeo | Repite la traducción/el doblaje con ajustes en los subtítulos, la sincronización o la configuración de voz. | Requiere el contexto de una tarea de traducción existente. |
| `POST` | `/v-w-c/gateway/ve/work/voice/incorporate` | Vídeo | Crea tareas de clonación de voz y doblaje de gran carga emocional. | Confirma el permiso de la cuenta antes de dirigir tráfico de producción. |
| `POST` | `/v-w-c/gateway/ve/image/translate` | Imagen | Crea una tarea de eliminación o traducción de texto en imágenes. | Puede requerir permiso para el flujo de imágenes tras activar el acceso gratuito a la API. |
| `POST` | `/v-w-c/gateway/ve/image/translate/redo` | Imagen | Vuelve a generar una tarea de imagen después de editar los metadatos de texto/estilo del resultado. | Requiere un ID de tarea de imagen existente y el JSON del resultado. |
| `POST` | `/v-w-c/ve/image/translate/task/launch` | Imagen heredada/web | Crea una única tarea de imagen en flujos antiguos de cuenta o web. | Úsalo solo cuando esté confirmado para la cuenta. |
| `POST` | `/v-w-c/ve/image/translate/task/launch2` | Imagen heredada/web | Crea una tarea de imagen por lotes en flujos antiguos de cuenta o web. | Confirma los límites de los lotes y la política de callbacks. |
| `POST` | `/v-w-c/ve/image/translate/task/query` | Imagen heredada/web | Consulta una tarea de imagen en flujos antiguos de cuenta o web. | Consulta hasta alcanzar un estado final antes de leer los resultados. |
| `POST` | `/v-w-c/enum/query2` | Utilidad | Consulta enumeraciones dinámicas, como estados y listas de idiomas. | No requiere firma. |

## Crear una tarea de vídeo

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

Flujos habituales que usan este endpoint:

| Flujo | Señal requerida | Página inicial |
| --- | --- | --- |
| Eliminación de subtítulos/texto | `needChineseOcclude: 1`, `2` o `3`; Advanced Lite/Pro mediante `extraOptions.extra_inpaint_config` | [Eliminación de subtítulos y texto de vídeo](https://weydub.com/docs/api/video-subtitle-removal.md) |
| Traducción/doblaje de vídeo | `needWanyin: 1`, `sourceLang`, `lang`, `wyTaskType` | [Traducción de vídeo](https://weydub.com/docs/api/video-translation.md) |
| Traducción de texto en pantalla | `needChineseOcclude: 11`, `sourceLang`, `lang`, `videoInpaintLang` | [Traducción de vídeo](https://weydub.com/docs/api/video-translation.md) |
| Extracción OCR de subtítulos | `needChineseOcclude: 14`, `videoInpaintMasks`, `videoInpaintLang` | [Extracción de subtítulos](./subtitle-extraction.md) |
| Extracción ASR de subtítulos | `needWanyin: 1`, `wyTaskType: "ONLY_ASR"`, `wyNeedText: 0` | [Extracción de subtítulos](./subtitle-extraction.md) |

Solicitud mínima:

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

Campos habituales de la respuesta de creación:

| Campo | Significado |
| --- | --- |
| `idProject` | ID del lote/proyecto. |
| `dataList[].id` | ID del trabajo para consultar el estado y asociar callbacks. |
| `dataList[].url` | URL de origen aceptada para su procesamiento. |

## Consultar el estado de un vídeo

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

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

Valores de estado:

| `processStatus` | Significado | Comportamiento del cliente |
| --- | --- | --- |
| `< 1` | En proceso. | Vuelve a consultar más tarde o espera al callback. |
| `1` | Completado correctamente. | Lee las URL de resultados y guárdalas. |
| `> 1` | Fallido. | Muestra `errorDetail`. Las tareas fallidas no descuentan créditos. |

Las tareas de vídeo completadas pueden incluir `videoUrl`, `coverUrl`, `srcSrtUrl`, `tgtSrtUrl`, `sourceVideoUrl`, `ttsMetaResult`, `wyVoiceParam` y metadatos de la tarea.

## Tareas de imagen

Endpoint público actual de creación:

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

Endpoint para repetir:

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

Solicitud de traducción de imagen:

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

Solicitud de eliminación de texto de imagen:

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

Lee [Traducción de imágenes](https://weydub.com/docs/api/image-translation.md) antes de implementar tareas de imagen, porque `downloadInfo`, `downloadInfos` y el `result` de una repetición deben mantener la estructura de cadena documentada.

## Consulta de enumeraciones

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

Este endpoint no requiere `AppSign`.

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

Nombres habituales de enumeraciones:

| `text` | Finalidad |
| --- | --- |
| `ProcessStatus` | Códigos de estado de tareas de vídeo. |
| `ImageTaskStatus` | Códigos de estado de tareas de imagen. |
| `sourceLang` | Lista de idiomas de origen para la traducción de vídeo. |
| `Lang` | Lista de idiomas de destino para la traducción de vídeo. |
| `musicRegion` | Lista de regiones para música inteligente cuando esté disponible. |

## Facturación, límites y retención

| Tema | Regla |
| --- | --- |
| Duración del vídeo | El límite estricto actual es de 15 minutos por archivo de vídeo. Divide el contenido más largo en segmentos de menos de 15 minutos, por ejemplo 14:59, para evitar problemas de redondeo de la duración. |
| Tamaño del vídeo | El límite estricto actual es de 1000 MB por archivo de vídeo. Comprime los archivos demasiado grandes antes de enviarlos. |
| Límites de imagen | Máximo de `2000*2000 px` y `50 MB`; formatos compatibles: `png`, `jpeg`, `jpg`, `bmp`, `webp`. Las URL de imágenes no deben contener caracteres chinos. |
| Unidad de facturación | Los flujos de vídeo se facturan en unidades de 30 segundos. Un vídeo de menos de 30 segundos cuenta como 30 segundos. |
| Servicios combinados | Combinar servicios como la eliminación de texto y la traducción de voz puede acumular costes. |
| Tareas fallidas | Las tareas cuyo estado final sea fallido (`processStatus > 1`) no descuentan créditos. |
| Retención | Los datos generados mediante la API siguen las reglas de retención web de Weydub. De forma predeterminada, se conservan los archivos de origen y los resultados renderizados de los últimos 30 días. Descarga y almacena los recursos importantes después del callback. |
| CRF | El CRF de vídeo predeterminado es `17`, visualmente sin pérdidas para la mayoría de las distribuciones. Es posible que haya valores más bajos, como `15` o `16`, disponibles mediante `extraOptions.write_options`, lo que puede añadir cargos por ancho de banda/almacenamiento. |

## Resumen de callbacks

Incluye una URL `callback` en las solicitudes de creación cuando sea compatible. Weydub envía directamente el elemento de trabajo completado a tu servidor, sin el envoltorio externo `code` / `msg` / `body` usado por las respuestas de consulta periódica.

Reglas para gestionar callbacks:

- Verifica `Callback-Sign` con el cuerpo sin procesar de la solicitud de callback y tu `AppSecret`.
- Devuelve HTTP 200 y cualquier cuerpo no vacío solo después de completar correctamente el almacenamiento duradero.
- Haz que los controladores sean idempotentes mediante el ID de trabajo/tarea.
- Los callbacks fallidos de tareas creadas en las últimas 24 horas se reintentan aproximadamente cada 30 minutos.
- Si una repetición cambia el contenido de vídeo o imagen, la URL de salida puede cambiar; almacena la URL del resultado más reciente.

Lee [Modelo de tarea asíncrona](https://weydub.com/docs/api/async-task-model.md) para obtener información detallada sobre los callbacks.

## Solución de problemas

| Síntoma | Causa probable | Comprobación |
| --- | --- | --- |
| Error de firma | Los bytes del cuerpo cambiaron después de firmarlo, o se firmó un JSON con formato legible y se envió un JSON compacto. | Registra un hash no secreto del cuerpo y compara las rutas de código de firma y envío. |
| Tarea creada pero sin resultado | El procesamiento asíncrono aún está en curso. | Consulta `/v-w-c/gateway/ve/work/status` o espera al callback. |
| Falta la URL de salida | Modo de flujo incorrecto o tarea no finalizada. | Confirma `processStatus === 1` e inspecciona los campos de salida específicos del flujo. |
| El callback no aparece reflejado en tu aplicación | El controlador respondió antes de completar el almacenamiento duradero, no superó la verificación de firma o no asoció el ID de trabajo. | Almacena la carga útil sin procesar del callback, compara `Callback-Sign` y haz que las actualizaciones sean idempotentes. |
| Endpoint no disponible | El permiso de la cuenta no está activado. | Confirma el acceso a la API para la familia de tareas específica. |
| Error de límite estricto de vídeo | El vídeo dura más de 15 minutos o supera los 1000 MB. | Segmenta o comprime antes de enviarlo. |
| Error de límite estricto de imagen | La imagen supera `2000*2000 px` o `50 MB`, no tiene un formato compatible o su URL contiene caracteres chinos. | Cambia el tamaño, vuelve a comprimir, cambia el nombre/codifica la URL y reintenta. |

## Contrato para agentes

Los agentes de automatización deben:

- Cargar [llms.txt](https://weydub.com/docs/api/llms.txt) y [Weydub API Skill](https://weydub.com/docs/api/weydub-api-skill.md).
- Usar [Escenarios de demostración](https://weydub.com/docs/api/demo-scenarios.md) antes de procesar contenido multimedia de clientes.
- Mantener las credenciales en variables de entorno o en un gestor de secretos.
- Guardar los ID antes de informar del éxito a los usuarios.
- Modelar las tareas como `submitted -> processing -> succeeded | failed | timed_out`.
- No exponer nunca `AppSecret` ni inventar endpoints habilitados.