Referencia de la API de edición de video HappyHorse - Alibaba Cloud Model Studio

El modelo de edición de video HappyHorse toma un video y una imagen de referencia como entrada, y realiza tareas de edición como transferencia de estilo y reemplazo local basándose en instrucciones de texto.

Disponibilidad

Asegúrese de que el modelo, la URL de endpoint y la clave de API pertenezcan todos a la misma región. Las llamadas entre regiones fallarán.

Seleccionar un modelo: Verifique a qué región pertenece el modelo.
Seleccionar una URL: Utilice la URL de endpoint correspondiente a la región. Se admiten URLs HTTP.
Configurar una clave de API: Seleccione una región y Cree una clave de API, luego Exporte la clave de API como variable de entorno.

NotaEl código de ejemplo en este tema aplica a la región de Singapur.

ImportanteAlibaba Cloud Model Studio ha lanzado dominios específicos de espacio de trabajo para las regiones de China (Beijing) y Singapur. Los nuevos dominios dedicados ofrecen un rendimiento superior y una mayor estabilidad para las solicitudes de inferencia. Recomendamos migrar a los nuevos dominios:

China (Pekín): de https://dashscope.aliyuncs.com a https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapur: de https://dashscope-intl.aliyuncs.com a https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} es su ID de espacio de trabajo, que se encuentra en la página Workspace Details de la consola de Alibaba Cloud Model Studio. El dominio existente permanece totalmente funcional.

Solicitud HTTP

Las tareas de edición de video consumen mucho tiempo (generalmente 1–5 minutos), por lo que la API utiliza llamadas asíncronas. El flujo de trabajo tiene dos pasos: "Crear una tarea -> Sondear resultado" como se describe a continuación:

Paso 1: Crear una tarea y obtener el ID de tarea

Singapore

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

EE. UU. (Virginia)

POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

China (Beijing)

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Germany (Frankfurt)

POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Japan (Tokyo)

POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

Nota

Después de crear la tarea, utilice el task_id devuelto para consultar el resultado. El task_id es válido durante 24 horas. No cree tareas duplicadas. En su lugar, utilice el sondeo para recuperar el resultado.
Para obtener orientación para principiantes, consulte Llamar a APIs con Postman o cURL.

Parámetros de solicitud

Encabezados

Content-Type string (Requerido)

El tipo de contenido de la solicitud. Debe ser application/json.

Authorization string (Requerido)

Autentica la solicitud con una clave API de Model Studio. Ejemplo: Bearer sk-xxxx.

X-DashScope-Async string (Requerido)

Habilita el procesamiento asíncrono. Las solicitudes HTTP solo admiten llamadas asíncronas. Debe ser enable.

ImportanteSi falta este encabezado de solicitud, se devuelve el error "current user api does not support synchronous calls".

Cuerpo de la solicitud

model string (Obligatorio)

El nombre del modelo.

Valor fijo: happyhorse-1.0-video-edit.

input object (Obligatorio)

La información de entrada, incluido el video a editar, las imágenes de referencia y el prompt.

Propiedades

prompt string (Obligatorio)

El prompt de texto que describe la edición deseada, como transferencia de estilo o reemplazo local.

Admite cualquier idioma. Máximo 5,000 caracteres no chinos o 2,500 caracteres chinos. El contenido que exceda este límite se truncará automáticamente.

media array (Obligatorio)

La lista de recursos multimedia, incluido el video a editar y las imágenes de referencia opcionales.

El arreglo debe contener exactamente 1 video elemento y opcionalmente puede contener 0–5 elementos de reference_image.

Propiedades del elemento

type string (Obligatorio)

El tipo de recurso multimedia. Debe ser uno de los siguientes:

video: Obligatorio. El video a editar.
reference_image: Opcional. Una imagen de referencia.

Límites de recursos:

Videos: exactamente 1.
Imágenes de referencia: 0–5.

url string (Obligatorio)

La URL del recurso multimedia.

Entrada de video (type=video)

Una URL de acceso público del video a editar.

Admite HTTP y HTTPS.
Ejemplo: https://xxx/xxx.mp4.

