SeeDance Videos Generation API Integração

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 fazer login. 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 individualmente para cada serviço. A primeira solicitação oferece um crédito gratuito para que você possa experimentar; quando o crédito estiver baixo, 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. O conteúdo específico é o seguinte:

Podemos ver que aqui configuramos os Cabeçalhos da Solicitação, incluindo:

accept: o formato de resposta desejado, que deve ser 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 entrada multimodal como referência de rosto/personagem): doubao-seedance-2-0-260128 (padrão), doubao-seedance-2-0-fast-260128 (rápido), doubao-seedance-2-0-mini-260615 (leve). Veja a seção “Referência de Rosto e Personagem (Seedance 2.0)” abaixo.
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, 2.0), video_url (vídeo de referência, 2.0). A imagem pode ser especificada através de role: first_frame (primeiro quadro) / last_frame (último quadro) / reference_image (referência de rosto/personagem/tema).
resolution: resolução de saída, opções 480p / 720p / 1080p (o modelo padrão 2.0 também suporta 4k; fast / mini de 2.0 suportam no máximo 720p).
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), intervalo de 2–12 para 1.x, 2–15 para 2.0.
seed: semente aleatória, inteiro, de -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 um vídeo com áudio, true / false, apenas doubao-seedance-1-5-pro-251215 suporta.
return_last_frame: se deve retornar a URL da imagem do último quadro do vídeo no resultado.
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 retornará imediatamente task_id, e quando a tarefa for concluída, o resultado será enviado para esse endereço via POST.
async: opcional, se definido como true, a interface retornará imediatamente task_id, sem necessidade de fornecer callback_url, e você poderá consultar o resultado 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:

{
  "success": true,
  "task_id": "9777f36b-4f44-47ff-962d-45cd2f7aeaa8",
  "trace_id": "ce5da2ca-6695-4459-9d2c-2ef9f86db752",
  "data": {
    "task_id": "7e4e1773-510a-4a73-9ab4-98dd1a0b2a7f",
    "status": "succeeded",
    "model": "doubao-seedance-2-0-fast-260128",
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/036f24ed-a9b1-49b3-92c4-30049a3bc152.mp4"
  }
}

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, como o código CURL abaixo:

curl -X POST 'https://api.acedata.cloud/seedance/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "content": [{"type":"text","text":"A white ceramic coffee mug on a glossy marble countertop with soft morning window light. The camera slowly orbits 360 degrees around the mug, steam gently rising."}],
  "model": "doubao-seedance-2-0-fast-260128",
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}'

Descrição dos Parâmetros Inline

No final da palavra-chave content[].text, você pode passar parâmetros de geração na forma de --parameter value (método antigo, verificação fraca, se preenchido incorretamente, o valor padrão será usado). A lista completa de parâmetros é a seguinte:

Parâmetro Inline	Campo Correspondente	Descrição	Faixa de Valores
`--rs`	`resolution`	Resolução de Saída	`480p` / `720p` / `1080p`
`--rt`	`ratio`	Proporção	`16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive`
`--dur`	`duration`	Duração do Vídeo (segundos)	2–12
`--frames`	`frames`	Número de Quadros do Vídeo	Inteiros que satisfaçam 25+4n em [29, 289]
`--fps`	`framespersecond`	Taxa de Quadros	Apenas suporta `24`
`--seed`	`seed`	Semente Aleatória	-1 a 4294967295
`--cf`	`camerafixed`	Se a Câmera é Fixa	`true` / `false`
`--wm`	`watermark`	Se Adicionar Marca D’água	`true` / `false`

Prática Recomendada: Use diretamente os campos de nível superior correspondentes (como resolution, ratio, etc.) no Request Body, para um modo de validação rigorosa, erros na entrada de parâmetros retornarão mensagens de erro claras, facilitando a identificação de problemas.

Gerar Vídeo com Áudio

doubao-seedance-1-5-pro-251215 suporta a geração de vídeos com áudio através do parâmetro generate_audio:

{
  "model": "doubao-seedance-1-5-pro-251215",
  "content": [
    {
      "type": "text",
      "text": "Uma garota segura uma raposa, o vento sopra seu cabelo, você pode ouvir o som do vento"
    }
  ],
  "generate_audio": true,
  "ratio": "16:9",
  "duration": 5
}

Outros modelos não suportam este parâmetro, e ele será ignorado se passado.

Gerar 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 igual a 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 em formato de string (como "image_url": "https://..."), deve ser usado no formato de objeto "image_url": {"url": "https://..."}, caso contrário, retornará erro 400.

