Skip to main content
Este documento apresentará uma descrição da integração da SeeDance Videos Generation API, que pode gerar vídeos oficiais da SeeDance através da entrada de parâmetros personalizados.

​
Processo de Solicitação

Para usar a SeeDance Videos Generation API, primeiro acesse o Painel de Controle da Ace Data Cloud para obter seu Token de API, que deve ser guardado para uso futuro. Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e logar; após a conclusão, você será redirecionado de volta para a página atual. Um Token de API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar um para cada serviço individualmente. A primeira solicitação oferece um crédito gratuito para que você possa experimentar; quando o crédito acabar, você pode recarregar o saldo geral no painel de controle.
📘 Documentação Completa: SeeDance Videos Generation API →

​
Uso Básico

Primeiro, entenda a forma básica de uso, que consiste em inserir a palavra-chave content.text, o tipo content.type=text e o modelo model, para obter o resultado processado, conforme detalhado abaixo:

Podemos ver que aqui configuramos os Cabeçalhos da Solicitação, incluindo:
  • accept: o formato de resposta desejado, aqui preenchido como application/json, ou seja, formato JSON.
  • authorization: a chave para chamar a API, que pode ser selecionada diretamente após a solicitação.
Além disso, configuramos o Corpo da Solicitação, incluindo:
  • model: o modelo para gerar o vídeo.
    • Série Seedance 1.x: doubao-seedance-1-0-pro-250528, doubao-seedance-1-0-pro-fast-251015, doubao-seedance-1-5-pro-251215, doubao-seedance-1-0-lite-t2v-250428, doubao-seedance-1-0-lite-i2v-250428.
    • Série Seedance 2.0 (suporta referências multimodais de personagens e áudio/vídeo): doubao-seedance-2-0-260128 (padrão), doubao-seedance-2-0-fast-260128 (rápido), doubao-seedance-2-0-mini-260615 (leve).
    • Seedance 2.5: doubao-seedance-2-5-260628, suporta até 30 segundos, referências de áudio puro, mais materiais, edição de vídeo e extensão.
  • content: array de conteúdo de entrada, type pode ser text (palavra-chave), image_url (imagem de referência), audio_url (áudio de referência), video_url (vídeo de referência). As imagens podem ser especificadas através de role: first_frame (primeiro quadro) / last_frame (último quadro) / reference_image (referência de personagem / sujeito).
  • resolution: resolução de saída, opções 480p / 720p / 1080p / 4k. 2.5 suporta 480p, 720p, 1080p; 2.0 Fast/Mini suporta 480p, 720p; 2.0 Standard suporta até 4k.
  • ratio: proporção, opções 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive.
  • duration: duração do vídeo (segundos, inteiro). Série 1.0 2–12; 1.5 Pro 4–12; série 2.0 4–15; 2.5 de 4–30. 1.5/2.x suporta -1 (duração automática).
  • seed: semente aleatória, inteiro, -1 a 4294967295.
  • camerafixed: se a câmera deve ser fixa, true / false.
  • watermark: se deve adicionar uma marca d’água, true / false.
  • generate_audio: se deve gerar vídeo com áudio, true / false, suportado por Seedance 1.5 Pro e séries 2.x.
  • return_last_frame: se deve retornar a URL da imagem do último quadro do vídeo no resultado.
  • omni_reference_task_type: apenas 2.5; auto / reference / edit / extend.
  • output_format: apenas 2.5; mp4 / mov, padrão mp4.
  • tools: apenas 2.5; atualmente suporta a ferramenta de busca na web web_search, podendo limitar o número de resultados, palavras-chave e fontes de pesquisa.
  • priority: 2.5 opção de prioridade da tarefa, inteiro 0–9, padrão 0.
  • safety_identifier: identificador de usuário final anônimo estável de até 64 caracteres; use hash ou ID anônimo interno, não insira nome, e-mail ou número de telefone.
  • execution_expires_after: tempo limite da tarefa (segundos), intervalo de 3600–259200.
  • callback_url: endereço de callback assíncrono, após a configuração a API retorna imediatamente task_id, e quando a tarefa for concluída, o resultado será enviado para esse endereço.
  • async: opcional, se definido como true, a interface retorna imediatamente task_id, sem necessidade de fornecer callback_url, e posteriormente, o resultado pode ser obtido através da interface de consulta de tarefas correspondente.
Após a seleção, você pode notar que o código correspondente também foi gerado à direita, como mostrado na imagem:

