Lista de verificación de producción de Seedance API para equipos de texto a video

Un prototipo de Seedance API puede parecer terminado después de un solo video exitoso. Una integración de producción solo está terminada cuando su sistema puede sobrevivir a trabajos lentos, eventos duplicados, rutas de modelo cambiantes, fallos parciales e incertidumbre de costos.

Esa diferencia importa porque la generación de video no es una característica normal de solicitud-respuesta. La aplicación envía el trabajo, espera, recibe cambios de estado, almacena un resultado grande y decide si un fallo debe reintentarse. La llamada al modelo es solo una etapa en un flujo de trabajo más largo.

Esta lista de verificación convierte ese flujo de trabajo en un contrato de producción que sus equipos de producto, plataforma y finanzas pueden revisar juntos.

Nota sobre la ruta actual: El catálogo público de modelos de Flatkey enumeraba seedance-2.5 para texto a video y de imagen a video, además de seedance-2.0-i2v para imagen a video, cuando se revisó esta guía el lunes 27 de julio de 2026. Trate esos nombres como estado del catálogo, no como constantes permanentes. Confirme el directorio de modelos de Flatkey actual antes de poner en producción o cambiar una lista permitida.

La respuesta corta

No conecte directamente su solicitud orientada al usuario a una llamada del proveedor de video. Coloque una capa de trabajos duradera entre ambas.

Su ruta mínima de producción debería ser:

1. aceptar y validar la solicitud de generación del usuario
2. asignar su propia clave de idempotencia y ID de trabajo
3. almacenar la solicitud antes de llamar a la ruta del modelo
4. enviar el trabajo a través de un adaptador del lado del servidor
5. procesar las actualizaciones de webhook y sondeo de forma idempotente
6. copiar los medios completados al almacenamiento que usted controla
7. registrar la latencia, el motivo del fallo, la ruta del modelo y el costo estimado
8. exponer un estado de producto estable independiente de la redacción del proveedor

Si falta uno de esos pasos, es posible que la integración siga funcionando bien en una demostración, pero será más difícil operarla de forma segura.

Por qué el trabajo de producción con Seedance API es diferente

La generación de texto a menudo devuelve una respuesta útil en un solo intercambio HTTP. La generación de video suele comportarse como un trabajo por lotes distribuido. Una acción del usuario puede sobrevivir a una solicitud de aplicación, un despliegue, una sesión del navegador o incluso a la URL temporal que finalmente contiene el resultado.

Las consecuencias prácticas son fáciles de subestimar:

El objetivo no es ocultar al proveedor. Es evitar que el comportamiento específico del proveedor se convierta en el contrato permanente de tu producto.

1. Congela el contrato del producto antes del payload

Empieza por la experiencia que prometes a los usuarios, no por los campos del proveedor disponibles hoy.

Define:

• tipos de entrada aceptados: solo texto, imagen más texto, o ambos
• relaciones de aspecto y rangos de duración admitidos
• tamaño máximo de carga y formatos de medios aceptados
• comprobaciones de moderación y derechos antes del envío
• actualizaciones de estado esperadas y comportamiento de cancelación
• período de retención de la salida
• si un trabajo fallido consume crédito del usuario
• qué significa “reintentar” en el producto

Luego traduce ese contrato a la ruta actual de Seedance dentro de un adaptador.

Esta separación te protege de dos modos de fallo comunes. Primero, una actualización de ruta puede añadir o renombrar parámetros sin obligar a reescribir el frontend. Segundo, tu aplicación puede rechazar combinaciones no compatibles antes de gastar dinero en un trabajo condenado al fracaso.

2. Usa tu propio ID de trabajo y clave de idempotencia

Cada solicitud necesita dos identificadores:

• ID de trabajo del producto: el identificador estable que se muestra en todo tu sistema
• clave de idempotencia: el identificador usado para evitar envíos duplicados accidentales

No uses un ID de tarea del proveedor como clave primaria. No existe hasta después del envío y puede cambiar si lo reenvías deliberadamente por otra ruta.

Un registro simple de solicitud puede verse así:

