Se você está criando fluxos de trabalho de vídeo no Seedance 2.0 ou 2.0-Fast, a Biblioteca de Ativos (Asset Library) é a forma de inserir mídia de referência — imagens, vídeo e áudio — em suas gerações de maneira limpa. Em vez de passar a mídia bruta em cada chamada, você registra um arquivo uma única vez, o Atlas valida e pré-processa esse arquivo, e você o referencia por meio de um ID estável em quantas gerações desejar.
Este guia o levará do zero a uma referência funcional em três chamadas cURL.
O que é a Biblioteca de Ativos (e o que ela não é)
É um armazenamento de mídia gerenciado, voltado para a geração de vídeo Seedance 2.0 / 2.0-Fast. Você registra um ativo, ele é pré-processado e, assim que estiver como Active (Ativo), você o referencia como asset://<asset_id> em sua solicitação de geração.
Duas coisas importantes para saber de antemão, pois economizarão seu tempo de depuração:
- Vídeo e áudio devem ser registrados aqui primeiro. Eles não podem ser passados via URL diretamente na solicitação de geração. Apenas imagens podem ser enviadas em linha (inline). Portanto, para qualquer fluxo de trabalho de referência de vídeo ou áudio, a Biblioteca de Ativos é o ponto de entrada obrigatório, não uma conveniência opcional.
- O upload é feito apenas por URL pública. Base64 / data URLs não são suportados. O arquivo precisa estar em um endereço acessível publicamente no momento do registro.
Antes de começar
Você precisará de uma chave de API do Atlas Cloud obtida no painel de controle.
Um detalhe que confunde os usuários: a Biblioteca de Ativos e a API de geração residem em hosts diferentes.
td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}
| Função | Host | URL Base |
|---|---|---|
| Biblioteca de Ativos (registrar, consultar, gerenciar) | console | https://console.atlascloud.ai/api/v1 |
| Geração de vídeo | api | https://api.atlascloud.ai/api/v1 |
Ambos utilizam o mesmo cabeçalho de autenticação:
plaintext1export ATLASCLOUD_API_KEY="sua-api-key-aqui"
plaintext1Authorization: Bearer $ATLASCLOUD_API_KEY
O fluxo de três etapas
Registrar → consultar até ficar Active → referenciar em uma geração.
Etapa 1 — Registrar um ativo
Aponte o Atlas para uma URL pública. Defina o tipo como Image, Video ou Audio (o padrão é Image).
plaintext1curl -X POST "https://console.atlascloud.ai/api/v1/sd/assets" \ 2 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \ 3 -H "Content-Type: application/json" \ 4 -d '{ 5 "type": "Video", 6 "url": "https://your-public-host.com/reference-clip.mp4" 7 }'
A resposta retorna o id do ativo e um status de Processing (Processando).
Ele aparecerá como mostrado abaixo:
Guarde o id (destacado acima) — é ele que você consultará e usará como referência.
Nota rápida: O que conta como uma "URL pública"?
Este é o passo onde as pessoas mais erram, por isso é importante ser preciso. O Atlas busca seu arquivo fazendo um HTTP GET simples na URL. Essa URL precisa retornar os bytes brutos do arquivo diretamente — sem login, sem cookies, sem páginas de "clique para visualizar" ou JavaScript necessário para renderizar.
O teste rápido: abra a URL em uma guia anônima do navegador. Se a imagem for exibida ou o vídeo for baixado sem necessidade de login, o Atlas conseguirá buscá-lo. Se você vir uma página de visualização, uma solicitação de login ou uma interface de preview, o Atlas não conseguirá.
Isso significa que um link de compartilhamento do Google Photos ou Google Drive não funcionará. Esses links apontam para uma página web que exibe sua mídia por trás do sistema de autenticação e redirecionamento do Google — e não para o arquivo em si. O Atlas buscaria o wrapper da página, não a mídia.
O que funciona:
- Armazenamento de objetos com leitura pública ou uma URL pré-assinada (presigned URL) — Amazon S3, Google Cloud Storage, Cloudflare R2, Azure Blob. URLs pré-assinadas são ideais: públicas, porém limitadas por tempo.
- Um CDN ou seu próprio servidor web servindo o arquivo diretamente.
- O endpoint de upload do próprio Atlas — se você possui apenas um arquivo local (ou algo exportado do Google Photos), envie-o para o Atlas primeiro para obter uma URL de armazenamento público e, em seguida, registre essa URL:
plaintext1# Envie um arquivo local → retorna uma URL pública storage.atlascloud.ai 2curl -X POST "https://api.atlascloud.ai/api/v1/model/uploadMedia" \ 3 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \ 4 -F "file=@./reference-clip.mp4"
Pegue o download_url dessa resposta e utilize-o como a URL ao registrar o ativo na Etapa 1.
Etapa 2 — Consultar até ficar Active
O Atlas valida e pré-processa o arquivo. Consulte o status do ativo até que ele mude para Active. (Este endpoint verifica automaticamente o trabalho interno enquanto ele ainda estiver como Processing).
plaintext1curl "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>" \ 2 -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
O ciclo de vida é:
plaintext1Create → Processing → Active → (pronto para uso) 2 ↓ 3 Failed → verifique error_code / error_message
Se você obtiver Failed, o error_code e o error_message indicarão o motivo — quase sempre relacionado a limites de formato, tamanho, duração ou dimensão. Consulte as tabelas de requisitos abaixo antes de tentar registrar novamente.
Ocasionalmente, você verá erros de violação de política como o abaixo — isso ocorre porque o ativo provavelmente viola nossas diretrizes de segurança. Se você tem certeza de que o ativo não viola nenhuma regra ou se você é o detentor dos direitos autorais, entre em contato conosco para resolver!
Etapa 3 — Referenciar em uma geração
Assim que o ativo estiver como Active, passe asset://<asset_id> no campo correspondente da sua solicitação Seedance — image, last_image, reference_images, reference_video ou reference_audio, dependendo do endpoint.
Observe a mudança de host aqui: a geração ocorre em api.atlascloud.ai.
plaintext1curl -X POST "https://api.atlascloud.ai/api/v1/model/generateVideo" \ 2 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \ 3 -H "Content-Type: application/json" \ 4 -d '{ 5 "model": "bytedance/seedance-2.0/image-to-video", 6 "input": { 7 "prompt": "Um plano dolly cinematográfico, luz de pôr do sol quente", 8 "image": "asset://<asset_id>" 9 } 10 }'
Isso retorna um prediction id. Consulte-o para verificar o vídeo concluído:
plaintext1curl "https://api.atlascloud.ai/api/v1/model/prediction/<prediction_id>" \ 2 -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
Quando o status for completed (ou succeeded), a URL do resultado estará em outputs.
Esse é o ciclo completo. O objetivo do ativo é a reutilização: registre uma vez, referencie o mesmo asset://<asset_id> em quantas gerações precisar.
Gerenciamento de ativos
A biblioteca oferece controle total do ciclo de vida.
plaintext1# Listar seus ativos (paginado, suporta filtros) 2curl "https://console.atlascloud.ai/api/v1/sd/assets" \ 3 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" 4 5# Renomear um ativo 6curl -X PUT "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>" \ 7 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \ 8 -H "Content-Type: application/json" \ 9 -d '{ "name": "sunset-reference-v2" }' 10 11# Mover para a lixeira (recuperável — é uma exclusão lógica, não física) 12curl -X DELETE "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>" \ 13 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" 14 15# Listar ativos na lixeira 16curl "https://console.atlascloud.ai/api/v1/sd/assets/trash" \ 17 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" 18 19# Restaurar da lixeira 20curl -X POST "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>/restore" \ 21 -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
A exclusão é reversível por design — os ativos vão para a lixeira e podem ser restaurados, garantindo que um comando errado não cause a perda do ativo.
Requisitos de entrada
A validação ocorre no momento do registro, portanto, um arquivo malformado falhará aqui — antes que você gaste uma chamada de geração. Respeite estes limites para evitar um status Failed.
Imagem
| Propriedade | Limite |
|---|---|
| Formatos | jpeg, png, webp, bmp, tiff, gif, heic/heif |
| Proporção (W/H) | 0.4 – 2.5 |
| Largura / altura | 300 – 6000 px |
| Tamanho | < 30 MB |
Vídeo
| Propriedade | Limite |
|---|---|
| Formatos | mp4, mov |
| Resolução | 480p, 720p |
| Duração | 2 – 15 s |
| Proporção (W/H) | 0.4 – 2.5 |
| Largura / altura | 300 – 6000 px |
| Total de pixels (W×H) | 409.600 – 927.408 (ex: 640×640 a 834×1112) |
| Tamanho | ≤ 50 MB |
| FPS | 24 – 60 |
Áudio
| Propriedade | Limite |
|---|---|
| Formatos | wav, mp3 |
| Duração | 2 – 15 s |
| Tamanho | ≤ 15 MB |
Códigos de erro
| Código | Significado |
|---|---|
| 200 | Sucesso |
| 400 | Solicitação inválida |
| 401 | Chave de API ausente ou inválida |
| 404 | Ativo não encontrado |
| 500 | Erro no servidor |
Pontos de atenção
- Vídeo e áudio devem ser pré-registrados. Apenas imagens podem ser passadas inline. Pule o registro para vídeo/áudio e a geração não terá nada para referenciar.
- Apenas URL, sem base64. O arquivo fonte deve estar em uma URL pública no momento do registro.
- Dois hosts. Ativos em console.atlascloud.ai; geração em api.atlascloud.ai. Confundi-los é a causa mais comum de erros 404 / 401.
- Valide-depois-gere. Entradas ruins falham no registro, não durante a geração — que é justamente o objetivo. Verifique as tabelas de requisitos primeiro.