Requisitos de video:

Formato: MP4, MOV (se recomienda codificación H.264).
Duración: 3–60 segundos.
Resolución: el lado más largo no debe exceder 4,096 px; el lado más corto debe tener al menos 360 px.
Relación de aspecto: 1:2.5–2.5:1.
Tamaño de archivo: hasta 100 MB.
Tasa de fotogramas: 8-60 fps. Si el video de entrada tiene una tasa de fotogramas variable, asegúrese de que los cambios en la tasa de fotogramas permanezcan dentro de este rango.

NotaDuración del video de salida: 3–15 segundos.

Si el video de entrada tiene 15 segundos o menos, el video de salida tendrá la misma duración que la entrada.
Si el video de entrada dura más de 15 segundos, el sistema utiliza automáticamente solo los primeros 15 segundos, por lo que la duración máxima de salida es de 15 segundos.

Entrada de imagen (type=reference_image)

URL o datos codificados en Base64 de la imagen de referencia.

Requisitos de imagen:

Formato: JPEG, JPG, PNG, WEBP.
Resolución: tanto el ancho como la altura deben ser de al menos 300 px.
Relación de aspecto: 1:2.5–2.5:1.
Tamaño de archivo: hasta 20 MB.

Formatos de entrada admitidos:

URL pública:
- Admite HTTP y HTTPS.
- Ejemplo: https://xxx/xxx.png.
Cadena de imagen codificada en Base64:
- Formato: data:{MIME_type};base64,{base64_data}.
- Ejemplo: data:image/png;base64,GDU7MtCZzEbTbmRZ...... (truncado para demostración).
  Formato de datos de codificación Base64
  Formato: data:{MIME_type};base64,{base64_data} .
  - {base64_data}: La cadena codificada en Base64 del archivo de imagen.
  - {MIME_type}: El tipo de medio de la imagen, que debe coincidir con el formato del archivo.
  Formato de imagen
  Tipo MIME
  JPEG
  image/jpeg
  JPG
  image/jpeg
  PNG
  image/png
  WEBP
  image/webp

parameters object (Opcional)

Parámetros de edición de video como la resolución.

Propiedades

resolution string (Opcional)

Resolución del video generado.

Valores válidos:

1080P (predeterminado)
720P

watermark boolean (Opcional)

Indica si se debe agregar una marca de agua al video generado. La marca de agua aparece en la esquina inferior derecha con el texto "Happy Horse". El valor predeterminado es true.

true (predeterminado)
false

audio_setting string (Opcional)

Control de audio.

auto (predeterminado): Determinado por el modelo.
origin: Conserva el audio original del video de entrada.

seed integer (Opcional)

La semilla de número aleatorio debe ser un entero en el rango [0, 2147483647].

Si no se especifica, se genera una semilla aleatoria. Una semilla fija mejora la reproducibilidad.

Dado que la generación del modelo es probabilística, la misma semilla no garantiza resultados idénticos.

Edición de video (instrucción + imagen de referencia)

# The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "happyhorse-1.0-video-edit",
    "input": {
        "prompt": "Make the horse-headed humanoid character in the video wear the striped sweater from the image",
        "media": [
            {
                "type": "video",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260409/dozxak/Wan_Video_Edit_33_1.mp4"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260415/hynnff/wan-video-edit-clothes.webp"
            }
        ]
    },
    "parameters": {
        "resolution": "720P"
    }
}'

Parámetros de respuesta

output object

La información de salida de la tarea.

Propiedades

task_id string

El ID de la tarea. Válido para consultas durante 24 horas.

task_status string

El estado de la tarea.

Valores de enumeración

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: La tarea no existe o se desconoce su estado.

request_id string

Identificador único de solicitud para rastreo y solución de problemas.

code string

Código de error. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.

message string

Mensaje de error detallado. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.

Respuesta exitosa

Guarde el task_id para consultar el estado y el resultado de la tarea.

