Mover un producto de texto a video de un proveedor a otro no debería requerir reescribir cada helper de autenticación, variable de entorno, regla de reintento y gancho de observabilidad. El patrón más seguro es separar las partes de tu integración que pueden permanecer estables de las partes que son específicas de la generación de video.
Para los equipos que ya usan un cliente estilo OpenAI, Flatkey ofrece un punto de partida práctico: crea una clave de API, establece la URL base del cliente en https://router.flatkey.ai/v1, ejecuta una pequeña solicitud compatible y confirma la solicitud en los registros de uso. Eso demuestra la capa de conexión compartida antes de adjuntar un flujo de trabajo asíncrono de video específico de Seedance.
Esta guía muestra cómo hacer que esa migración sea controlada, reversible y fácil de inspeccionar.
Respuesta rápida
Una URL base estable compatible con OpenAI puede reducir el trabajo de migración de las partes compartidas de una integración de IA:
- inyección de clave de API
- configuración del entorno
- inicialización del cliente
- correlación de solicitudes
- política de reintentos y timeouts
- monitoreo de uso y costos
No significa que cada proveedor de texto a video use el mismo cuerpo de solicitud o el mismo endpoint. La generación de video normalmente necesita un flujo asíncrono separado: crear un trabajo, almacenar el ID del trabajo, hacer polling o recibir un webhook y recuperar el recurso final.
Por lo tanto, el objetivo de implementación no es “forzar a Seedance a través de una forma de chat completions”. Es “mantener estable la conexión del gateway y luego aislar el adaptador de trabajos específico de video detrás de una interfaz pequeña”.
Por qué la estabilidad de la URL base importa para los productos de texto a video
Las migraciones de proveedores suelen fallar en las costuras alrededor de la llamada al modelo, no en la única línea que nombra un modelo. Una aplicación de producción puede tener claves de API en un gestor de secretos, clientes HTTP en varios servicios, workers de colas, manejadores de webhooks, registros de auditoría, alertas de gasto y ajustes de reversión.
Si cada proveedor se conecta directamente a todas esas capas, agregar un nuevo modelo de video se convierte en un cambio amplio de infraestructura. Un límite estable del gateway reduce el radio de impacto.
| Capa | Mantener estable | Cambiar solo cuando sea necesario |
|---|---|---|
| Credenciales | Nombre del secreto y patrón de inyección | Valor de la clave y registro de rotación |
| Cliente | Inicialización compartida del cliente HTTP o estilo OpenAI | Adaptador de video usado para la ruta seleccionada |
| URL base | Una URL de gateway controlada por el entorno | Solo durante una reversión intencional del gateway |
| Observabilidad | ID de correlación, logs, latencia, revisión de costos | Campos de estado de trabajos específicos del proveedor |
| Confiabilidad | Presupuestos de timeout, propiedad de reintentos, política de circuit breaker | Intervalo de polling y estados terminales del video |
| Lógica del producto | Solicitud del usuario, derechos, cuota, ciclo de vida del recurso | Prompt de Seedance y parámetros de video |
El resultado es una superficie de migración más pequeña. El código de tu producto sigue dependiendo de una interfaz interna estable mientras el adaptador maneja las diferencias en las APIs de video.
La secuencia de migración más segura
Usa dos verificaciones separadas en lugar de intentar validar toda la ruta de video en una sola solicitud.
- Prueba de humo de conexión: verifica la autenticación, la URL base compatible con OpenAI, el acceso de red y los Registros de uso.
- Prueba del flujo de trabajo de video: verifica la ruta actual de Seedance, los parámetros aceptados, las transiciones asíncronas de estado, la entrega de activos y el comportamiento de facturación.
Esta separación facilita clasificar los fallos. Si falla la prueba de humo, es probable que el problema esté en las credenciales, la configuración de la URL base, la red o el manejo compartido de solicitudes. Si la prueba de humo pasa pero falla el trabajo de video, céntrate en la ruta del modelo y en el adaptador de video.
Step 1: move the base URL into configuration
No codifiques una URL del proveedor en la lógica de la aplicación. Coloca la conexión del gateway en variables de entorno para que el despliegue y la reversión no requieran cambios de código.
FLATKEY_API_KEY=sk-fk-replace-me
AI_BASE_URL=https://router.flatkey.ai/v1
AI_SMOKE_TEST_MODEL=gpt-4o-mini
VIDEO_PROVIDER=flatkey
VIDEO_MODEL=replace-with-current-seedance-route
Trata el valor del modelo de video como una configuración de momento de despliegue. Los alias de modelo y las capacidades compatibles pueden cambiar, así que confirma la ruta actual en Flatkey antes del despliegue en lugar de copiar un identificador antiguo de una publicación de blog.
Step 2: initialize the existing OpenAI-style client once
Si tu aplicación ya usa el SDK de Python de OpenAI, el cambio de conexión compartida es intencionalmente pequeño.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.getenv("AI_BASE_URL", "https://router.flatkey.ai/v1"),
)
La configuración equivalente en TypeScript mantiene la misma frontera:
import OpenAI from "openai";
export const aiClient = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: process.env.AI_BASE_URL ?? "https://router.flatkey.ai/v1",
});
La decisión de diseño importante es que los servicios importen un cliente configurado en lugar de construir sus propios clientes específicos del proveedor a lo largo de toda la base de código.
Step 3: run a connection smoke test before touching video jobs
La guía de inicio rápido de Flatkey usa una solicitud de chat completions compatible con OpenAI y luego te pide verificar la llamada en los Registros de uso. Usa esa pequeña prueba para demostrar la capa de integración compartida.
import os
from app.ai_client import client
def verify_gateway_connection() -> dict:
response = client.chat.completions.create(
model=os.getenv("AI_SMOKE_TEST_MODEL", "gpt-4o-mini"),
messages=[
{"role": "user", "content": "Reply with: gateway connection verified"}
],
max_tokens=20,
)
return {
"request_model": response.model,
"finish_reason": response.choices[0].finish_reason,
"usage": response.usage.model_dump() if response.usage else None,
}
Esta solicitud no prueba la generación de video de Seedance. Verifica cuatro requisitos previos de los que dependen ambos flujos de trabajo:
- la clave está presente y es aceptada
- la URL base es correcta
- la aplicación puede الوصول al router
- la solicitud aparece en el panel con datos de uso
Para una guía detallada del primer request, usa la guía de inicio rápido de Seedance API para equipos de producto.
Paso 4: mantén Seedance detrás de un adaptador asíncrono de video
La generación de texto a video suele tardar más que una solicitud API síncrona normal. El flujo público de la API de Seedance describe la creación de tareas seguida de comprobaciones de estado o entrega mediante webhook. Modela ese ciclo de vida de forma explícita.
export type VideoJobState =
| "queued"
| "running"
| "succeeded"
| "failed"
| "cancelled";
export interface VideoJob {
id: string;
state: VideoJobState;
outputUrl?: string;
errorCode?: string;
}
export interface TextToVideoAdapter {
createJob(input: {
prompt: string;
model: string;
idempotencyKey: string;
}): Promise<VideoJob>;
getJob(jobId: string): Promise<VideoJob>;
}
El adaptador debe traducir los campos internos estables de tu producto al payload requerido por el endpoint de video actual. Mantén los parámetros específicos del proveedor dentro de ese adaptador, en lugar de filtrarlos hacia controladores, código de interfaz o esquemas de cola.
No asumas que el endpoint de video es /chat/completions, y no asumas que una respuesta de chat demuestra que la ruta Seedance seleccionada está disponible. Confirma el endpoint actual, el alias del modelo, los parámetros y los valores de estado en la documentación del producto o en el panel en el momento de la implementación.
Paso 5: haz que el polling sea seguro y acotado
Un worker de video necesita reglas de fiabilidad distintas a las de una solicitud de chat. Hacer polling indefinidamente no es una estrategia de reintento.
import random
import time
TERMINAL_STATES = {"succeeded", "failed", "cancelled"}
def wait_for_video(adapter, job_id: str, deadline_seconds: int = 600):
started_at = time.monotonic()
attempt = 0
while time.monotonic() - started_at < deadline_seconds:
job = adapter.get_job(job_id)
if job.state in TERMINAL_STATES:
return job
attempt += 1
delay = min(30, 2 ** min(attempt, 4))
time.sleep(delay + random.uniform(0, 1))
raise TimeoutError(f"Video job {job_id} exceeded its processing deadline")
El polling en producción también debe respetar la guía del proveedor y cualquier encabezado Retry-After. Guarda el ID externo de la tarea antes de hacer polling para que un reinicio del worker no cree un video duplicado.
Si hay webhooks disponibles, verifica las firmas, responde rápidamente y haz que el handler sea idempotente. Un webhook puede entregarse más de una vez o llegar después de que un worker de polling ya haya completado la tarea.
Paso 6: añade observabilidad en ambas capas
Supervisa por separado la solicitud del gateway y la tarea de video a nivel de producto.
Campos del gateway
- entorno y nombre del servicio
- ID interno de la solicitud
- ruta o alias del modelo
- estado HTTP
- latencia
- recuento de reintentos
- datos de uso o coste visibles en el panel
Campos de la tarea de video
- ID externo de la tarea
- ID de usuario o de espacio de trabajo
- versión del prompt, sin registrar de forma predeterminada el contenido sensible del prompt
- modelo y modo de capacidad
- marcas de tiempo de encolado, inicio y finalización
- estado terminal y código de error normalizado
- ubicación del activo de salida y política de retención
El panel es el punto de control operativo compartido. Después de la prueba rápida y del primer trabajo de video controlado, compare los registros de la aplicación con los registros de uso de Flatkey. Investigue los registros faltantes, los trabajos duplicados, los nombres de modelo inesperados o los cambios de costo antes de ampliar el tráfico.
Step 7: use a reversible rollout plan
Cambiar una sola URL base es simple. Hacer un despliegue seguro aún requiere controles.
- Ejecute la prueba rápida desde un entorno de desarrollo.
- Ejecute un trabajo de evaluación de Seedance no sensible.
- Confirme el manejo del estado del trabajo, la recuperación de activos y la visibilidad del uso.
- Habilite la ruta para una cuenta interna o un pequeño porcentaje del tráfico.
- Compare la tasa de éxito, la latencia de extremo a extremo y el costo por activo completado.
- Aumente el tráfico solo después de que el margen de error siga siendo aceptable.
- Mantenga disponible la configuración del proveedor anterior hasta que expiren los criterios de reversión.
Defina los desencadenantes de reversión antes del lanzamiento. Los ejemplos incluyen errores de autenticación repetidos, una tasa elevada de trabajos fallidos, trabajos atascados más allá de la fecha límite de procesamiento, registros de uso faltantes o fallos en la recuperación de resultados.
Migration checklist
| Check | Pass condition |
|---|---|
| Key ownership | A named owner can rotate and revoke the Flatkey key |
| Secret handling | The key is server-side and absent from source control and browser bundles |
| Stable base URL | All shared clients read AI_BASE_URL from configuration |
| Connection test | The OpenAI-compatible smoke test succeeds |
| Dashboard verification | The smoke-test request appears in Usage Logs |
| Current Seedance route | The model alias and capability are confirmed at rollout time |
| Async lifecycle | Create, poll or webhook, terminal state, and asset retrieval are tested |
| Idempotency | Retries cannot create unintended duplicate videos |
| Timeout budget | Workers stop and escalate jobs that exceed the deadline |
| Observability | Gateway requests and video jobs share a correlation ID |
| Rollback | The previous configuration and decision owner are documented |
Common migration mistakes
Treating OpenAI compatibility as universal endpoint compatibility
Un cliente compatible con OpenAI puede simplificar la autenticación y las familias de solicitudes admitidas. No garantiza que cada operación multimodal o de video tenga el mismo esquema. Mantenga explícito el adaptador de video.
Changing the key, base URL, model, and worker logic in one release
Eso dificulta aislar los fallos. Demuestre primero la conexión con la pasarela y luego cambie la ruta de video.
Retrying job creation without an idempotency strategy
Puede ocurrir un tiempo de espera de red después de que el proveedor haya aceptado el trabajo. Crear otro trabajo sin comprobarlo puede producir y facturar un activo duplicado.
Using the HTTP request timeout as the video deadline
La solicitud de creación del trabajo y el ciclo de vida de procesamiento de video son temporizadores diferentes. Mantenga corta la primera solicitud y luego haga un seguimiento del plazo asíncrono en el estado duradero del trabajo.
Skipping dashboard verification
Una respuesta correcta de la aplicación no constituye la comprobación operativa completa. Confirme que la información de uso, modelo, latencia y coste aparezca donde el equipo espera supervisarla.
FAQ
¿Puedo integrar Seedance cambiando solo la URL base de OpenAI?
Cambiar la URL base puede simplificar la capa de conexión compartida para las solicitudes compatibles con OpenAI admitidas. La generación de vídeo de Seedance puede seguir requiriendo un endpoint asíncrono dedicado y parámetros específicos del proveedor. Verifique la ruta actual antes de implementar.
¿Qué debería permanecer sin cambios durante la migración?
Mantenga estables la inyección de secretos, la nomenclatura de entornos, los IDs de correlación, el registro, las alertas y la interfaz de vídeo orientada al producto. Limite los cambios específicos del proveedor a la configuración y al adaptador de vídeo.
¿Por qué ejecutar una prueba rápida de chat para un producto de vídeo?
La prueba rápida aísla rápidamente la autenticación de la pasarela, la URL base, la red y los Usage Logs del flujo de trabajo de vídeo más largo. Es una prueba de conexión, no una prueba de capacidad de vídeo.
¿Debería hacer polling o usar webhooks para la finalización del vídeo?
Use el mecanismo que admita la API de vídeo actual y su infraestructura. El polling es más sencillo, pero debe estar acotado y aplicar retroceso exponencial. Los webhooks reducen el polling, pero requieren verificación de firma, idempotencia y conciliación de eventos perdidos.
¿Cómo evito trabajos de vídeo duplicados?
Cree y persista una clave de idempotencia para la solicitud del producto, almacene inmediatamente el ID del trabajo externo y haga que los reintentos reanuden el trabajo existente siempre que sea posible.
¿Dónde debería comparar el coste antes del despliegue?
Revise la actual página de precios de Flatkey y luego compare el coste por vídeo completado en lugar de solo el precio por solicitud o por segundo. Incluya en el cálculo los trabajos fallidos y duplicados.
Construya primero el límite estable
La migración más rápida no es la que cambia menos líneas el primer día. Es la que reduce los futuros cambios de proveedor a una actualización de configuración controlada y a un pequeño adaptador.
Empiece con una clave de Flatkey, mueva el cliente compartido a la URL base estable, verifique la conexión en Usage Logs y luego pruebe el flujo de trabajo actual de Seedance como un sistema de trabajos asíncronos. Cuando pasen las comprobaciones, obtenga una clave y despliegue con métricas explícitas y disparadores de reversión.
