Saltar para o conteúdo principal
Este artigo apresentará um tipo de instrução de integração da API SeeDance Videos Generation, que permite gerar vídeos oficiais do SeeDance inserindo parâmetros personalizados.

Processo de solicitação

Para usar a API SeeDance Videos Generation, primeiro obtenha seu API Token no console do Ace Data Cloud e guarde-o para uso posterior. Se você ainda não tiver feito login ou se registrado, será automaticamente redirecionado para a página de login para convidá-lo a se registrar e fazer login; após a conclusão, você retornará automaticamente à página atual. Um API Token pode chamar todos os serviços da plataforma, sem a necessidade de solicitar separadamente para cada serviço. A primeira solicitação oferece créditos gratuitos para experiência gratuita; quando os créditos forem insuficientes, você poderá recarregar o saldo universal no console.
📘 Documentação completa: SeeDance Videos Generation API →

Uso básico

Primeiro, vamos entender o método básico de uso: basta inserir o texto de prompt content.text, o tipo content.type=text e o modelo model para obter o resultado processado. O conteúdo específico é o seguinte:

É possível ver que aqui configuramos os Request Headers, incluindo:
  • accept: qual formato de resposta você deseja receber; aqui é preenchido como application/json, ou seja, formato JSON.
  • authorization: a chave para chamar a API, que pode ser selecionada diretamente no menu suspenso após a solicitação.
