> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Wan Videos Generation API Integración
> Tongyi Wansiang Video Generation 集成指南 - XHuoAPI
Este documento presentará una descripción de la integración de la API de Wan Videos Generation, que permite generar videos oficiales de Tongyi Wanxiang mediante la entrada de parámetros personalizados.
## Proceso de Solicitud
Para utilizar la API, primero debe ir a la página correspondiente de [Wan Videos Generation API](https://api.xhuoapi.ai/documents/52b0f490-1bbf-4fe5-b60e-96626d333d2c) para solicitar el servicio correspondiente. Una vez en la página, haga clic en el botón "Acquire", como se muestra en la imagen:
Si aún no ha iniciado sesión o registrado, será redirigido automáticamente a la página de inicio de sesión, invitándolo a registrarse e iniciar sesión. Después de registrarse e iniciar sesión, será redirigido automáticamente a la página actual.
En la primera solicitud, se otorgará un límite gratuito que permite usar la API sin costo.
## Uso Básico
Primero, debe comprender la forma básica de uso, que consiste en ingresar la palabra clave `prompt`, la acción de generación `action`, la imagen de referencia del primer fotograma `image_url` y el modelo `model`, para obtener el resultado procesado. Primero, necesita pasar un campo `action`, cuyo valor es `text2video`, que incluye dos tipos de acciones: video generado por texto (`text2video`) y video generado por imagen (`image2video`). Luego, también necesitamos ingresar el modelo `model`, que actualmente incluye los modelos `wan2.6-i2v`, `wan2.6-r2v`, `wan2.6-i2v-flash`, `wan2.6-t2v`, con los siguientes detalles:
Aquí podemos ver que hemos configurado los Request Headers, que incluyen:
* `accept`: el formato de respuesta que desea recibir, aquí se establece como `application/json`, es decir, formato JSON.
* `authorization`: la clave para llamar a la API, que puede seleccionarse directamente después de la solicitud.
Además, se ha configurado el Request Body, que incluye:
* `model`: el modelo para generar el video, que incluye principalmente `wan2.6-i2v`, `wan2.6-r2v`, `wan2.6-i2v-flash`, `wan2.6-t2v`.
* `action`: la acción de la tarea de generación de video, que incluye tres tipos de acciones: video generado por texto (`text2video`), video generado por imagen (`image2video`). Cuando es video generado por texto, actualmente solo se admite el modelo `wan2.6-t2v`. Cuando es video generado por imagen, actualmente solo se admiten los modelos `wan2.6-i2v`, `wan2.6-r2v`, `wan2.6-i2v-flash`.
* `image_url`: cuando se elige la acción de video generado por imagen `image2video`, es necesario subir el enlace de la imagen de referencia del primer fotograma. Actualmente, solo se admiten los modelos `wan2.6-i2v`, `wan2.6-i2v-flash`.
* `reference_video_urls`: opcional al generar video por imagen, especifica el enlace de video de referencia para la generación. Actualmente, solo se admite el modelo `wan2.6-r2v`.
* `size`: especifica la resolución del video generado, en el formato ancho\*alto. El valor predeterminado de este parámetro y los valores enumerados disponibles dependen del parámetro model, las reglas específicas se pueden consultar en [documentación oficial](https://modelstudio.console.alibabacloud.com/ap-southeast-1/?tab=api#/api/?type=model\&url=2865250).
* `duration`: la duración de la generación del video, principalmente admite 5, 10, 15.
* `shot_type`: opcional, especifica el tipo de plano del video generado, es decir, si el video consiste en un plano continuo o múltiples planos alternos. Condición de efectividad: solo es efectivo cuando "prompt\_extend": true. Prioridad de parámetros: shot\_type > prompt. Por ejemplo, si shot\_type se establece en "single", incluso si el prompt incluye "generar video de múltiples planos", el modelo seguirá produciendo un video de un solo plano. Las reglas específicas se pueden consultar en [documentación oficial](https://modelstudio.console.alibabacloud.com/ap-southeast-1/?tab=api#/api/?type=model\&url=2865250).
* `negative_prompt`: opcional, palabra clave inversa, utilizada para describir el contenido que no desea ver en el video, puede limitar el contenido del video. Admite chino e inglés, con una longitud no superior a 500 caracteres; el exceso se truncará automáticamente. Ejemplo de valores: baja resolución, errores, calidad más baja, baja calidad, defectos, dedos adicionales, proporciones inadecuadas, etc.
* `resolution`: especifica el nivel de resolución del video generado, utilizado para ajustar la claridad del video (total de píxeles). El modelo ajustará automáticamente la escala a un total de píxeles cercano según la resolución seleccionada, y la relación de aspecto del video se mantendrá lo más posible en línea con la relación de aspecto de la imagen de entrada img\_url. Más detalles se pueden consultar en [documentación oficial](https://modelstudio.console.alibabacloud.com/ap-southeast-1/?tab=api#/api/?type=model\&url=2867393).
* `audio_url`: URL del archivo de audio, el modelo utilizará este audio para generar el video. El método de uso se puede consultar en [documentación oficial](https://modelstudio.console.alibabacloud.com/ap-southeast-1/?tab=api#/api/?type=model\&url=2867393).
* `audio`: si se generará un video con sonido. Prioridad de parámetros: audio > audio\_url. Cuando audio=false, incluso si se proporciona audio\_url, la salida seguirá siendo un video sin sonido, y la facturación se calculará como video sin sonido; el valor predeterminado es true.
* `prompt_extend`: si se habilita la reescritura inteligente del prompt. Al habilitarlo, se utiliza un modelo grande para reescribir inteligentemente el prompt de entrada. La mejora en la generación de prompts más cortos es notable, pero aumentará el tiempo de procesamiento; el valor predeterminado es true.
* `prompt`: palabra clave.
* `callback_url`: URL donde se necesita la devolución de resultados.
Después de seleccionar, puede ver que también se ha generado el código correspondiente a la derecha, como se muestra en la imagen:
Haga clic en el botón "Try" para realizar una prueba, como se muestra en la imagen anterior, y obtendremos el siguiente resultado:
```json theme={null}
{
"success": true,
"video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=",
"state": "completed",
"task_id": "a4bca552-d964-46a1-8ff7-fd922f916582"
}
```
El resultado devuelto tiene varios campos, que se describen a continuación:
* `success`, el estado de la tarea de generación de video en este momento.
* `task_id`, el ID de la tarea de generación de video en este momento.
* `video_url`, el enlace del video de la tarea de generación de video en este momento.
* `state`, el estado de la tarea de generación de video en este momento.
Podemos ver que hemos obtenido la información del video deseado, solo necesitamos obtener el video de Tongyi Wanxiang generado a partir de la dirección del enlace de video `video_url` en el resultado.
Además, si desea generar el código de integración correspondiente, puede copiarlo directamente, por ejemplo, el código de CURL es el siguiente:
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/wan/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"action": "text2video",
"model": "wan2.6-t2v",
"prompt": "Astronautas se trasladan del espacio a un volcán",
"duration": 5
}'
```
## Función de Video Generado por Imagen
Si desea generar un video a partir de una imagen de referencia o un video de referencia, puede establecer el parámetro `action` en `image2video`, y luego ingresar el enlace de la imagen de referencia o el enlace del video de referencia. A continuación, debemos completar los siguientes pasos con las palabras clave que necesitamos para personalizar la generación del video, pudiendo especificar el siguiente contenido:
* `model`: el modelo para generar el video, que incluye los modelos `wan2.6-i2v`, `wan2.6-r2v`, `wan2.6-i2v-flash`, `wan2.6-t2v`.
* `image_url`: cuando se elige la acción de generar video a partir de imagen `image2video`, es necesario subir el enlace de la imagen de referencia para el primer fotograma, actualmente solo se admiten los modelos `wan2.6-i2v`, `wan2.6-i2v-flash`.
* `reference_video_urls`: opcional al generar video a partir de imagen, especifica el enlace del video de referencia para la generación, actualmente solo se admite el modelo `wan2.6-r2v`.
* `prompt`: palabras clave.
Un ejemplo de llenado es el siguiente:
Una vez completado, se generó automáticamente el siguiente código:
El código correspondiente en Python:
```python theme={null}
import requests
url = "https://api.xhuoapi.ai/v1/wan/videos"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"action": "image2video",
"model": "wan2.6-i2v",
"prompt": "Astronautas se trasladan del espacio a un volcán",
"duration": 5,
"image_url": "https://cdn.xhuoapi.ai/r9vsv9.png",
"callback_url": "https://www.baidu.com/"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
Al hacer clic en ejecutar, se puede observar que se obtiene un resultado como el siguiente:
```json theme={null}
{
"success": true,
"video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=",
"state": "completed",
"task_id": "a4bca552-d964-46a1-8ff7-fd922f916582"
}
```
Se puede ver que el contenido del resultado es consistente con el anterior, lo que también logra la función de extensión de video.
## Callback Asíncrono
Dado que el tiempo de generación de la API de Wan Videos es relativamente largo, aproximadamente de 1 a 2 minutos, si la API no responde durante mucho tiempo, la solicitud HTTP mantendrá la conexión, lo que provocará un consumo adicional de recursos del sistema. Por lo tanto, esta API también ofrece soporte para callbacks asíncronos.
El flujo general es: cuando el cliente inicia la solicitud, se especifica un campo adicional `callback_url`. Después de que el cliente realiza la solicitud a la API, la API devolverá inmediatamente un resultado que incluye un campo `task_id`, que representa el ID de la tarea actual. Cuando la tarea se completa, el resultado del video generado se enviará al `callback_url` especificado por el cliente en formato JSON POST, que también incluirá el campo `task_id`, de modo que el resultado de la tarea se pueda asociar mediante el ID.
A continuación, entenderemos cómo operar a través de un ejemplo.
Primero, el callback de Webhook es un servicio que puede recibir solicitudes HTTP, y el desarrollador debe reemplazarlo con la URL de su propio servidor HTTP. Para facilitar la demostración, se utiliza un sitio web de muestra de Webhook público [https://webhook.site/](https://webhook.site/), al abrir este sitio se obtiene una URL de Webhook, como se muestra en la imagen:
Copie esta URL y podrá usarla como Webhook, el ejemplo aquí es `https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3`.
A continuación, podemos establecer el campo `callback_url` en la URL de Webhook anterior, al mismo tiempo que ingresamos los parámetros correspondientes, el contenido específico se muestra en la imagen:
Al hacer clic en ejecutar, se puede observar que se obtiene inmediatamente un resultado como el siguiente:
```
{
"task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}
```
Después de un momento, podemos observar el resultado del video generado en `https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3`, como se muestra en la imagen:
El contenido es el siguiente:
```json theme={null}
{
"success": true,
"video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=",
"state": "completed",
"task_id": "a4bca552-d964-46a1-8ff7-fd922f916582"
}
```
Se puede ver que en el resultado hay un campo `task_id`, y los otros campos son similares a los anteriores, a través de este campo se puede lograr la asociación de tareas.
## Manejo de Errores
Al llamar a la API, si se encuentra con un error, la API devolverá el código de error y la información correspondiente. Por ejemplo:
* `400 token_mismatched`: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
* `400 api_not_implemented`: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
* `401 invalid_token`: No autorizado, token de autorización inválido o faltante.
* `429 too_many_requests`: Demasiadas solicitudes, ha superado el límite de tasa.
* `500 api_error`: Error interno del servidor, algo salió mal en el servidor.
### Ejemplo de Respuesta de Error
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## Conclusión
A través de este documento, ha aprendido cómo usar la API de Generación de Videos de Wan, que permite generar videos mediante la entrada de palabras clave y una imagen de referencia para el primer fotograma. Esperamos que este documento le ayude a integrar y utilizar mejor esta API. Si tiene alguna pregunta, no dude en ponerse en contacto con nuestro equipo de soporte técnico.