Código correspondente:

import requests

url = "https://api.acedata.cloud/seedance/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "content": [
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png"
            }
        },
        {
            "type": "text",
            "text": "Uma garota segura uma raposa em seus braços. Ela abre os olhos e olha ternamente para a câmera, enquanto a raposa a segura afetuosamente. À medida que a câmera se afasta lentamente, seu cabelo é suavemente soprada pelo vento. --ratio adaptive  --dur 5"
        }
    ],
    "model": "doubao-seedance-1-0-pro-250528"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Ao clicar em executar, você verá que receberá imediatamente um resultado, como abaixo:

{
    "success": true,
    "task_id": "dc7cceb5-3c12-4de7-a5f4-abcbba3e8e39",
    "trace_id": "b3b09de3-b7fa-4bb0-88b5-aad4b4a96fd4",
    "data": {
        "task_id": "cgt-20251222072003-x2259",
        "status": "succeeded",
        "video_url": "https://platform.cdn.acedata.cloud/seedance/6afb78b8-5ba8-424f-adcd-69423a700b50.mp4",
        "model": "doubao-seedance-1-0-pro-250528"
    }
}

Você pode ver que o efeito gerado é um vídeo a partir da imagem, e o resultado é semelhante ao mencionado acima.

Gerar 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 um item do tipo image_url, e deve definir role como first_frame e last_frame, permitindo especificar o seguinte conteúdo:

role: especifica o primeiro ou o último quadro.
image_url
- url link da imagem Além disso, content também precisa incluir um tipo text como prompt.

Código correspondente:

import requests

url = "https://api.acedata.cloud/seedance/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
   "model": "doubao-seedance-1-0-pro-250528",
    "content": [
         {
            "type": "text",
            "text": "Tomada de 360 graus"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_first_frame.jpeg"
            },
            "role": "first_frame"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_last_frame.jpeg"
            },
            "role": "last_frame"
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Ao clicar em executar, você verá que receberá imediatamente um resultado, como abaixo:

{
    "success": true,
    "task_id": "f7096c6c-9430-4392-8201-d259632d7afd",
    "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a",
    "data": {
        "task_id": "cgt-20251222073134-54qcw",
        "status": "succeeded",
        "video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
        "model": "doubao-seedance-1-0-pro-250528"
    }
}

Você pode ver que o efeito gerado é um vídeo gerado a partir de personagens, e o resultado é semelhante ao mencionado acima.

Referência de Rosto e Personagem (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 a entrada de materiais de referência de “pessoas reais / personagens”: adicione um item no content com type igual a image_url e role igual a reference_image, usando fotos de pessoas como referência, o modelo manterá as características faciais dessa pessoa no vídeo gerado, permitindo “colocar” a mesma pessoa em novas cenas, ações ou ângulos.

📌 Fotos de pessoas reais serão automaticamente registradas pela plataforma como materiais de base antes de serem usadas na geração, todo o processo é completamente transparente para o chamador: o formato de solicitação e resposta permanece inalterado, sem necessidade de parâmetros adicionais, apenas a primeira geração levará alguns segundos a mais para o processamento do material.

Pontos de uso:

Apenas os modelos da série Seedance 2.0 suportam reference_image; para modelos 1.x, utilize first_frame / last_frame (primeiro e último quadro do vídeo gerado).
reference_image não pode ser usado em conjunto com first_frame / last_frame, apenas um dos dois pode ser escolhido.
Limite máximo de referências multimodais: image_url no máximo 9 imagens; a versão 2.0 também suporta audio_url (com role como reference_audio, no máximo 3) e video_url (com role como reference_video, no máximo 3).
Recomenda-se que as imagens de referência sejam 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 para que a pessoa sorria e acene para a câmera. O código correspondente:

import requests

url = "https://api.acedata.cloud/seedance/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "doubao-seedance-2-0-fast-260128",
    "content": [
        {
            "type": "text",
            "text": "A mulher olha para a câmera, dá um sorriso natural e caloroso e acena com a mão, iluminação suave de estúdio, leve aproximação da câmera."
        },
        {
            "type": "image_url",
            "role": "reference_image",
            "image_url": {
                "url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg"
            }
        }
    ],
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 5
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

O resultado retornado é o seguinte, o vídeo gerado mantém a aparência da pessoa da foto de referência:

{
  "success": true,
  "task_id": "895eb5ea-bbe1-41a3-a9e9-48608e03f93a",
  "trace_id": "83544791-7a84-44de-b8d2-afe171a1c0e4",
  "data": {
    "task_id": "458abf29-cc39-4fd0-bcea-24f89a70d8de",
    "status": "succeeded",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/e71d3cc5-27e7-4719-be34-1f0e254eccaf.mp4",
    "model": "doubao-seedance-2-0-fast-260128",
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 5
  }
}

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

A grande vantagem do reference_image é: manter apenas a identidade da pessoa, enquanto o cenário, a roupa e a ação são totalmente determinados pelas palavras-chave. Abaixo, usando a mesma foto do rosto, a pessoa aparece vestindo um casaco bege caminhando em um parque de outono:

{
  "model": "doubao-seedance-2-0-fast-260128",
  "content": [
    {
      "type": "text",
      "text": "A mesma mulher vestindo um casaco bege caminha por um parque ensolarado de outono, folhas douradas caindo ao seu redor, ela sorri suavemente para a câmera, tomada de rastreamento cinematográfico."
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg"
      }
    }
  ],
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 5
}