type VideoJob = {
  id: string;
  idempotencyKey: string;
  accountId: string;
  requestedModel: string;
  resolvedModel: string | null;
  providerTaskId: string | null;
  status: "accepted" | "queued" | "running" | "succeeded" | "failed" | "cancelled";
  attempt: number;
  outputUrl: string | null;
  failureCode: string | null;
  createdAt: string;
  updatedAt: string;
};

Crea este registro antes de la llamada saliente a la API. Si la aplicación falla después del envío pero antes de guardar la respuesta, la clave de idempotencia te da una forma de conciliar en lugar de cobrar a ciegas por otra generación.

3. Coloca Seedance detrás de un único adaptador del lado del servidor

Mantén la construcción de solicitudes específica del proveedor en un solo módulo. El resto de tu producto debería enviar un comando normalizado como:

type GenerateVideoCommand = {
  prompt: string;
  sourceImageUrl?: string;
  aspectRatio: "16:9" | "9:16" | "1:1";
  durationSeconds: number;
  qualityProfile: "draft" | "standard" | "high";
};

El adaptador es responsable de:

• resolver qualityProfile a un modelo y ajustes actualmente disponibles
• adjuntar la autenticación del lado del servidor
• traducir tus opciones de aspecto y duración al esquema activo de la API
• enviar la tarea
• normalizar los errores del proveedor
• almacenar el ID de tarea del proveedor
• informar suficientes metadatos para el análisis de coste y fiabilidad

Flatkey ofrece a los equipos una clave API, un endpoint de enrutamiento estable, un saldo compartido y visibilidad centralizada del uso en todas las familias de modelos. Para los equipos que ya usan esa capa de acceso, mantén la lógica asíncrona específica de Seedance en el adaptador en lugar de dispersar suposiciones de rutas por toda la base de código. La guía anterior sobre una URL base estable compatible con OpenAI para equipos de Seedance API explica ese límite con más detalle.

4. Modela el flujo de trabajo como una máquina de estados

No permitas que cadenas de estado arbitrarias entren en la lógica del producto. Normalízalas.

stateDiagram-v2
    [*] --> accepted
    accepted --> queued: submit accepted
    accepted --> failed: validation or submit error
    queued --> running: provider starts work
    queued --> failed: terminal provider error
    running --> succeeded: output verified
    running --> failed: terminal provider error
    accepted --> cancelled: cancelled before submit
    queued --> cancelled: cancellation confirmed
    succeeded --> [*]
    failed --> [*]
    cancelled --> [*]

Permite solo transiciones hacia adelante, a menos que estés ejecutando un proceso explícito de recuperación. Un evento running tardío no debe sobrescribir un trabajo ya marcado como succeeded. Un webhook succeeded duplicado no debe disparar dos copias de almacenamiento ni dos notificaciones al cliente.

Guarda el evento bruto del proveedor por separado para depuración, pero toma las decisiones del producto a partir del estado normalizado.

5. Usa webhooks y polling juntos

Los webhooks son eficientes, pero no garantizan que tu aplicación procese todos los eventos una sola vez y en orden. El polling es más lento, pero es valioso para la reconciliación.

Usa ambos:

• ruta de webhook: actualizaciones de estado de baja latencia
• ruta de polling: recuperación programada para trabajos que no han cambiado recientemente

Tu controlador de webhooks debería:

1. autenticar la devolución de llamada cuando la API activa admita verificación
2. analizar el evento sin realizar trabajo pesado en línea
3. escribir una huella digital del evento en una tabla de desduplicación
4. encolar el procesamiento
5. devolver éxito rápidamente

Tu trabajador de reconciliación debería hacer polling solo de los trabajos que sigan sin estado terminal después de un retraso sensato. Añade jitter para que un despliegue no provoque miles de comprobaciones de estado al mismo instante.

Los campos específicos del proveedor para webhook y consulta pueden cambiar. Verifícalos frente a la referencia oficial actual de la API durante la implementación en lugar de copiar una carga útil antigua de una publicación de blog.

6. Tomar decisiones de reintento por clase de fallo

“Reintentar trabajos fallidos” no es una política. Es un riesgo de costos.

Normaliza los errores en clases:

La última distinción es especialmente importante. Si el video se generó correctamente pero falló tu copia al almacenamiento, regenerar el video crea un costo innecesario y puede producir un resultado diferente.

