Si tu equipo de producto quiere la forma más rápida y segura de evaluar el acceso a Seedance API, el primer paso correcto no es construir el flujo de video completo desde el primer día. Es demostrar tres bases con la superficie de integración más pequeña posible:
- tu clave de Flatkey se autentica correctamente
- tu app puede llamar a
https://router.flatkey.ai/v1 - tu equipo puede ver la solicitud en Usage Logs antes de conectar trabajos asíncronos de video
Esa es la guía rápida de baja fricción que cubre esta página.
A fecha de viernes, 17 de julio de 2026, la guía pública de inicio rápido de Flatkey sigue indicando a los desarrolladores que usen Bearer auth, la URL base compatible con OpenAI https://router.flatkey.ai/v1 y POST /v1/chat/completions para la primera prueba de humo. El catálogo de modelos en vivo de Flatkey también enumera públicamente seedance-2.5 para texto a video e imagen a video, y seedance-2.0-i2v para imagen a video. La propia página pública de API de Seedance sigue describiendo el flujo de video como creación de tareas asíncronas, sondeo de estado, webhooks y créditos basados en uso.
Esa combinación importa para la incorporación: el patrón de acceso al router es simple, pero el flujo real de generación de video no es una llamada síncrona de chat. Los equipos de producto deberían validar primero el router con la solicitud más pequeña posible y, después, cambiar solo el modelo y el flujo de trabajo que necesiten para la evaluación de Seedance.
Respuesta rápida
Usa esta secuencia cuando quieras una ruta de incorporación de Seedance revisable con el menor número posible de componentes.
| Paso | Qué usar | Qué demuestra |
|---|---|---|
| 1. Crear una clave | Clave de API de Flatkey que empiece con sk-fk- |
Tu equipo tiene una credencial válida |
| 2. Configurar una base URL | https://router.flatkey.ai/v1 |
Tu app apunta al router compartido, no a un endpoint específico del proveedor |
| 3. Ejecutar la prueba de humo más pequeña | POST /v1/chat/completions con un modelo de texto simple |
La autenticación, los encabezados, el enrutamiento y Usage Logs funcionan |
| 4. Cambiar a la ruta de Seedance | Reemplazar el modelo de marcador de posición con el ID de modelo de Seedance aprobado | La misma capa de acceso ahora puede admitir tu flujo de evaluación de video |
| 5. Añadir manejo asíncrono | Lógica de sondeo o webhook para trabajos de video | Tu producto está listo para la ejecución real de texto a video |
Si solo recuerdas una cosa, recuerda esto: la primera solicitud cURL es una comprobación de conectividad con el router, no la carga útil final de texto a video.
Antes de empezar
Necesitas cuatro cosas:
- Una cuenta de Flatkey
- Una clave de API de Flatkey
- Algo de crédito prepago para la solicitud
- Una decisión de producto sobre qué ruta de Seedance quieres evaluar realmente
Para la mayoría de los equipos de texto a video, el catálogo público de modelos hace que las opciones actuales sean lo bastante claras como para iniciar la conversación:
| Señal pública actual del modelo en Flatkey | Mejor uso |
|---|---|
seedance-2.5 |
Evaluación de texto a video, además de imagen a video si se necesita |
seedance-2.0-i2v |
Solo imagen a video |
No codifique de forma rígida un nombre de modelo a partir de una captura antigua o una nota interna. Consulte el directorio de modelos actual o el catálogo en vivo el día de publicación, porque la disponibilidad de la ruta de video puede cambiar más rápido que una guía de configuración estática.
Step 1: crear y almacenar la clave API de Flatkey
En la consola de Flatkey, cree una clave API y guárdela como una variable de entorno.
export FLATKEY_API_KEY="sk-fk-..."
Este es el primer lugar donde los equipos crean fricción evitable. Mantenga la clave del lado del servidor, no en código del navegador ni en una nota local compartida. Si la evaluación es para un equipo de producto en lugar de un solo ingeniero, use desde el inicio un secreto propiedad del equipo.
Step 2: ejecute la prueba mínima de humo del router
La guía rápida actual de Flatkey usa POST /v1/chat/completions para la primera solicitud. Esa es la decisión correcta incluso si su objetivo final es la generación de video con Seedance, porque verifica la capa de acceso compartida antes de añadir complejidad de flujo de trabajo asíncrono.
curl https://router.flatkey.ai/v1/chat/completions -H "Authorization: Bearer $FLATKEY_API_KEY" -H "Content-Type: application/json" -d '{
"model": "gpt-4o-mini",
"messages": [
{"role": "user", "content": "Reply with the word connected."}
]
}'
Una respuesta correcta le indica de inmediato cinco cosas útiles:
- la clave API es válida
- el encabezado
Authorization: Bearer ...es correcto - la URL base es correcta
- su cliente puede hacer POST de JSON correctamente
- la solicitud debería aparecer en los registros de uso de Flatkey con recuentos de tokens y coste
Esa es la prueba verificable más pequeña de que la capa de acceso funciona.
Step 3: entender qué está comprobando realmente la solicitud de prueba de humo
La prueba de humo de chat completions es intencionadamente simple. La estructura requerida es:
| Campo de la solicitud | Por qué importa |
|---|---|
Authorization header |
Confirma el formato del token Bearer |
Content-Type: application/json |
Confirma que el cuerpo de la solicitud se analiza correctamente |
model |
Confirma que la ruta puede resolver un ID de modelo |
messages |
Confirma que el cuerpo coincide con el esquema compatible con OpenAI |
La documentación actual de chat completions de Flatkey también destaca los tres campos de respuesta que los equipos de producto suelen revisar primero:
choices[0].message.contentmodelusage
Ese último campo es especialmente útil para la incorporación, porque ofrece a los equipos de producto y operaciones un lugar compartido para verificar que la solicitud realmente pasó por el router.
Step 4: sustituir el modelo de marcador de posición por la evaluación de Seedance
Una vez que la prueba de humo pase, mantenga la misma credencial y la misma URL base del router, y luego cambie solo las partes específicas de su flujo de trabajo de video.
Mantenga sin cambios estas partes:
Authorization: Bearer $FLATKEY_API_KEYhttps://router.flatkey.ai/v1- su manejo de secretos del lado del servidor
- su ruta de revisión de registros y facturación
Cambie ahora estas partes:
| Qué cambia después de la prueba de humo | Por qué cambia |
|---|---|
model |
Reemplazas el texto de marcador de posición del modelo por el ID aprobado del modelo Seedance |
| Forma del cuerpo de la solicitud | La generación de video necesita sus propios campos de payload, no solo un array de messages de chat |
| Manejo de la respuesta | Los flujos de trabajo de video devuelven estado del trabajo, recursos o estado asincrónico en lugar de solo texto inmediato |
| Lógica del producto | Necesitas polling o un webhook en lugar de tratar la llamada como chat síncrono |
Para una evaluación de producto de texto a video, el marcador de posición seguro para el día de publicación es:
seedance-2.5
Para una evaluación de imagen a video, la ruta pública actual es:
seedance-2.0-i2v
Usa esos nombres como punto de partida para el descubrimiento, no como una promesa de que cada flujo de trabajo posterior comparte una única forma de payload idéntica.
Paso 5: diseña en torno al flujo de trabajo asincrónico de video de Seedance
Este es el paso que la mayoría de los quickstarts omiten.
La página pública de la API de Seedance todavía describe el flujo de trabajo como:
- creación de tareas asincrónicas
- sondeo de estado
- webhooks
- créditos basados en uso
Eso significa que un equipo de producción debe asumir que la ruta real de video necesita al menos cuatro estados en su propia app:
| Estado del trabajo | Qué debería hacer tu app |
|---|---|
queued |
Registrar el trabajo y mostrar que la solicitud fue aceptada |
running |
Consultar el estado o esperar un webhook |
succeeded |
Recuperar el recurso de salida y adjuntar metadatos |
failed |
Guardar el error y decidir si reintentar |
Si tu equipo intenta tratar Seedance como una respuesta de chat síncrona, la integración se sentirá inestable incluso cuando la API se esté comportando con normalidad.
Una secuencia práctica de incorporación para equipos de producto
Si quieres el ciclo de evaluación más pequeño posible, usa este orden:
- Crea la clave Flatkey.
- Ejecuta la prueba de humo de
chat/completions. - Verifica que la solicitud aparezca en los registros de uso.
- Elige el ID del modelo Seedance actual que realmente quieres probar.
- Implementa el flujo de solicitud asincrónico específico de Seedance.
- Añade una ruta de polling o una ruta de webhook antes de ampliar el despliegue.
Esto reduce el riesgo de incorporación porque separas la verificación del router de la implementación del flujo de trabajo de video.
Solución de problemas
401 o 403 en la primera solicitud cURL
Normalmente significa que la clave no es válida, ha caducado o no se está pasando como token Bearer.
Comprueba:
- la clave comienza con
sk-fk- - la variable del shell realmente está configurada
- el encabezado es
Authorization: Bearer ...
404 o desajuste de ruta
Normalmente significa que tu app apunta a la URL equivocada.
Usa:
https://router.flatkey.ai/v1
No apuntes la solicitud al sitio de marketing ni elimines el sufijo /v1.
La solicitud se realiza correctamente, pero los registros de uso permanecen vacíos
La guía de inicio rápido de Flatkey dice explícitamente que hay que esperar unos segundos y buscar de nuevo. Si los logs siguen sin aparecer, vuelve a comprobar el nombre del modelo, la API key y la base URL que realmente enviaste.
La prueba de humo funciona, pero el flujo de trabajo de Seedance no
Eso normalmente significa que la capa de acceso está bien y que el problema está ahora en uno de estos lugares:
- ID de modelo Seedance incorrecto
- forma incorrecta del payload de video
- falta lógica de sondeo asíncrono
- la gestión de webhooks aún no está implementada
- el código del producto asume una respuesta de texto síncrona
Eso es progreso, no un fracaso. Ya has aislado el problema de la autenticación y del enrutamiento.
Cuándo este inicio rápido es suficiente
Este inicio rápido es suficiente cuando tu equipo necesita responder:
- ¿Podemos autenticarnos a través de Flatkey?
- ¿Podemos reutilizar nuestro camino de cliente compatible con OpenAI?
- ¿Pueden producto y operaciones ver la solicitud en los logs?
- ¿Podemos cambiar de una prueba de humo de texto a una ruta de Seedance sin añadir primero otra clave de proveedor?
Si la respuesta a esas cuatro preguntas es sí, el siguiente paso de aprobación suele centrarse en el flujo de trabajo asíncrono de video y el modelo de costes, no en la conectividad básica.
Si necesitas la parte de precios antes del despliegue, revisa a continuación la página de precios en vivo de Flatkey para que el equipo pueda aprobar la evaluación con la misma superficie de facturación que usará en producción.
FAQ
¿Cuál es la forma más rápida de probar el acceso a la API de Seedance a través de Flatkey?
Empieza con la prueba de humo actual de Flatkey POST /v1/chat/completions para verificar la autenticación, la base URL y los Usage Logs. Una vez que eso funcione, sustituye el modelo de marcador de posición por el ID del modelo Seedance actualmente aprobado y construye el flujo de trabajo asíncrono de video.
¿La primera solicitud cURL genera un video?
No. La primera solicitud cURL es una comprobación de conectividad para el router compartido. Demuestra que tu clave, encabezados, base URL y logs funcionan antes de que añadas la gestión específica de solicitudes de video.
¿Con qué modelo de Seedance debería empezar un equipo de texto a video?
A fecha de viernes, 17 de julio de 2026, el catálogo público de modelos de Flatkey enumera seedance-2.5 para texto a video e imagen a video. Vuelve a comprobar el directorio de modelos actual antes de fijarlo en el código del producto.
¿Con qué modelo de Seedance debería empezar un equipo de imagen a video?
A fecha de viernes, 17 de julio de 2026, el catálogo público de Flatkey enumera seedance-2.0-i2v para imagen a video.
¿Por qué el flujo de incorporación comienza con chat completions en lugar de con un trabajo de video?
Porque la solicitud de chat completions es la prueba más pequeña posible de que tu ruta de enrutamiento compatible con OpenAI funciona. Separa los problemas de autenticación y registro de los problemas del pipeline de video.
¿Qué debo inspeccionar en la primera respuesta exitosa?
Inspecciona model, choices[0].message.content y usage, y luego confirma que la misma solicitud aparece en Usage Logs.
¿Qué cambia cuando paso de la prueba de humo a una evaluación real de Seedance?
La clave y la base URL siguen siendo las mismas. Cambian el ID del modelo, el cuerpo de la solicitud y la gestión del trabajo asíncrono.
