> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# SeeDance Videos Generation API Integração
> ByteDance Seedance Video Generation API guide - Ace Data Cloud
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](https://platform.acedata.cloud/console/applications) 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](https://platform.acedata.cloud/console/coin).
> 📘 Documentação Completa: [SeeDance Videos Generation API →](https://platform.acedata.cloud/documents/seedance-videos)
## 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:
```json theme={null}
{
"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:
```shell theme={null}
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`:
```json theme={null}
{
"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:
```python theme={null}
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:
```python theme={null}
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:
```python theme={null}
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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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.
```json theme={null}
{
"task_id": "f7096c6c-9430-4392-8201-d259632d7afd"
}
```
Quando a tarefa é concluída, o conteúdo enviado pela plataforma para `callback_url` é o seguinte:
```json theme={null}
{
"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
```json theme={null}
{
"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.