Si estás creando flujos de trabajo de video en Seedance 2.0 o 2.0-Fast, la Biblioteca de activos (Asset Library) es la forma de incorporar medios de referencia —imágenes, video y audio— a tus generaciones de forma limpia. En lugar de pasar archivos sin procesar en cada llamada, registras un archivo una vez, Atlas lo valida y preprocesa, y luego lo referencias mediante un ID estable en todas las generaciones que desees.
Esta guía te lleva de cero a una referencia funcional en tres llamadas cURL.
Qué es (y qué no es) la Biblioteca de activos
Es un almacén de medios gestionado diseñado específicamente para la generación de video en Seedance 2.0 / 2.0-Fast. Registras un activo, este se preprocesa y, una vez que está en estado Activo (Active), lo referencias como asset://<asset_id> en tu solicitud de generación.
Dos cosas que debes saber desde el principio, ya que te ahorrarán tiempo de depuración:
- El video y el audio deben registrarse aquí primero. No se pueden pasar directamente como URLs en una solicitud de generación. Solo las imágenes pueden enviarse directamente. Por lo tanto, para cualquier flujo de trabajo de referencia de video o audio, la Biblioteca de activos es el punto de entrada obligatorio, no una comodidad opcional.
- La carga se realiza únicamente mediante URL pública. No se admiten URLs en Base64 o data URLs. El archivo debe estar disponible en una URL de acceso público al momento de registrarlo.
Antes de empezar
Necesitarás una clave de API de Atlas Cloud desde el panel de control.
Un detalle que suele causar confusión: la Biblioteca de activos y la API de generación residen en 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;}
| Función | Host | URL base |
|---|---|---|
| Biblioteca de activos (registrar, consultar, gestionar) | console | https://console.atlascloud.ai/api/v1 |
| Generación de video | api | https://api.atlascloud.ai/api/v1 |
Ambas utilizan la misma cabecera de autenticación:
plaintext1export ATLASCLOUD_API_KEY="your-api-key-here"
plaintext1Authorization: Bearer $ATLASCLOUD_API_KEY
El flujo de tres pasos
Registrar → consultar hasta que esté Activo → referenciar en una generación.
Paso 1 — Registrar un activo
Indica a Atlas una URL pública. Define el tipo como Image, Video o Audio (el valor predeterminado es 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 }'
La respuesta devuelve el id del activo y un estado de Procesando (Processing).
Se verá así:
Guarda el id (resaltado arriba); es lo que usarás para consultar y referenciar.
Nota rápida: ¿Qué cuenta como una "URL pública"?
Este es el paso donde la gente se equivoca más a menudo, así que es importante ser preciso. Atlas obtiene tu archivo realizando un HTTP GET simple a la URL. Esa URL debe devolver los bytes del archivo sin procesar directamente: sin inicio de sesión, sin cookies, sin páginas de "hacer clic para ver" y sin necesidad de ejecutar JavaScript para renderizarlo.
La prueba rápida: abre la URL en una pestaña privada o de incógnito en tu navegador. Si la imagen se muestra o el video se descarga sin pedir inicio de sesión, Atlas puede obtenerlo. Si ves una página de visualización, un aviso de inicio de sesión o una interfaz de vista previa, no funcionará.
Esto significa que los enlaces compartidos de Google Photos o Google Drive no funcionarán. Esos enlaces apuntan a una página web que muestra tus medios detrás del sistema de autenticación y redirección de Google, no al archivo en sí. Atlas obtendría el contenedor de la página, no el medio.
Qué funciona en su lugar:
- Almacenamiento de objetos con lectura pública o una URL prefirmada (presigned URL): Amazon S3, Google Cloud Storage, Cloudflare R2, Azure Blob. Las URLs prefirmadas son ideales: públicas pero limitadas en el tiempo.
- Una CDN o tu propio servidor web sirviendo el archivo directamente.
- El endpoint de carga propio de Atlas: si solo tienes un archivo local (o algo que exportaste de Google Photos), súbelo primero a Atlas para obtener una URL de almacenamiento público y luego registra esa URL:
plaintext1# Cargar un archivo local → devuelve una 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"
Toma la download_url de esa respuesta y úsala como url cuando registres el activo en el Paso 1.
Paso 2 — Consultar hasta que esté Activo
Atlas valida y preprocesa el archivo. Consulta el estado del activo hasta que cambie a Activo. (Este endpoint verifica automáticamente el trabajo en segundo plano mientras sigue procesándose).
plaintext1curl "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>" \ 2 -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
El ciclo de vida es:
plaintext1Crear → Procesando → Activo → (listo para usar) 2 ↓ 3 Fallido → verificar error_code / error_message
Si obtienes el estado Fallido (Failed), el error_code y error_message te dirán por qué; casi siempre se debe a límites de formato, tamaño, duración o dimensiones. Consulta las tablas de requisitos a continuación antes de volver a registrar.
Ocasionalmente, verás errores de violación de políticas como el que se muestra abajo; esto ocurre porque el activo probablemente infringe las salvaguardas (guardrails). Si consideras firmemente que el activo no infringe ninguna norma o eres el titular de los derechos de autor, ¡contáctanos para resolverlo!
Paso 3 — Referenciarlo en una generación
Una vez que el activo esté Activo, pasa asset://<asset_id> al campo correspondiente de tu solicitud de Seedance: image, last_image, reference_images, reference_video o reference_audio, dependiendo del endpoint.
Ten en cuenta el cambio de host aquí: la generación se realiza en 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": "A cinematic dolly shot, warm sunset light", 8 "image": "asset://<asset_id>" 9 } 10 }'
Esto devuelve un id de predicción. Consúltalo para obtener el video terminado:
plaintext1curl "https://api.atlascloud.ai/api/v1/model/prediction/<prediction_id>" \ 2 -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
Cuando el estado sea completado (completed o succeeded), la URL del resultado estará en outputs.
Ese es el ciclo completo. El objetivo del activo es la reutilización: regístralo una vez y referencia ese mismo asset://<asset_id> en todas las generaciones que necesites.
Gestión de activos
La biblioteca te ofrece un control total del ciclo de vida.
plaintext1# Listar tus activos (paginado, admite filtros) 2curl "https://console.atlascloud.ai/api/v1/sd/assets" \ 3 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" 4 5# Renombrar un activo 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 a la papelera (recuperable — esto es una eliminación lógica, no 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 activos en la papelera 16curl "https://console.atlascloud.ai/api/v1/sd/assets/trash" \ 17 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" 18 19# Restaurar desde la papelera 20curl -X POST "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>/restore" \ 21 -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
La eliminación está diseñada para ser recuperable: los activos se mueven a la papelera y pueden restaurarse, por lo que una llamada incorrecta no implica perder el activo.
Requisitos de entrada
La validación ocurre en el momento del registro, por lo que un archivo mal formado fallará aquí, antes de que gastes una llamada de generación en él. Cumple con estos límites para evitar un estado Fallido (Failed).
Imagen
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;}
| Propiedad | Límite |
|---|---|
| Formatos | jpeg, png, webp, bmp, tiff, gif, heic/heif |
| Relación de aspecto (A/H) | 0.4 – 2.5 |
| Ancho / alto | 300 – 6000 px |
| Tamaño | < 30 MB |
Video
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;}
| Propiedad | Límite |
|---|---|
| Formatos | mp4, mov |
| Resolución | 480p, 720p |
| Duración | 2 – 15 s |
| Relación de aspecto (A/H) | 0.4 – 2.5 |
| Ancho / alto | 300 – 6000 px |
| Total de píxeles (A×H) | 409,600 – 927,408 (ej. 640×640 a 834×1112) |
| Tamaño | ≤ 50 MB |
| FPS | 24 – 60 |
Audio
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;}
| Propiedad | Límite |
|---|---|
| Formatos | wav, mp3 |
| Duración | 2 – 15 s |
| Tamaño | ≤ 15 MB |
Códigos de error
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;}
| Código | Significado |
|---|---|
| 200 | Éxito |
| 400 | Solicitud inválida |
| 401 | Clave de API faltante o inválida |
| 404 | Activo no encontrado |
| 500 | Error del servidor |
Detalles importantes a recordar
- El video y el audio deben pre-registrarse. Solo las imágenes pueden pasarse directamente. Si omites el registro para video/audio, la generación no tendrá nada que referenciar.
- Solo URL, no base64. El archivo de origen debe residir en una URL pública en el momento del registro.
- Dos hosts. Los activos van en console.atlascloud.ai; la generación en api.atlascloud.ai. Confundirlos es la causa más común de errores 404 / 401.
- Validar primero, generar después. Las entradas incorrectas fallan en el registro, no a mitad de la generación, que es precisamente el objetivo. Consulta primero las tablas de requisitos.