Clique no botão “Try” para realizar o teste, como mostrado na imagem acima, e assim obtemos o seguinte resultado:
O resultado retornado contém vários campos, descritos a seguir:
  • success, o status da tarefa de geração de vídeo neste momento.
  • task_id, o ID da tarefa de geração de vídeo neste momento.
  • trace_id, o ID de rastreamento da geração de vídeo neste momento.
  • data, a lista de resultados da tarefa de geração de vídeo neste momento.
    • task_id, o ID do servidor da tarefa de geração de vídeo neste momento.
    • video_url, o link do vídeo gerado pela tarefa de geração de vídeo neste momento.
    • status, o status da tarefa de geração de vídeo neste momento.
      • model, o modelo utilizado para gerar o vídeo.
Podemos ver que obtivemos informações satisfatórias sobre o vídeo, e tudo o que precisamos fazer é acessar o link do vídeo gerado em data para obter o vídeo SeeDance. Além disso, se você quiser gerar o código de integração correspondente, pode copiá-lo diretamente, por exemplo, o código CURL é o seguinte:

​
Descrição dos parâmetros inline

No final do prompt content[].text, você pode passar parâmetros de geração na forma --parameter value (antiga forma, verificação fraca, se preenchido incorretamente, o valor padrão será usado automaticamente). A lista completa de parâmetros é a seguinte:
Prática recomendada: Use diretamente os campos de nível superior correspondentes (como resolution, ratio, etc.) no corpo da solicitação para um modo de verificação forte; se os parâmetros forem preenchidos incorretamente, uma mensagem de erro clara será retornada, facilitando a identificação de problemas.

​
Geração de vídeo com áudio

Seedance 1.5 Pro e 2.x suportam a geração de vídeos com áudio através do parâmetro generate_audio:
A série 1.0 não suporta este parâmetro.

​
Geração, edição e extensão multimodal do Seedance 2.5

doubao-seedance-2-5-260628 suporta 480p / 720p / 1080p, 4–30 segundos ou duração automática, e aumenta o limite de material para 30 imagens de referência, 10 vídeos de referência, 10 áudios de referência (no total, no máximo 50). A versão 2.5 também suporta o envio apenas de áudio de referência, não exigindo mais o fornecimento simultâneo de imagens ou vídeos. A geração multimodal normal pode omitir omni_reference_task_type, definindo como auto, ou explicitamente como reference. A edição e extensão de vídeo devem incluir reference_video:
  • reference: deve incluir pelo menos uma reference_image, reference_video ou reference_audio; a versão 2.5 suporta apenas o envio de áudio de referência.
  • edit: deve usar ratio: adaptive e duration: -1; a duração de saída é cobrada com base no resultado real.
  • extend: deve usar ratio: adaptive; duration pode ser de 4–30 ou -1.
  • auto: o modelo escolhe automaticamente entre gerar, editar ou estender com base no prompt e no material.
  • Quando o tipo de tarefa não corresponde ao material ou ao prompt, a tarefa falhará e retornará um erro de parâmetro localizável; ajuste conforme as restrições acima e reenvie.

​
Geração de vídeo a partir da primeira imagem

Se você deseja gerar um vídeo a partir de uma imagem, primeiro o parâmetro content deve incluir um item com type como image_url, e o campo image_url deve estar no formato de objeto: {"url": "https://..."} ou no formato Base64 {"url": "data:image/png;base64,..."}.
Nota: image_url não suporta a passagem direta no formato de string (como "image_url": "https://cdn.acedata.cloud/e724d7f13d.png"), deve usar o formato de objeto "image_url": {"url": "https://..."}, caso contrário, retornará erro 400.
Código correspondente:
Ao clicar em executar, você pode ver que imediatamente obterá um resultado, como abaixo:
Você pode ver que o efeito gerado é a geração de vídeo a partir da imagem, e o resultado é semelhante ao mencionado acima.

​
Geração de vídeo a partir da primeira e última imagem

Se você deseja gerar um vídeo a partir da primeira e última imagem, primeiro o parâmetro content deve incluir o tipo image_url, e deve definir role como first_frame e last_frame, podendo especificar o seguinte conteúdo:
  • role: especifica o primeiro ou o último quadro.
  • image_url
    • url link da imagem Ao mesmo tempo, content também precisa incluir o tipo text como prompt.
Código correspondente:
Clicando em executar, pode-se notar que um resultado é imediatamente obtido, como abaixo:
Pode-se ver que o efeito gerado é um vídeo gerado por personagens, com resultados semelhantes ao texto acima.

​
Referência Multimodal de Personagens e Áudio e Vídeo (Seedance 2.0)

