Referencia de API de generación de imágenes de Vidu - Alibaba Cloud Model Studio

Los modelos de generación de imágenes de Vidu admiten tareas de texto a imagen, edición de imágenes e imagen de referencia a imagen.

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.

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)

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

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

Imagen de referencia a imagen

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 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 de la tarea

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

Nota

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 object

Información de salida de la tarea.

Propiedades

task_id string

ID de tarea.

choices array

Lista de candidatos de salida de imagen, devuelta solo cuando task_status=SUCCEEDED.

Propiedades

finish_reason string

Motivo de finalización. Normalmente stop en caso de éxito.

message object

Mensaje devuelto por el modelo.

Propiedades

rolestring

Rol del mensaje, fijado como assistant.

contentarray

Propiedades

type string

Tipo de contenido de salida, fijado como image.

imagen string

Enlace 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 bool

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

usage object

Información de uso de recursos. Solo cuenta los resultados exitosos.

Propiedades

image_count integer

Número de imágenes generadas.

size string

Resolución de la imagen generada en formato width*height. Ejemplo: 2048*2048.

SR string

Nivel de resolución de la imagen generada. Ejemplo: 2K.

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.

Tarea exitosa

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

Tarea fallida

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