Skip to main content

Referência da API de Geração Vidu-Image

Os modelos de Geração de Imagens Vidu suportam tarefas de texto para imagem, edição de imagem e imagem de referência para imagem.

Visão Geral do Modelo

Modelo

Capacidades

Modalidade de Entrada

Especificações da Imagem de Saída

vidu/vidu-image_reference2image

Geração de imagem de referência, texto para imagem, edição de imagem. Renderização precisa de texto em chinês e inglês, restauração no nível de pixel de UI/gráficos e detalhes de design. Ideal para pôsteres, infográficos, etc.

Texto, Imagem

Resolução: 1K, 2K, 4K

Número de imagens: 1

Formato da imagem: PNG

Pré-requisitos

  1. Ativar o serviço: Acesse o console do Model Studio, pesquise por "Vidu", encontre o cartão do modelo correspondente e clique em Activate Now para confirmar a ativação e autorização na janela pop-up.
  2. Configurar API Key: Selecione uma região e Obtenha uma chave de API.

Chamada HTTP

As tarefas de geração de imagens levam um certo tempo e a API usa chamadas assíncronas. O processo envolve "Criar Tarefa -> Consultar Resultados" duas etapas principais, da seguinte forma:

Etapa 1: Enviar Tarefa de Geração de Imagem

Região de Singapura: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation

Parâmetros da Requisição

Cabeçalhos
Content-Type string (Obrigatório)O tipo de conteúdo da requisição. Deve ser application/json.Authorization string (Obrigatório)Autentica a requisição com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.X-DashScope-Async string (Obrigatório)Habilita o processamento assíncrono. Requisições HTTP suportam apenas chamadas assíncronas. Deve ser enable.
Se este cabeçalho de solicitação estiver ausente, o erro "a API do usuário atual não suporta chamadas síncronas" será retornado.
Corpo da Requisição
model string (Obrigatório)Nome do modelo. Valores disponíveis:
  • vidu/vidu-image_reference2image
input object (Obrigatório)Objeto de parâmetro de entrada contendo os seguintes campos:

Propriedades

messages array (Obrigatório)Lista de mensagens. O servidor extrai o primeiro text não vazio como o prompt e extrai todos os campos image como imagens de referência. O array contém exatamente um objeto com as propriedades role e content.

Propriedades

rolestring (Opcional)Função da mensagem. Valor recomendado: user.contentarray (Obrigatório)Conteúdo da mensagem, contendo prompts de texto (text) e imagens de referência opcionais (image, múltiplas suportadas).

Propriedades

textstring(Condicionalmente Obrigatório)Prompt positivo descrevendo o conteúdo, estilo e composição desejados da imagem.Suporta chinês e inglês. O comprimento máximo é de 5,000 caracteres, onde cada caractere (chinês, letra, dígito ou símbolo) conta como um.Exemplo: Um gato laranja sentado com uma expressão feliz, animado e fofo, realista e preciso.Nota: Pelo menos um texto não vazio é obrigatório nas mensagens.image string (Opcional)URL de uma imagem de referência. Várias imagens são suportadas. Todos os modelos suportam até 14 imagens de referência.Restrições de imagem:
  • Formatos: PNG, JPG, WEBP.
  • Proporção: Entre 1:4 e 4:1.
  • Tamanho do arquivo: O tamanho total de todas as imagens não deve exceder 50 MB.
  • Quantidade: Até 14 imagens de referência.
parameters object (Opcional)Parâmetros de geração de imagem.

Propriedades