Além disso, configuramos o Request Body, incluindo:
  • model: o modelo para gerar vídeos.
    • 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 (compatível com referência multimodal de personagem 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, compatível com até 30 segundos, referência de áudio puro, mais materiais, edição e extensão de vídeo.
  • content: array de conteúdo de entrada; type pode ser text (prompt), image_url (imagem de referência), audio_url (áudio de referência), video_url (vídeo de referência). As imagens podem especificar sua finalidade por meio de role: first_frame (primeiro quadro) / last_frame (último quadro) / reference_image (referência de personagem / sujeito).
  • resolution: resolução de saída, com opções 480p / 720p / 1080p / 4k. A 2.5 suporta 480p, 720p e 1080p; a 2.0 Fast/Mini suporta 480p e 720p; a 2.0 Standard suporta até 4k.
  • ratio: proporção de aspecto, com 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: 4–30. 1.5/2.x suporta -1 (duração automática).
  • seed: semente aleatória, inteiro, de -1 a 4294967295.
  • camerafixed: se a câmera deve ser fixada, true / false.
  • watermark: se deve adicionar marca d’água, true / false.
  • generate_audio: se deve gerar vídeo com áudio, true / false, compatível com Seedance 1.5 Pro e série 2.x.
  • return_last_frame: se deve retornar a URL da imagem do último quadro do vídeo no resultado.
  • omni_reference_task_type: somente 2.5; auto / reference / edit / extend.
  • output_format: somente 2.5; mp4 / mov, o padrão é mp4.
  • tools: somente 2.5; atualmente é compatível com a ferramenta de busca online web_search, que pode limitar o número de resultados, o número de palavras-chave e as fontes de busca.
  • priority: prioridade de tarefa opcional para 2.5, inteiro de 0–9, o padrão é 0.
  • safety_identifier: identificador estável e anônimo do usuário final de até 64 caracteres; use um hash ou ID anônimo interno, não envie 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 o task_id, e, quando a tarefa for concluída, fará POST do resultado para esse endereço.
  • async: opcional; quando definido como true, a interface retorna imediatamente o task_id, sem necessidade de fornecer callback_url; em seguida, obtenha o resultado por polling através da interface de consulta de tarefas correspondente.
Após a seleção, é possível perceber que o código correspondente também foi gerado à direita, como mostrado na imagem:

Clique no botão “Try” para testar. Conforme mostrado na imagem acima, aqui obtemos o seguinte resultado:
O resultado retornado possui vários campos, apresentados 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 lado do servidor da tarefa de geração de vídeo neste momento.
    • video_url, o link do vídeo da 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 usado para gerar o vídeo.
É possível ver que obtivemos informações satisfatórias do vídeo. Basta obter o vídeo SeeDance gerado através do endereço de link do vídeo em data no resultado. Além disso, se quiser gerar o código de integração correspondente, você pode copiá-lo diretamente. Por exemplo, o código CURL é o seguinte:

Descrição dos parâmetros em linha

No final do prompt content[].text, os parâmetros de geração podem ser passados adicionando --parameter value (método antigo, validação fraca; valores incorretos usarão automaticamente os valores padrão). 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 Request Body. Este é o modo de validação forte; quando os parâmetros forem preenchidos incorretamente, serão retornadas mensagens de erro claras, facilitando a investigação de problemas.

Gerar vídeos com áudio

Seedance 1.5 Pro e a série 2.x oferecem suporte à geração de vídeos com áudio por meio do parâmetro generate_audio:
A série 1.0 não oferece suporte a este parâmetro.

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

doubao-seedance-2-5-260628 oferece suporte a 480p / 720p / 1080p, 4–30 segundos ou duração automática, e aumenta o limite de materiais para 30 imagens de referência, 10 vídeos de referência e 10 áudios de referência (até 50 no total). O 2.5 também oferece suporte ao envio apenas de áudio de referência, sem exigir mais que imagens ou vídeos sejam fornecidos ao mesmo tempo. A geração multimodal comum pode omitir omni_reference_task_type, defini-lo como auto ou defini-lo explicitamente como reference. A edição e extensão de vídeo devem incluir reference_video:
  • reference: envie pelo menos um reference_image, reference_video ou reference_audio; o 2.5 oferece suporte ao envio apenas de áudio de referência.
  • edit: deve usar ratio: adaptive e duration: -1; a duração de saída é cobrada de acordo com o resultado real.
  • extend: deve usar ratio: adaptive; duration pode ser 4–30 ou -1.
  • auto: o modelo seleciona automaticamente geração, edição ou extensão com base no prompt e nos materiais.
  • Quando o tipo de tarefa não corresponder aos materiais ou ao prompt, a tarefa falhará e retornará um erro de parâmetro localizável; ajuste de acordo com as restrições acima e envie novamente.

Primeiro quadro de vídeo gerado a partir de imagem

Se quiser uma tarefa de vídeo gerado a partir de imagem, primeiro o parâmetro content precisa incluir um item cujo type seja image_url, e o campo image_url deve estar no formato de objeto: {"url": "https://..."} ou no formato Base64 {"url": "data:image/png;base64,..."}.
Observação: image_url não oferece suporte ao envio direto no formato de string (como "image_url": "https://cdn.acedata.cloud/e724d7f13d.png"); deve ser usado o formato de objeto "image_url": {"url": "https://..."}, caso contrário, será retornado um erro 400.
O código correspondente:
Clique para executar, e você poderá ver que um resultado será obtido imediatamente, como segue:
Pode-se ver que o efeito gerado é de vídeo criado a partir de imagem, e o resultado é semelhante ao descrito acima.

Primeiro e último quadros de vídeo gerado a partir de imagem

Se quiser o primeiro e o último quadros de vídeo gerado a partir de imagem, primeiro o parâmetro content deve enviar o tipo image_url e definir respectivamente o role como first_frame e last_frame, podendo especificar o seguinte conteúdo:
  • role: especifica o primeiro quadro ou o último quadro.
  • image_url
    • url: link da imagem Ao mesmo tempo, content também precisa inserir o tipo text como prompt.
O código correspondente:
Clique em executar e será possível ver que um resultado será obtido imediatamente, conforme abaixo:
É possível ver que o efeito gerado é um vídeo com personagem, e o resultado é semelhante ao descrito acima.

Referência multimodal de personagem e áudio/vídeo (Seedance 2.0)

A série Seedance 2.0 (doubao-seedance-2-0-260128, doubao-seedance-2-0-fast-260128, doubao-seedance-2-0-mini-260615) oferece suporte a reference_image, reference_audio e reference_video. É possível usar materiais próprios ou autorizados para manter a consistência de personagens, sujeitos, movimentos, movimentos de câmera, sons e ritmo.
Envie apenas materiais de pessoas reais e personagens que sejam próprios ou autorizados. Modelos diferentes oferecem suporte de maneiras diferentes para materiais de pessoas reais; o formato da solicitação permanece inalterado e será retornado um erro claro se o material não atender aos requisitos.
Pontos principais de uso:
  • Apenas os modelos da série Seedance 2.0 oferecem suporte a reference_image; para modelos 1.x, use first_frame / last_frame (primeiro e último quadro de vídeo gerado a partir de imagem).
  • Primeiro quadro de vídeo gerado a partir de imagem, primeiro e último quadros de vídeo gerado a partir de imagem e referência multimodal completa são três cenários mutuamente exclusivos: first_frame / last_frame não podem ser usados junto com reference_image / reference_video / reference_audio.
  • Se quiser especificar o primeiro e o último quadros na referência multimodal completa, marque as imagens como reference_image e escreva no prompt “imagem 1 como primeiro quadro” ou “imagem 2 como último quadro”; se precisar bloquear rigorosamente o primeiro e o último quadros, use apenas first_frame / last_frame.
  • Limite de quantidade de referências multimodais: no máximo 9 imagens em image_url; a versão 2.0 também oferece suporte a audio_url (role como reference_audio, no máximo 3 itens) e video_url (role como reference_video, no máximo 3 itens).
  • Requisitos do material de áudio de referência (audio_url): formato wav / mp3; duração de cada item entre 2 e 15 segundos, no máximo 3 itens e duração total não superior a 15 segundos; cada item não pode exceder 15 MB. Exceder o intervalo de duração causará falha na etapa de processamento do material.
  • Requisitos do material de vídeo de referência (video_url): formato mp4 / mov; duração de cada item entre 2 e 15 segundos, no máximo 3 itens e duração total não superior a 15 segundos.
  • Recomenda-se que as imagens de referência usem fotos de uma única pessoa, de frente, nítidas e sem obstruções; quanto mais nítido o rosto, maior a semelhança.

Exemplo um: close-up que mantém a aparência da pessoa

Envie uma foto de rosto e faça essa pessoa sorrir e acenar para a câmera. O código correspondente:
O resultado retornado é o seguinte; a pessoa no vídeo gerado permanece consistente com a foto de referência:

Exemplo dois: colocar a mesma pessoa em um cenário totalmente novo

O poder de reference_image está em: preservar apenas a identidade da pessoa, enquanto o cenário, a roupa e a ação são totalmente determinados pelo prompt. Abaixo, usando a mesma foto de rosto, faça essa pessoa caminhar em um parque de outono vestindo um casaco bege:
O resultado retornado é o seguinte; a aparência da pessoa é preservada, enquanto o cenário foi alterado para um parque de outono:
💡 Se quiser que a pessoa replique precisamente a composição da foto (em vez de «a mesma pessoa em outro cenário»), pode usar first_frame (primeiro quadro de imagem para vídeo), permitindo que o vídeo comece a se mover a partir desta foto.

Retorno de chamada assíncrono

Como a API de Geração de Vídeos SeeDance leva um tempo maior para gerar (cerca de 1 a 2 minutos), é possível usar o modo assíncrono por meio do campo callback_url, evitando que a conexão HTTP fique ocupada por muito tempo. Fluxo geral: ao iniciar uma solicitação, o cliente especifica callback_url, e a API retorna imediatamente uma resposta contendo task_id; após a conclusão da tarefa, a plataforma envia o resultado gerado para callback_url na forma de POST JSON, e o resultado também contém task_id para facilitar a associação.
Quando a tarefa é concluída, o conteúdo enviado pela plataforma para callback_url é o seguinte:
O campo task_id no resultado é consistente com o retornado durante a solicitação, e a associação da tarefa pode ser realizada por meio desse campo.

Tratamento de erros

Ao chamar a API, se ocorrer um erro, a API retornará o código e a mensagem de erro correspondentes. 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

Por meio deste documento, você já aprendeu como usar a API de Geração de Vídeos Seedance para gerar vídeos a partir de texto, gerar a partir de quadros inicial e final 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; em caso de dúvidas, entre em contato com o suporte técnico.