Seedance es un modelo de generación de video desarrollado por ByteDance. Para llamar a su API, el primer obstáculo no es redactar un buen prompt, sino obtener una clave válida y colocarla en el lugar correcto. Buena parte de los errores 401 no se deben a que la clave sea incorrecta, sino a la cabecera Authorization, a la Base URL o a que el modelo no está habilitado en la cuenta.

Este artículo recorre esa cadena en orden —registro, creación, configuración, diagnóstico y rotación— y explica la diferencia entre una clave oficial y una clave emitida por una pasarela compatible.

Nota: Seedance, ByteDance, Doubao, Volcano Engine y Volcano Ark son marcas de sus respectivos titulares. Este artículo solo ofrece una explicación técnica y no implica ninguna relación de cooperación, representación ni licencia. Las interfaces y los precios se rigen por la documentación oficial o la del sitio.

1. Cuenta, modelo y clave: tres capas que no se sustituyen

Una llamada a Seedance implica tres elementos. La cuenta de la plataforma gestiona la identidad y la facturación; el servicio del modelo debe habilitarse por separado; la clave de API solo acredita quién realiza la petición. Los tres son necesarios y ninguno reemplaza a los demás.

La clave no es la contraseña de la cuenta. No sirve para iniciar sesión en la consola ni funciona como credencial de una suscripción web. Si se filtra, otra persona puede enviar tareas con tu cuota, así que conviene tratarla como información sensible desde el momento en que se crea.

En las interfaces de datos oficiales suele usarse Authorization: Bearer <API_KEY>. Las interfaces de administración —creación y gestión de claves, endpoints y otros recursos— normalmente requieren firma AK/SK. Son credenciales con propósitos distintos: no conviene insertar un AK/SK de administración en una petición del plano de datos.

2. Ruta A: obtener una clave oficial en Volcano Ark

La vía oficial encaja con equipos que necesitan conexión directa y prefieren administrar por su cuenta los recursos de nube y la facturación. Los pasos habituales son:

  1. Registrar una cuenta de Volcengine y completar la verificación de identidad y la información de la entidad conforme a la consola.
  2. Entrar en la consola de Volcano Ark y habilitar el modelo Seedance que se va a utilizar. Si el modelo no está habilitado, la llamada suele devolver un error del tipo ModelNotOpen.
  3. Localizar la página de gestión de claves de API y crear una nueva. Se recomienda un nombre que indique uso y entorno, por ejemplo seedance-prod-server.
  4. Copiar y guardar la clave de inmediato. Muchas plataformas solo la muestran completa una vez; al cerrar la página ya no puede consultarse.
  5. Enviar una tarea corta con la configuración mínima para comprobar autenticación, habilitación del modelo, cuota y facturación.
  6. Guardar la clave en variables de entorno del servidor o en un gestor de secretos, nunca en el código, la documentación o un chat.

Los nombres de los menús pueden cambiar entre versiones; consulta la guía de inicio rápido del sitio para la ruta exacta. Si varias personas comparten la cuenta, conviene crear una clave por sistema, lo que facilita la auditoría y la desactivación selectiva.

3. Ruta B: obtener una clave mediante una pasarela compatible

Si el equipo ya trabaja con una pasarela de API unificada, por lo general no necesita mantener además una cuenta de nube independiente. Tras registrarte en ZSQH AI Gateway puedes crear una clave en la consola y comprobar en la lista de modelos si el canal de video Seedance está habilitado y qué modelos y parámetros admite.

Cabe insistir en un punto: la clave de la pasarela y la clave oficial no son intercambiables. La Base URL, la cabecera de autenticación, los campos de la tarea, el mecanismo de callback y la unidad de facturación pueden diferir. Al pasar de la vía oficial a la pasarela, o al contrario, hay que sustituir el conjunto completo de la configuración; cambiar solo la clave suele provocar fallos al enviar tareas.

El registro se realiza en ZSQH AI Gateway y los modelos disponibles y la forma de facturación figuran en precios de modelos. Los precios cambian; antes de contratar, toma como referencia lo que muestre la página.

4. Cómo elegir entre clave oficial y clave de pasarela

Dimensión Clave oficial de Volcano Ark Clave de pasarela compatible
Cuenta e identidad Requiere cuenta de Volcengine y verificación Registro según los requisitos de la pasarela
Base URL Dirección oficial del plano de datos Dirección proporcionada por la pasarela
Alcance de permisos Limitado por cuenta, habilitación y cuota Limitado por la configuración de modelos y saldo de la pasarela
Facturación Factura del proveedor Factura de la pasarela; precios en la página correspondiente
Escenario adecuado Conexión directa y gestión propia de recursos de nube Entrada única para varios modelos y menos mantenimiento de cuentas
Punto de atención Las operaciones de administración requieren AK/SK Confirmar antes el canal de video y el soporte de callbacks

El criterio no debería ser únicamente cuál parece más económica, sino si el equipo puede asumir el mantenimiento de cuentas, la revisión de cumplimiento y el diagnóstico de fallos. El precio es solo un factor; la estabilidad y la portabilidad también importan.

5. Colocar la clave en variables de entorno

Tanto la clave oficial como la de pasarela deben evitar el código hardcodeado. Este ejemplo muestra la forma mínima de una llamada:

# .env solo para uso local; debe figurar en .gitignore
export ARK_API_KEY="tu-clave-de-volcengine-ark"
export SEEDANCE_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"