{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Respuesta de error

Error en la creación de la tarea. Consulte Códigos de error.

{
    "code": "InvalidApiKey",
    "message": "Invalid API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

Paso 2: Consultar resultados por ID de tarea

Singapore

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

EE. UU. (Virginia)

GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

China (Beijing)

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Germany (Frankfurt)

GET https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

Japan (Tokyo)

GET https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

Nota

Sondeo: La edición de video tarda varios minutos. Utilice un mecanismo de sondeo con un intervalo razonable (por ejemplo, 15 segundos) para verificar los resultados.
Flujo de estado de la tarea: PENDING (en cola) → RUNNING (procesando) → SUCCEEDED / FAILED.
Caducidad de task_id: El task_id caduca después de 24 horas. Después de la caducidad, ya no se pueden recuperar los resultados y la API devuelve un estado de tarea UNKNOWN.

Parámetros de solicitud

Encabezados

Authorization string (Requerido)

Autentica la solicitud con una clave API de Model Studio. Ejemplo: Bearer sk-xxxx.

Parámetros de ruta

task_id string (Obligatorio)

El ID de la tarea.

Consultar resultado de la tarea

Reemplace {task_id} con el valor task_id devuelto por la llamada a la API anterior. El task_id es válido para consultas durante 24 horas. Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Parámetros de respuesta

outputobject

Información de salida de la tarea.

Propiedades

task_id string

El ID de la tarea. Válido para consultas durante 24 horas.

task_status string

El estado de la tarea.

Valores de enumeración

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: La tarea no existe o se desconoce su estado.

Transiciones de estado durante el sondeo:

PENDING → RUNNING → SUCCEEDED o FAILED.
El estado inicial de la consulta suele ser PENDING o RUNNING.
Cuando el estado cambia a SUCCEEDED, la respuesta contiene la URL del video generado.
Si el estado es FAILED, revise el mensaje de error y reintente la tarea.

submit_time string

La hora en que se envió la tarea. La hora está en UTC+8 y el formato es YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time string

La hora en que se ejecutó la tarea. La hora está en UTC+8 y el formato es YYYY-MM-DD HH:mm:ss.SSS.

end_time string

La hora en que se completó la tarea. La hora está en UTC+8 y el formato es YYYY-MM-DD HH:mm:ss.SSS.

video_url string

URL del video generado. Se devuelve solo cuando task_status es SUCCEEDED.

Válido durante 24 horas. El video está en formato MP4 con codificación H.264.

orig_prompt string

El prompt de entrada original, correspondiente al parámetro de solicitud prompt.

code string

Código de error. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.

message string

Mensaje de error detallado. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.

usage object

Estadísticas de uso. Solo cuenta resultados exitosos.

Propiedades

duration float

Duración total del video generado, utilizada para facturación.

SR integer

Nivel de resolución del video generado.

output_video_duration float

Duración del video de salida, en segundos.

input_video_duration float

Duración del video de entrada, en segundos.

video_count integer

Número de videos generados. Siempre 1.

request_id string

Identificador único de solicitud para rastreo y solución de problemas.

Tarea exitosa

Las URL de video son válidas solo durante 24 horas y luego se eliminan automáticamente. Guarde los videos generados de inmediato.

{
    "request_id": "c11018a8-3f83-9591-a636-xxxxxx",
    "output": {
        "task_id": "051c7b40-b2c5-4341-aee4-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-04-26 14:13:14.373",
        "scheduled_time": "2026-04-26 14:13:14.419",
        "end_time": "2026-04-26 14:14:13.679",
        "orig_prompt": "Dress the horse-headed humanoid character in the video in the striped sweater from the image",
        "video_url": "https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxxx.mp4"
    },
    "usage": {
        "duration": 13.24,
        "input_video_duration": 6.62,
        "output_video_duration": 6.62,
        "video_count": 1,
        "SR": 720
    }
}

Tarea fallida

Cuando una tarea falla, task_status es FAILED con un código de error y un mensaje. Consulte Códigos de error.

{
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The resolution is not valid xxxxxx"
    }
}

Consulta de tarea caducada

El task_id es válido durante 24 horas. Después de este período, las consultas devuelven el siguiente error.

{
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}

Códigos de error

Si la llamada al modelo falla y devuelve un mensaje de error, consulte Códigos de error para su resolución.