O resultado retornado é o seguinte, a aparência da pessoa é mantida, enquanto o cenário foi alterado para um parque de outono:

{
  "success": true,
  "task_id": "00872de7-16b7-431f-b4f7-6bf38ae86157",
  "trace_id": "577a07c3-4f5f-4cc7-86fe-535bb8332614",
  "data": {
    "task_id": "32fe1537-ba3e-452a-8749-3ef8890d37fd",
    "status": "succeeded",
    "video_url": "https://platform2.cdn.acedata.cloud/seedance/44f47593-556b-4fda-afa5-7a71eefcd228.mp4",
    "model": "doubao-seedance-2-0-fast-260128",
    "resolution": "720p",
    "ratio": "9:16",
    "duration": 5
  }
}

💡 Se você deseja que a pessoa replique exatamente a composição da foto (e não “a mesma pessoa em um cenário diferente”), pode usar first_frame (primeiro quadro do vídeo gerado), fazendo o vídeo começar a partir dessa foto.

Callback Assíncrono

Como a geração de vídeos pela API SeeDance pode demorar (cerca de 1-2 minutos), você pode usar o campo callback_url para ativar o modo assíncrono, evitando que a conexão HTTP fique ocupada por muito tempo. Fluxo geral: ao iniciar a solicitação, o cliente 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 em formato JSON POST, e o resultado também conterá task_id para associação.

{
  "task_id": "f7096c6c-9430-4392-8201-d259632d7afd"
}

Quando a tarefa é concluída, o conteúdo enviado pela plataforma para callback_url é o seguinte:

{
  "success": true,
  "task_id": "f7096c6c-9430-4392-8201-d259632d7afd",
  "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a",
  "data": {
    "task_id": "cgt-20251222073134-54qcw",
    "status": "succeeded",
    "video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
    "model": "doubao-seedance-1-0-pro-250528"
  }
}

O campo task_id no resultado é o mesmo que o retornado na solicitação, permitindo a associação da tarefa.

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

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusão

Através deste documento, você já entendeu como usar a API SeeDance Videos Generation para gerar vídeos através de palavras-chave, imagens de referência, e a referência de rosto/personagem do Seedance 2.0. Esperamos que este documento ajude você a integrar e usar melhor essa API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico.

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Proxy

Avançado

SeeDance Videos Generation API Integração

Processo de Solicitação

Uso Básico

Descrição dos Parâmetros Inline

Gerar Vídeo com Áudio

Gerar Vídeo a Partir da Primeira Imagem

Gerar Vídeo a Partir da Primeira e Última Imagem

Referência de Rosto e Personagem (Seedance 2.0)

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

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

Callback Assíncrono

Tratamento de Erros

Exemplo de Resposta de Erro

Conclusão

​Processo de Solicitação

​Uso Básico

​Descrição dos Parâmetros Inline

​Gerar Vídeo com Áudio

​Gerar Vídeo a Partir da Primeira Imagem

​Gerar Vídeo a Partir da Primeira e Última Imagem

​Referência de Rosto e Personagem (Seedance 2.0)

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

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

​Callback Assíncrono

​Tratamento de Erros

​Exemplo de Resposta de Erro

​Conclusão

Processo de Solicitação

Uso Básico

Descrição dos Parâmetros Inline

Gerar Vídeo com Áudio

Gerar Vídeo a Partir da Primeira Imagem

Gerar Vídeo a Partir da Primeira e Última Imagem

Referência de Rosto e Personagem (Seedance 2.0)

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

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

Callback Assíncrono

Tratamento de Erros

Exemplo de Resposta de Erro

Conclusão