# Prueba de humo: solo valida la autenticación y la creación de la tarea
curl -sS -X POST "$SEEDANCE_BASE_URL/contents/generations/tasks" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-pro-250528",
    "content": [{"type": "text", "text": "Calle de una ciudad después de la lluvia, la cámara avanza despacio, estilo cinematográfico"}],
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p"
  }'

El ID de modelo y los parámetros del ejemplo solo ilustran la forma de la petición; copia los valores reales de la consola o de la documentación oficial. En Python se lee con os.environ; en Node.js, con process.env. En integración continua se usan los secretos de la plataforma y, en producción, un gestor de secretos. Antes de escribir en el log, redacta el valor de Authorization para que la clave no acabe en la plataforma de registros a través de un informe de errores.

6. Orden de diagnóstico de un error 401

Cuando aparece un 401, no reintentes de inmediato. Revisa en este orden:

  • Que la cabecera sea exactamente Authorization: Bearer <clave>, con un espacio después de Bearer.
  • Que la clave no incluya saltos de línea, comillas ni espacios sobrantes, algo frecuente al copiar desde la consola.
  • Que la Base URL corresponda a la plataforma que emitió la clave. Una clave oficial con una dirección de pasarela, o al revés, fallará en la autenticación.
  • Que la clave no esté desactivada, eliminada o caducada. Tras un cambio de responsable es común que la clave antigua ya no sirva y el código no se haya actualizado.
  • Que la cuenta no tenga deudas y que el servicio esté habilitado. Estos casos a veces devuelven 403 en lugar de 401, por lo que conviene revisar ambos.
  • Que la región y el endpoint sean correctos. Las direcciones de distintas regiones no deben mezclarse y, en llamadas transfronterizas, también influye la ruta de red.

Un 401 solo indica que la identidad no se validó. Reintentar a ciegas no resuelve nada. Imprime la cabecera redactada, la dirección de destino y el cuerpo de la respuesta, y compara cada elemento.

7. Lista de seguridad de la clave

  • Una clave por entorno: desarrollo, pruebas y producción separados, para acotar el impacto de una filtración.
  • Permisos mínimos: habilitar solo los modelos que el negocio necesita; en cuentas empresariales, usar subusuarios IAM y AK/SK para las operaciones de administración.
  • Nunca en el frontend: la clave permanece en el servidor y la web o la app envían las peticiones a través de su propio backend.
  • Nada en texto plano: el centro de configuración cifra el valor y la base de datos no guarda la clave completa.
  • Vigilar anomalías: configurar alertas de cuota y revisar picos de consumo, IP inusuales y tasa de fallos.
  • Conservar auditoría: registrar quién creó y usó cada clave y cuándo, durante al menos un ciclo de rotación.

8. Rotación y respuesta ante una filtración

La rotación periódica reduce el riesgo de una filtración prolongada. El orden recomendado es:

  1. Crear una clave nueva con la fecha en el nombre, por ejemplo seedance-prod-202610.
  2. Escribirla en el centro de configuración y aplicarla primero a una instancia o a un entorno.
  3. Ejecutar el circuito mínimo de envío, sondeo y descarga, y confirmar que la facturación y la cuota son correctas.
  4. Tras el cambio completo, observar de 24 a 48 horas hasta que el uso de la clave antigua llegue a cero.
  5. Desactivar y eliminar la clave antigua, y revisar logs y facturas en busca de llamadas anómalas.

Si sospechas una filtración, invierte el orden: desactiva primero la clave afectada, revisa después el historial de llamadas y la facturación, y por último reconstruye y analiza lo ocurrido. Cambiar solo la cadena en el código sin revocar la clave antigua deja el riesgo abierto.

Preguntas frecuentes

¿La clave de API de Seedance es lo mismo que la contraseña de la cuenta de Volcengine?

No. La clave solo sirve para autenticar llamadas a la interfaz y no permite iniciar sesión en la consola. La contraseña se usa para la consola y la gestión de la cuenta. Conviene guardarlas por separado y no registrarlas en el mismo lugar.

La clave es correcta, ¿por qué sigue devolviendo 401?

Las causas habituales son un formato incorrecto de la cabecera, espacios o saltos de línea al copiar, una Base URL que no corresponde a la plataforma de la clave, una clave desactivada y un estado anómalo de la cuenta o del servicio. Haz primero una petición mínima con curl y descarta cada punto.

¿Una sola clave puede llamar a modelos de texto y de video?

Depende del estado de habilitación y de los permisos configurados en la plataforma. Aunque se trate de la misma cuenta, cada modelo debe habilitarse por separado. Confirma en la consola antes de llamar y guíate por la respuesta real.

¿Se puede colocar la clave en el frontend de una web o de una app?

No es recomendable y no debería hacerse. El código del frontend puede extraerse y la clave quedaría expuesta. Lo correcto es que el backend propio custodie la clave y actúe como intermediario, con autenticación de usuarios y limitación de peticiones.

¿Cada cuánto tiempo hay que rotar la clave?

No existe un estándar único. Una práctica común es rotar cada 90 días y hacerlo de inmediato ante cambios de personal, sospechas de filtración o cambio de proveedor. Antes de rotar, confirma que todos los clientes de la clave antigua ya migraron.

Siguiente paso

Decide primero si usarás la vía oficial o una pasarela; después crea una clave dedicada y ejecuta una prueba de humo con la tarea más corta posible. Si necesitas un punto de entrada unificado, puedes registrarte en ZSQH AI Gateway y confirmar el canal de Seedance y su facturación en la página de precios de modelos.

Lecturas relacionadas: