Referencia de API de generación de Vidu-Image

Descripción general del modelo

Modelo	Capacidades	Modalidad de entrada	Especificaciones de la imagen de salida
vidu/vidu-image_reference2image	Generación de imágenes de referencia, texto a imagen, edición de imágenes. Renderizado preciso de texto en chino e inglés, restauración a nivel de píxel de detalles de UI/gráficos y diseño. Ideal para pósteres, infografías, etc.	Texto, Imagen	Resolución: 1K, 2K, 4K Número de imágenes: 1 Formato de imagen: PNG

Modelo

Capacidades

Modalidad de entrada

Especificaciones de la imagen de salida

vidu/vidu-image_reference2image

Generación de imágenes de referencia, texto a imagen, edición de imágenes. Renderizado preciso de texto en chino e inglés, restauración a nivel de píxel de detalles de UI/gráficos y diseño. Ideal para pósteres, infografías, etc.

Texto, Imagen

Resolución: 1K, 2K, 4K

Número de imágenes: 1

Formato de imagen: PNG

Requisitos previos

Activar el servicio: Vaya a la consola de Model Studio, busque "Vidu", encuentre la tarjeta del modelo correspondiente y haga clic en Activate Now para confirmar la activación y autorización en la ventana emergente.
Configurar API Key: Seleccione una región y Obtener una clave API.

Llamada HTTP

Las tareas de generación de imágenes requieren cierto tiempo y la API utiliza llamadas asíncronas. El proceso implica "Crear tarea -> Sondear resultados" dos pasos principales, como se detalla a continuación:

Paso 1: Enviar tarea de generación de imagen

Región de Singapur: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation

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.

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

Cuerpo de la solicitud

model string (Obligatorio)Nombre del modelo. Valores disponibles:

vidu/vidu-image_reference2image

input object (Obligatorio)Objeto de parámetros de entrada que contiene los siguientes campos:

Propiedades

messages array (Obligatorio)Lista de mensajes. El servidor extrae el primer text no vacío como indicación y extrae todos los campos image como imágenes de referencia. La matriz contiene exactamente un objeto con las propiedades role y content.

Propiedades

rolestring (Opcional)Rol del mensaje. Valor recomendado: user.contentarray (Obligatorio)Contenido del mensaje, que incluye indicaciones de texto (text) e imágenes de referencia opcionales (image, se admiten varias).

Propiedades

textstring(Condicionalmente requerido)Prompt positivo que describe el contenido, estilo y composición deseados de la imagen.Admite chino e inglés. La longitud máxima es de 5,000 caracteres, donde cada carácter (chino, letra, dígito o símbolo) cuenta como uno.Ejemplo: Un gato naranja sentado con una expresión feliz, animado y tierno, realista y preciso.Nota: Se requiere al menos un texto no vacío en los mensajes.image string (Opcional)URL de una imagen de referencia. Se admiten múltiples imágenes. Todos los modelos admiten hasta 14 imágenes de referencia.

Admite protocolos HTTP o HTTPS.
Ejemplo: https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png.

Restricciones de imagen:

Formatos: PNG, JPG, WEBP.
Relación de aspecto: Entre 1:4 y 4:1.
Tamaño de archivo: El tamaño total de todas las imágenes no debe exceder 50 MB.
Cantidad: Hasta 14 imágenes de referencia.

parameters object (Opcional)Parámetros de generación de imagen.

Propiedades

size string (Opcional)Tamaño de la imagen en formato width*height (por ejemplo, 2048*2048). El valor predeterminado es 1024*1024 si no se especifica.Consulte la sección Tamaños de imagen admitidos a continuación para ver la lista de tamaños compatibles por modelo.n integer (Opcional)Número de imágenes a generar. Actualmente solo se admite 1. Otros valores devolverán un error de parámetro.seed integer (Opcional)Semilla de número aleatorio. Rango válido: [0,2147483647]. 0 significa aleatorio.Usar la misma seed produce resultados similares. Si se omite, el algoritmo utiliza una semilla aleatoria.watermark bool (Opcional)Si se debe añadir una marca de agua.

false: Predeterminado. Sin marca de agua.
true: Añadir marca de agua.

Texto a imagen
Imagen de referencia a imagen

Compatible con todos los modelos Vidu.

# Singapore region. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "vidu/vidu-image_reference2image",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "A flower shop with exquisite windows, a beautiful wooden door, displaying flowers"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1,
        "watermark": false
    }
}'

Compatible con todos los modelos Vidu. Se pueden proporcionar hasta 14 imágenes de referencia.

# Singapore region. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "vidu/vidu-image_reference2image",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "Following the style of the reference image, generate a sitting orange cat"
                    },
                    {
                        "image": "https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "size": "2048*2048",
        "n": 1,
        "watermark": false
    }
}'

Parámetros de respuesta

request_id stringIdentificador único de solicitud para rastreo y solución de problemas.code stringCódigo de error. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.message stringMensaje de error detallado. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.

Respuesta exitosa
Respuesta de error

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

Paso 2: Consultar resultados de la tarea

Región de Singapur: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

Recomendación de sondeo: La generación de imágenes lleva tiempo. Se recomienda utilizar un mecanismo de sondeo con un intervalo de consulta razonable (por ejemplo, 5 segundos) para obtener resultados.
Flujo de estado de la tarea: PENDING (en espera) → RUNNING (procesando) → SUCCEEDED (éxito) / FAILED (fallo).
Validez del enlace de imagen: Los enlaces de descarga para las imágenes generadas son válidos durante 24 horas. Descargue y guarde las imágenes a la brevedad.

Parámetros de solicitud

Encabezados

Authorization string (Requerido)Autentica la solicitud con una clave API de Model Studio. Ejemplo: Bearer sk-xxxx.task_id string (Obligatorio)El ID de la tarea.

Consultar resultados de la tarea

# Singapore region. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.
curl --location --request GET 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Parámetros de respuesta

output objectInformación de salida de la tarea.

Propiedades

task_id stringID de tarea.choices arrayLista de candidatos de salida de imagen, devuelta solo cuando task_status=SUCCEEDED.

Propiedades

finish_reason stringMotivo de finalización. Normalmente stop en caso de éxito.message objectMensaje devuelto por el modelo.

Propiedades

rolestringRol del mensaje, fijado como assistant.contentarray

Propiedades

type stringTipo de contenido de salida, fijado como image.imagen stringEnlace de descarga para la imagen generada en formato PNG. El enlace es válido durante 24 horas. Descargue y guarde la imagen a la brevedad.

finished boolIndica si la tarea ha finalizado, devuelto solo cuando task_status=SUCCEEDED.

usage objectInformación de uso de recursos. Solo cuenta los resultados exitosos.

Propiedades

image_count integerNúmero de imágenes generadas.size stringResolución de la imagen generada en formato width*height. Ejemplo: 2048*2048.SR stringNivel de resolución de la imagen generada. Ejemplo: 2K.

Tarea exitosa
Tarea fallida

{
    "request_id": "f584a817-6e00-9841-961a-49f7382a03d4",
    "output": {
        "task_id": "6404d4ec-4cdf-45b5-8d7d-3d429c6baed5",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-07-13 20:27:41.291",
        "scheduled_time": "2026-07-13 20:27:41.320",
        "end_time": "2026-07-13 20:28:39.767",
        "finished": true,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://example.com/generated-image.png",
                            "type": "image"
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "SR": "2K",
        "size": "2048*2048",
        "image_count": 1
    }
}

Si la tarea falla por cualquier motivo, se devolverá información relacionada. Puede identificar la causa del error mediante los campos code y message. Consulte Códigos de error para solucionar problemas.

{
    "request_id": "1f015514-b04c-9190-b4dd-8ba11bb15708",
    "output": {
        "task_id": "ccae6c03-fe9f-48fd-b3d6-a524c4707f17",
        "task_status": "FAILED",
        "submit_time": "2026-07-13 20:27:50.654",
        "scheduled_time": "2026-07-13 20:27:50.689",
        "end_time": "2026-07-13 20:27:51.090",
        "code": "InvalidParameter",
        "message": "Missing required field 'parameters.n' in request body"
    }
}

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.

Tamaños de imagen compatibles

vidu-image

Resolución	Tamaños compatibles
1K	10241024, 7201440, 1440720, 1024768, 7681024, 19201088, 10881920, 15361024, 10241536, 1920816, 816*1920
2K	20482048, 10882160, 21601088, 27362048, 20482736, 25601440, 14402560, 30722048, 20483072, 25601104, 1104*2560
4K	28802880, 14402880, 28801440, 33122480, 24803312, 38402160, 21603840, 35202352, 23523520, 38401648, 1648*3840

​Descripción general del modelo

​Requisitos previos

​Llamada HTTP

​Paso 1: Enviar tarea de generación de imagen

Parámetros de solicitud

Encabezados

Cuerpo de la solicitud

Parámetros de respuesta

​Paso 2: Consultar resultados de la tarea

Parámetros de solicitud

Encabezados

Parámetros de respuesta

​Códigos de error

​Tamaños de imagen compatibles

​vidu-image

Descripción general del modelo

Requisitos previos

Llamada HTTP

Paso 1: Enviar tarea de generación de imagen

Paso 2: Consultar resultados de la tarea

Códigos de error

Tamaños de imagen compatibles

vidu-image