Série Seedance 2.0 (doubao-seedance-2-0-260128, doubao-seedance-2-0-fast-260128, doubao-seedance-2-0-mini-260615) suporta reference_image, reference_audio e reference_video. É possível usar materiais próprios ou licenciados para manter a consistência de personagens, sujeitos, ações, movimentos de câmera, sons e ritmos.
Por favor, faça upload apenas de materiais de pessoas reais e personagens que você possui ou tem autorização. Diferentes modelos suportam materiais de pessoas reais de maneiras diferentes; o formato do pedido permanece o mesmo, se o material não atender aos requisitos, um erro claro será retornado.
Pontos de uso:
  • Apenas modelos da série Seedance 2.0 suportam reference_image; modelos 1.x devem usar first_frame / last_frame (primeiro e último quadro do vídeo gerado).
  • O primeiro quadro do vídeo gerado, o primeiro e último quadro do vídeo gerado e a referência multimodal são três cenários mutuamente exclusivos: first_frame / last_frame não podem ser usados em conjunto com reference_image / reference_video / reference_audio.
  • Se você deseja especificar os quadros inicial e final na referência multimodal, deve marcar a imagem como reference_image e indicar nas instruções “imagem 1 como primeiro quadro” ou “imagem 2 como último quadro”; se precisar bloquear estritamente os quadros inicial e final, use apenas first_frame / last_frame.
  • Limite máximo de referências multimodais: image_url no máximo 9 imagens; 2.0 também suporta audio_url (role como reference_audio, no máximo 3) e video_url (role como reference_video, no máximo 3).
  • Requisitos para materiais de áudio de referência (audio_url): formato wav / mp3; duração única de 2 a 15 segundos, no máximo 3 e duração total não superior a 15 segundos; cada um não deve exceder 15 MB. Exceder o limite de duração resultará em falha na fase de processamento do material.
  • Requisitos para materiais de vídeo de referência (video_url): formato mp4 / mov; duração única de 2 a 15 segundos, no máximo 3 e duração total não superior a 15 segundos.
  • Recomenda-se usar fotos de uma única pessoa, de frente, nítidas e sem obstruções; quanto mais nítido o rosto, maior a similaridade.

​
Exemplo 1: Close-up mantendo a aparência da pessoa

Envie uma foto do rosto de uma pessoa, fazendo com que ela sorria e acene para a câmera. O código correspondente:
O resultado retornado é o seguinte, o vídeo gerado mantém a aparência da pessoa em relação à foto de referência:

​
Exemplo 2: Colocando a mesma pessoa em um novo cenário

A força do reference_image está em: manter apenas a identidade da pessoa, enquanto o cenário, roupas e ações são totalmente determinados pelas instruções. Abaixo, usando a mesma foto do rosto, a pessoa é vista vestindo um casaco bege caminhando em um parque de outono:
O resultado retornado é o seguinte, a aparência da pessoa é mantida, enquanto o cenário foi alterado para um parque de outono:
💡 Se você deseja que a figura reproduza com precisão a composição da foto (em vez de “trocar a cena da mesma pessoa”), pode usar first_frame (primeiro quadro do vídeo), fazendo o vídeo começar a se mover a partir desta foto.

​
Callback Assíncrono

Devido ao tempo de geração do SeeDance Videos Generation API ser longo (cerca de 1-2 minutos), você pode usar o campo callback_url para operar em modo assíncrono, evitando que a conexão HTTP fique ocupada por muito tempo. Fluxo geral: quando o cliente inicia a solicitação, especifica callback_url, a API retorna imediatamente uma resposta contendo task_id; após a conclusão da tarefa, a plataforma enviará os resultados gerados para callback_url no formato POST JSON, e os resultados também conterão task_id para associação.
Quando a tarefa é concluída, o conteúdo enviado pela plataforma para callback_url é o seguinte:
O campo task_id nos resultados é o mesmo que foi retornado na solicitação, e através deste campo é possível realizar a associação da tarefa.

​
Tratamento de Erros

Ao chamar a API, se ocorrer um erro, a API retornará o código de erro e a mensagem correspondente. Por exemplo:
  • 400 token_mismatched: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
  • 400 api_not_implemented: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
  • 401 invalid_token: Não autorizado, token de autorização inválido ou ausente.
  • 429 too_many_requests: Muitas solicitações, você excedeu o limite de taxa.
  • 500 api_error: Erro interno do servidor, algo deu errado no servidor.

​
Exemplo de Resposta de Erro

​
Conclusão

Através deste documento, você já entendeu como usar a Seedance Videos Generation API para gerar vídeos a partir de texto, quadros iniciais e finais, e referências multimodais, bem como usar o Seedance 2.5 para editar ou estender vídeos. Esperamos que este documento possa ajudá-lo a concluir a integração da API; se houver dúvidas, entre em contato com o suporte técnico.