size string (Opcional)Tamanho da imagem no formato width*height (por exemplo, 2048*2048). O padrão é 1024*1024 se não for especificado.Consulte a seção Tamanhos de imagem suportados abaixo para a lista de tamanhos suportados por modelo.n integer (Opcional)Número de imagens a serem geradas. Atualmente, apenas 1 é suportado. Outros valores retornarão um erro de parâmetro.seed integer (Opcional)Semente de número aleatório. Intervalo válido: [0,2147483647]. 0 significa aleatório.Usar a mesma seed produz saídas semelhantes. Se omitido, o algoritmo usa uma semente aleatória.watermark bool (Opcional)Se deve adicionar uma marca d'água.
  • false: Padrão. Sem marca d'água.
  • true: Adicionar marca d'água.
  • Texto para Imagem
  • Imagem de Referência para Imagem
Suportado por todos os 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
    }
}'

Parâmetros da Resposta

request_id stringIdentificador exclusivo da requisição para rastreamento e solução de problemas.code stringCódigo de erro. Retornado apenas para requisições com falha. Consulte Códigos de erro.message stringMensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Códigos de erro.
  • Resposta bem-sucedida
  • Resposta de erro
Salve o task_id para consultar o status e o resultado da tarefa.
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Etapa 2: Consultar Resultados da Tarefa

Região de Singapura: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
  • Recomendação de polling: A geração de imagens leva tempo. Recomenda-se usar um mecanismo de polling com um intervalo de consulta razoável (por exemplo, 5 segundos) para obter os resultados.
  • Fluxo de status da tarefa: PENDING (aguardando) → RUNNING (processando) → SUCCEEDED (sucesso) / FAILED (falha).
  • Validade do link da imagem: Os links de download para imagens geradas são válidos por 24 horas. Baixe e salve as imagens prontamente.

Parâmetros da Requisição

Cabeçalhos
Authorization string (Obrigatório)Autentica a requisição com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.task_id string (Obrigatório)O ID da tarefa.
  • Consultar Resultados da Tarefa
# 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 da Resposta

output objectInformações de saída da tarefa.

Propriedades

task_id stringID da tarefa.choices arrayLista de candidatos de saída de imagem, retornada apenas quando task_status=SUCCEEDED.

Propriedades

finish_reason stringMotivo da conclusão. Normalmente stop em caso de sucesso.message objectMensagem retornada pelo modelo.

Propriedades

rolestringFunção da mensagem, fixada como assistant.contentarray

Propriedades

type stringTipo do conteúdo de saída, fixado como image.image stringLink de download para a imagem gerada no formato PNG. O link é válido por 24 horas. Baixe e salve a imagem prontamente.
finished boolSe a tarefa está concluída, retornado apenas quando task_status=SUCCEEDED.
usage objectInformações de uso de recursos. Conta apenas resultados bem-sucedidos.

Propriedades

image_count integerNúmero de imagens geradas.size stringResolução da imagem gerada no formato width*height. Exemplo: 2048*2048.SR stringNível de resolução da imagem gerada. Exemplo: 2K.
request_id stringIdentificador exclusivo da requisição para rastreamento e solução de problemas.code stringCódigo de erro. Retornado apenas para requisições com falha. Consulte Códigos de erro.message stringMensagem de erro detalhada. Retornada apenas para solicitações com falha. Consulte Códigos de erro.
  • Tarefa Bem-sucedida
  • Tarefa Falhou
{
    "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
    }
}

Códigos de erro

Se a chamada do modelo falhar e retornar uma mensagem de erro, consulte Códigos de erro para resolução.

Tamanhos de Imagem Suportados

vidu-image

Resolução

Tamanhos Suportados

1K

1024*1024, 720*1440, 1440*720, 1024*768, 768*1024, 1920*1088, 1088*1920, 1536*1024, 1024*1536, 1920*816, 816*1920

2K

2048*2048, 1088*2160, 2160*1088, 2736*2048, 2048*2736, 2560*1440, 1440*2560, 3072*2048, 2048*3072, 2560*1104, 1104*2560

4K

2880*2880, 1440*2880, 2880*1440, 3312*2480, 2480*3312, 3840*2160, 2160*3840, 3520*2352, 2352*3520, 3840*1648, 1648*3840