Alibaba Cloud Model Studio:LivePortrait video generation API reference

Gere vídeos dinâmicos de retrato a partir de imagens processadas pelo LivePortrait-detect e arquivos de áudio com voz humana. Este documento descreve a API de geração de vídeo.

Visão geral do modelo

Modelo	Descrição
liveportrait	Gera vídeos leves e dinâmicos de retrato a partir de imagens e áudio de voz humana.

HTTP

Pré-requisitos

• Ative o Model Studio e crie uma chave de API: Obtain an API key.
• A imagem de entrada passou pela LivePortrait image detection.

Limites de entrada

• Formatos de imagem aceitos: JPEG, JPG, PNG, BMP ou WebP.
• Resolução da imagem: até 10 MB, proporção máxima de 2 e lado maior limitado a 4096 pixels.
• Formatos de áudio aceitos: WAV ou MP3.
• Restrições de áudio: tamanho máximo de 15 MB e duração entre 1 segundo e 3 minutos.
• Conteúdo do áudio: voz humana nítida obrigatória. Não deve haver ruído ambiental, música de fundo ou outras interferências.
• Faça upload das imagens e dos arquivos de áudio usando URLs HTTP ou HTTPS. Caminhos de arquivo locais não são suportados.

Envie uma tarefa

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

Parâmetros da requisição

Campo	Tipo	Localização	Obrigatório	Descrição	Exemplo
Content-Type	String	Header	Sim	Formato do corpo da requisição. Defina como application/json.	application/json
Authorization	String	Header	Sim	Chave de API com o prefixo Bearer.	Bearer d1**2a
X-DashScope-Async	String	Header	Sim	Defina como enable para envio assíncrono.	enable
model	String	Body	Sim	Nome do modelo. Defina como liveportrait.	liveportrait
input.image_url	String	Body	Sim	URL da imagem enviada (deve ser processada primeiro pela LivePortrait image detection API). Tamanho máximo de 10 MB, proporção de até 2 e lado maior limitado a 4096 pixels. Formatos suportados: JPEG, JPG, PNG, BMP e WebP. O upload de arquivos suporta apenas links HTTP ou HTTPS. Caminhos de arquivo locais não são aceitos.	"image_url": "http://a/a.jpg"
input.audio_url	String	Body	Sim	URL do arquivo de áudio enviado. Limite de 15 MB e duração entre 1 segundo e 3 minutos. Formatos suportados: WAV e MP3. O upload de arquivos suporta apenas links HTTP ou HTTPS. Caminhos de arquivo locais não são aceitos.	http://aaa/bbb.wav
parameters.template_id	String	Body	Não	Controla a postura e a amplitude do movimento da cabeça. Opções: normal (padrão), calm, active.	"normal"
parameters.eye_move_freq	Float	Body	Não	Piscadas por segundo (0-1). Valores maiores indicam piscadas mais frequentes. Padrão: 0,5.	0,5
parameters.video_fps	Integer	Body	Não	Taxa de quadros do vídeo de saída (15-30). Valor padrão: 24.	24
parameters.mouth_move_strength	Float	Body	Não	Intensidade do movimento da boca (0-1,5). Valores maiores resultam em movimentos labiais mais amplos. Defina como 0 para desativar. Padrão: 1.	1
parameters.paste_back	Boolean	Body	Não	Sobrepõe o rosto gerado na imagem original. Se falso, retorna apenas o rosto (corpo ignorado). Padrão: true.	true
parameters.head_move_strength	Float	Body	Não	Amplitude do movimento da cabeça (0-1). Valores maiores aumentam a faixa de movimento. Padrão: 0,7.	0,7

Parâmetros da resposta

Campo	Tipo	Descrição	Exemplo
output.task_id	String	ID da tarefa enviada. Use a API de consulta para obter os resultados.	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	Status da tarefa após o envio.	"PENDING"
request_id	String	ID único da requisição.	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Modelos de ação

template_id	Descrição do efeito
normal	Modelo padrão com amplitude moderada de movimento da cabeça. Adequado para diversos cenários.
calm	O personagem aparenta calma com movimento mínimo da cabeça. Recomendado para cenários de transmissão.
active	O personagem parece animado com grande amplitude de movimento da cabeça. Ideal para cenários de canto.

Exemplo de requisição

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "liveportrait",
    "input": {
        "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250911/ynhjrg/p874909.png",
        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251226/fwnqyq/liveportrait_boy.mp3"
    },
      "parameters": {
         "template_id": "normal",
         "eye_move_freq": 0.5,
         "video_fps":30,
         "mouth_move_strength":1,
         "paste_back": true,
         "head_move_strength":0.7
    }
  }'

Exemplo de resposta

{
    "output": {
	"task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1",
        "task_status": "PENDING"
    },
    "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}

Consultar status da tarefa e obter resultados

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

Parâmetros da requisição

Campo	Tipo	Localização	Obrigatório	Descrição	Exemplo
Authorization	String	Header	Sim	Chave de API com o prefixo Bearer.	Bearer d1**2a
task_id	String	Url Path	Sim	ID da tarefa a ser consultada.	a8532587-fa8c-4ef8-82be-0c46b17950d1

Parâmetros da resposta

Campo	Tipo	Descrição	Exemplo
output.task_id	String	ID da tarefa consultada.	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	Status atual da tarefa consultada.	Status possíveis: PENDING RUNNING SUCCEEDED FAILED UNKNOWN: A tarefa não existe ou o status é desconhecido.
output.results.video_url	String	Se a tarefa for bem-sucedida, este campo contém a URL do vídeo gerado. Válido por 24 horas após a conclusão da tarefa.	https://xxx/1.mp4
usage.video_duration	Float	Duração do vídeo gerado (segundos).	10,23
usage.video_ratio	String	Tipo de quadro do vídeo gerado. Valor: standard.	"video_ratio": "standard"
request_id	String	ID único da requisição.	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Exemplo de requisição

Substitua 86ecf553-d340-4e21-xxxxxxxxx pelo ID da sua tarefa.

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Exemplo de resposta (sucesso)

{
    "request_id": "b64e9c68-3923-462d-b25a-xxxxxx",
    "output": {
        "task_id": "a1c69ca5-810b-49ae-8b20-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-12-26 11:33:03.146",
        "scheduled_time": "2025-12-26 11:33:13.312",
        "end_time": "2025-12-26 11:33:22.455",
        "results": {
            "video_url": "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=xxx"
        }
    },
    "usage": {
        "video_duration": 2.79,
        "video_ratio": "standard"
    }
}

Exemplo de resposta (falha)

{
    "request_id": "7574ee8f-38a3-4b1e-9280-xxxxxx",
    "output": {
        "task_id": "a8532587-fa8c-4ef8-82be-xxxxxx",
        "task_status": "FAILED",
        "code": "xxx",
        "message": "xxxxxx"
    }
}

Códigos de erro

Para informações sobre códigos de status comuns, consulte Error codes.