Establece un presupuesto de reintentos por trabajo. Una política razonable podría permitir más comprobaciones de estado e intentos de copia al almacenamiento que envíos de generación.

7. Copia las salidas al almacenamiento que controlas

Trata cualquier URL de resultado alojada por el proveedor como una ubicación de transferencia, no como el activo permanente de tu producto.

Después de que un trabajo tenga éxito:

1. verifica que la respuesta contenga el tipo de medio esperado
2. descarga con un límite de tamaño y tiempo
3. valida que el archivo no esté vacío o truncado de forma evidente
4. calcula una suma de verificación
5. cópialo a tu almacenamiento de objetos
6. guarda duración, dimensiones, códec y tamaño
7. cambia el trabajo del producto a succeeded solo después de que la copia duradera esté disponible

Si tu producto permite a los usuarios descargar el activo original del proveedor antes de que termine la copia, represéntalo como un estado transitorio separado. No prometas permanencia en silencio.

8. Añade controles de costos antes de abrir la función

Los trabajos de video son lo bastante caros como para que existan límites de producto antes del lanzamiento público.

Como mínimo, define:

• un tope de gasto por clave o por equipo
• una lista de अनुमति de modelos para la clave de la aplicación
• trabajos concurrentes máximos por cuenta
• duración máxima y perfil de calidad por plan
• un límite diario de envíos para cuentas nuevas o no confiables
• un circuito de corte cuando aumente la tasa de fallos o el costo por éxito

La documentación pública de Flatkey describe topes por clave, listas de अनुमति opcionales de modelos y visibilidad de uso a través de Usage & Logs o la API de ledger. Usa esos controles como la barrera de protección de la capa de acceso y luego añade cuotas a nivel de producto basadas en tus propios planes y en el riesgo de abuso.

Antes de habilitar una nueva ruta, compare el catálogo actual y los precios de Flatkey. No incorpore un precio numérico de este artículo en la lógica de la aplicación; los precios y la disponibilidad de rutas son datos actualizables.

9. Mida el trabajo completo, no solo la latencia de la API

Para un flujo de trabajo asíncrono de la API de Seedance, una solicitud enviada correctamente aún puede generar una mala experiencia del cliente.

Rastree al menos:

• tasa de aceptación de envíos
• tiempo de espera en cola
• tiempo de generación
• tiempo total hasta una salida persistente
• tasa de éxito por modelo resuelto
• tasa de fallo por clase de fallo normalizada
• retardo de entrega de webhook
• tasa de recuperación por sondeo
• tasa de fallo de copia al almacenamiento
• coste por trabajo enviado
• coste por salida persistente exitosa
• conteo de prevención de envíos duplicados

Use percentiles, no solo promedios. Un tiempo medio de generación puede parecer saludable mientras que el diez por ciento más lento de los trabajos genera la mayoría de los tickets de soporte.

Registre también requestedModel y resolvedModel por separado. Eso hace visibles los cambios de ruta y le da evidencia para las decisiones de reversión.

10. Publique los cambios de modelo como migraciones

Un cambio de catálogo no es solo un reemplazo de cadena. Trátelo como una actualización de dependencia.

Antes de mover el tráfico de producción a una nueva ruta de Seedance:

1. confirme la ruta actual en el directorio de modelos en vivo
2. compare las entradas compatibles y las restricciones de salida
3. ejecute un conjunto de evaluación fijo en sus tipos de prompt habituales
4. compare la tasa de éxito, la latencia, la aceptación de salida y el coste
5. pruebe webhook, sondeo y normalización de errores
6. haga canary con un pequeño porcentaje del tráfico
7. conserve una ruta de reversión hasta que el canary sea estable
8. actualice la lista de अनुमति de modelos y el manual operativo

Si su aplicación expone una configuración de “calidad”, asígnela a un perfil de capacidad en lugar de a un ID de modelo permanente. Eso le permite cambiar la ruta subyacente sin romper la API del producto.

Lista de verificación de preparación para producción

Use esta lista como criterio de lanzamiento.

Solicitud y acceso

• [ ] las claves de API permanecen del lado del servidor
• [ ] la clave de la aplicación tiene un límite de gasto y una lista de permitidos de modelos
• [ ] cada solicitud tiene un ID interno de trabajo y una clave de idempotencia
• [ ] las entradas se validan antes del envío
• [ ] la ruta actual del modelo Seedance se comprueba en el catálogo en vivo

