> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# SeeDance Videos Generation API Integração
> ByteDance Seedance Video Generation 集成指南 - XHuoAPI
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 API, você precisa primeiro solicitar o serviço correspondente na página [SeeDance Videos Generation API](https://api.xhuoapi.ai/documents/seedance-videos). Após acessar a página, clique no botão "Acquire", conforme mostrado na imagem:
Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, convidando-o a se registrar e fazer login. Após o registro e login, você será redirecionado de volta para a página atual.
Na primeira solicitação, haverá um crédito gratuito disponível, permitindo o uso gratuito da API.
## Uso Básico
Primeiro, entenda a forma básica de uso, que é 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 Request Headers, incluindo:
* `accept`: o formato de resposta desejado, 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 Request Body, incluindo:
* `model`: o modelo para gerar o vídeo, valores opcionais: `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`.
* `content`: array de conteúdo de entrada, `type` pode ser `text` ou `image_url`.
* `resolution`: resolução de saída, opções `480p` / `720p` / `1080p`.
* `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.
* `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**.
* `service_tier`: modo de inferência, `default` (online) ou `flex` (offline, preço 50% do online).
* `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 retorna imediatamente `task_id`, e quando a tarefa é concluída, o resultado é enviado para esse endereço.
Após a seleção, você pode notar que o código correspondente também foi gerado à direita, conforme 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": "ec22ae22-0140-4033-8c86-a48b536da595",
"trace_id": "1cc87db0-8ee5-4436-969b-35cc571a9fd5",
"data": {
"task_id": "cgt-20251222005129-62fhb",
"status": "succeeded",
"video_url": "https://platform.cdn.xhuoapi.ai/seedance/f592800a-b87c-4705-8796-cbb8018cae35.mp4",
"model": "doubao-seedance-1-0-pro-250528"
}
}
```
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`.
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:
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/seedance/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
"content": [{"text":"Um gatinho bocejando para a câmera. --rs 720p --rt 16:9 --dur 5 --fps 24 --wm true --seed 11 --cf false","type":"text"}],
"model": "doubao-seedance-1-0-pro-250528"
}'
```
## 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` (forma antiga, verificação fraca, se preenchido incorretamente, usará valores padrão automaticamente). A lista completa de parâmetros é a seguinte:
| Parâmetro Inline | Campo Correspondente | Descrição | Intervalo 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 deve ser fixa | `true` / `false` |
| `--wm` | `watermark` | Se deve adicionar uma 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 verificação forte, onde erros de preenchimento 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 será ignorado se passado.
## 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` precisa conter 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 o formato de objeto `"image_url": {"url": "https://..."}`, caso contrário, retornará erro 400.
Código correspondente:
```python theme={null}
import requests
url = "https://api.xhuoapi.ai/v1/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 de volta com carinho. À 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.xhuoapi.ai/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.
## 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`, permitindo especificar o seguinte conteúdo:
* role: especifica a primeira ou última imagem.
* image\_url
* url link da imagem
Além disso, `content` também precisa incluir o tipo `text` como prompt.
Código correspondente:
```python theme={null}
import requests
url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
"model": "doubao-seedance-1-0-pro-250528"
}
}
```
Você pode ver que o efeito gerado é um vídeo a partir das imagens, e o resultado é semelhante ao mencionado acima.
## Callback assíncrono
Como a geração de vídeos pela API SeeDance pode levar mais tempo (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 faz 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 em formato JSON POST para `callback_url`, 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.xhuoapi.ai/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, e você pode usar esse campo para associar a 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": "falha ao buscar"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## Conclusão
Através deste documento, você já entendeu como usar a API de Geração de Vídeos SeeDance, podendo gerar vídeos através de palavras-chave e imagens de referência. 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.