Ejecución asíncrona

• [ ] la lógica específica del proveedor vive en un solo adaptador
• [ ] los estados del producto usan una máquina de estados normalizada
• [ ] los eventos de webhook se autentican cuando se admite y se deduplican
• [ ] el sondeo reconcilia trabajos obsoletos no terminales
• [ ] los eventos tardíos o duplicados no pueden revertir estados terminales

Fiabilidad y coste

• [ ] el comportamiento de reintento varía según la clase de fallo
• [ ] los reintentos de generación tienen un presupuesto estricto
• [ ] los reintentos de copia de salida no regeneran vídeos exitosos
• [ ] se aplican límites de concurrencia y de trabajos diarios
• [ ] un cortafuegos de circuitos puede pausar una ruta degradada

Salida y observabilidad

• [ ] el medio exitoso se copia al almacenamiento controlado
• [ ] se almacenan los metadatos de salida y la suma de verificación
• [ ] se registran los IDs del modelo solicitados y resueltos
• [ ] se mide el costo por cada salida duradera exitosa
• [ ] los operadores tienen un runbook para trabajos atascados, fallidos y duplicados

Dónde encaja Flatkey

Flatkey no elimina la necesidad de una capa asíncrona de trabajos de video. Reduce el trabajo de acceso y gobernanza alrededor de esa capa: una cuenta, un saldo, controles de clave API, una superficie estable de enrutador, un catálogo de modelos en vivo y registros de uso centralizados.

Para una primera integración, comienza con la guía rápida de Seedance API para equipos de producto de texto a video más amplia. Cuando la funcionalidad avance hacia producción, aplica esta lista de verificación a las capas de cola, estado, reintento, almacenamiento y observabilidad alrededor de la llamada al modelo.

Si tu equipo está decidiendo qué ruta actual y qué controles de uso encajan con la implementación, revisa los modelos en vivo y los precios antes de aprobar la configuración de producción.

Preguntas frecuentes

¿La API de Seedance es sincrónica o asincrónica?

Trata la generación de video como un trabajo asíncrono. Tu producto debería enviar el trabajo, devolver su propio ID de trabajo y procesar las actualizaciones de estado mediante webhooks y/o sondeo según la referencia actual de la API.

¿Debería usar un ID de tarea del proveedor como la clave primaria de mi base de datos?

No. Crea tu propio ID de trabajo estable antes del envío. Guarda el ID de tarea del proveedor como referencia externa para que puedas reconciliar, reenviar o cambiar rutas sin cambiar el identificador del producto.

¿Necesito tanto webhooks como sondeo?

Para un sistema de producción resistente, sí. Los webhooks proporcionan actualizaciones rápidas; el sondeo recupera trabajos cuyos eventos se retrasaron, se perdieron o no se procesaron.

¿Cuándo es seguro reintentar un trabajo fallido de Seedance?

Reintenta solo después de clasificar el fallo. Los fallos de capacidad y de red pueden ser reintentables. La validación, autenticación, seguridad u otros fallos terminales suelen requerir un cambio de configuración o del usuario. Si el envío agotó el tiempo de espera, reconcilia mediante la clave de idempotencia antes de enviar otro trabajo de pago.

¿Debería almacenar yo mismo el video generado?

Sí. Copia el resultado completado al almacenamiento que controlas, valida el archivo y guarda sus metadatos. Las URL de resultados alojadas por el proveedor no deben tratarse como almacenamiento permanente del producto a menos que los términos actuales garanticen explícitamente ese comportamiento.

¿Cómo debo manejar una nueva versión del modelo Seedance?

Trátala como una migración: verifica el catálogo actual, ejecuta un conjunto fijo de evaluación, compara calidad, latencia, fallos y costo, canaliza tráfico, y conserva una ruta de reversión hasta que el cambio sea estable.

¿Qué modelo de Seedance debería codificar de forma fija?

Evita incrustar de forma permanente un modelo basado en un artículo estático. Resuelve un perfil de capacidades del producto a un modelo incluido en el directorio de modelos de Flatkey actual, y mantén la ruta elegida en la configuración para que los operadores puedan cambiarla de forma segura.