URL de base OpenAI-compatible stable pour les équipes produit de l’API Seedance

Faire passer un produit de text-to-video d’une configuration de fournisseur à une autre ne devrait pas nécessiter de réécrire chaque aide d’authentification, variable d’environnement, règle de retry et hook d’observabilité. Le schéma le plus sûr consiste à séparer les parties de votre intégration qui peuvent rester stables de celles qui sont spécifiques à la génération vidéo.

Pour les équipes qui utilisent déjà un client de style OpenAI, Flatkey offre un point de départ pratique : créez une clé API, définissez l’URL de base du client sur https://router.flatkey.ai/v1, exécutez une petite requête compatible, puis confirmez la requête dans les journaux d’utilisation. Cela prouve la couche de connexion partagée avant que vous n’ajoutiez un workflow vidéo asynchrone spécifique à Seedance.

Ce guide montre comment rendre cette migration contrôlée, réversible et facile à inspecter.

Réponse rapide

Une URL de base OpenAI-compatible stable peut réduire le travail de migration pour les parties partagées d’une intégration d’IA :

• injection de la clé API
• configuration de l’environnement
• initialisation du client
• corrélation des requêtes
• politique de retry et de timeout
• surveillance de l’utilisation et des coûts

Cela ne signifie pas que chaque fournisseur de text-to-video utilise le même corps de requête ou le même endpoint. La génération vidéo nécessite généralement un flux asynchrone séparé : créer une tâche, stocker l’ID de tâche, interroger régulièrement ou recevoir un webhook, puis récupérer l’asset final.

L’objectif d’implémentation n’est donc pas de « forcer Seedance à passer par une forme de chat-completions ». C’est de « garder la connexion du gateway stable, puis d’isoler l’adaptateur de tâche spécifique à la vidéo derrière une petite interface ».

Pourquoi la stabilité de l’URL de base est importante pour les produits text-to-video

Les migrations de fournisseurs échouent généralement dans les interfaces autour de l’appel au modèle, et non dans la seule ligne qui nomme un modèle. Une application de production peut avoir des clés API dans un gestionnaire de secrets, des clients HTTP dans plusieurs services, des workers de file d’attente, des handlers de webhook, des journaux d’audit, des alertes de dépenses et des paramètres de rollback.

Si chaque fournisseur est branché directement sur toutes ces couches, l’ajout d’un nouveau modèle vidéo devient un changement d’infrastructure de grande ampleur. Une frontière de gateway stable limite le rayon d’impact.

Le résultat est une surface de migration plus réduite. Le code de votre produit continue de dépendre d’une interface interne stable tandis que l’adaptateur gère les différences entre les API vidéo.

La séquence de migration la plus sûre

Utilisez deux vérifications distinctes au lieu d’essayer de valider tout le chemin vidéo en une seule requête.

1. Test de fumée de connexion : vérifiez l’authentification, l’URL de base compatible OpenAI, l’accès réseau et les journaux d’utilisation.
2. Test du workflow vidéo : vérifiez la route Seedance actuelle, les paramètres acceptés, les transitions d’état asynchrones, la livraison des assets et le comportement de facturation.

Cette séparation facilite la classification des échecs. Si le test de fumée échoue, le problème se situe probablement dans les identifiants, la configuration de l’URL de base, le réseau ou le traitement partagé des requêtes. Si le test de fumée passe mais que le job vidéo échoue, concentrez-vous sur la route du modèle et l’adaptateur vidéo.

Step 1: move the base URL into configuration

Ne codez pas en dur l’URL d’un fournisseur dans la logique applicative. Placez la connexion au gateway dans des variables d’environnement afin que le déploiement et le rollback ne nécessitent pas de modifications du code.

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

Traitez la valeur du modèle vidéo comme un paramètre défini au moment du déploiement. Les alias de modèles et les capacités prises en charge peuvent changer ; confirmez donc la route actuelle dans Flatkey avant le déploiement plutôt que de copier un ancien identifiant depuis un article de blog.

Step 2: initialize the existing OpenAI-style client once

Si votre application utilise déjà le SDK Python OpenAI, le changement de connexion partagée est volontairement réduit.

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 configuration TypeScript équivalente conserve la même frontière :

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",
});

Le choix de conception important est que les services importent un client configuré au lieu de construire leurs propres clients spécifiques au fournisseur dans toute la base de code.

Step 3: run a connection smoke test before touching video jobs

Le guide de démarrage rapide de Flatkey utilise une requête de chat-completions compatible OpenAI, puis vous demande de vérifier l’appel dans les journaux d’utilisation. Utilisez ce petit test pour valider la couche d’intégration partagée.

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,
    }

Cette requête ne teste pas la génération vidéo Seedance. Elle vérifie quatre prérequis dont dépendent les deux workflows :

• la clé est présente et acceptée
• l’URL de base est correcte
• l’application peut atteindre le routeur
• la requête apparaît dans le tableau de bord avec les données d’utilisation

Pour un guide détaillé du premier appel, utilisez le guide de démarrage rapide de l’API Seedance pour les équipes produit.

Étape 4 : garder Seedance derrière un adaptateur vidéo asynchrone

La génération texte-vidéo prend généralement plus de temps qu’une requête API synchrone normale. Le flux public de l’API Seedance décrit la création de tâche, suivie de vérifications de statut ou d’une livraison par webhook. Modélisez explicitement ce cycle de vie.

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>;
}

L’adaptateur doit traduire les champs internes stables de votre produit vers la charge utile requise par le point de terminaison vidéo actuel. Conservez les paramètres propres au fournisseur à l’intérieur de cet adaptateur plutôt que de les laisser fuiter dans les contrôleurs, le code UI ou les schémas de file d’attente.

N’assumez pas que le point de terminaison vidéo est /chat/completions, et n’assumez pas non plus qu’une réponse de chat prouve que la route Seedance sélectionnée est disponible. Vérifiez le point de terminaison actuel, l’alias de modèle, les paramètres et les valeurs de statut dans la documentation produit ou le tableau de bord au moment de l’implémentation.

Étape 5 : rendre le polling sûr et borné

Un worker vidéo a besoin de règles de fiabilité différentes de celles d’une requête de chat. Faire du polling indéfiniment n’est pas une stratégie de retry.

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"La tâche vidéo {job_id} a dépassé son délai de traitement")

Le polling en production doit également respecter les indications du fournisseur et tout en-tête Retry-After. Enregistrez l’ID externe de la tâche avant de lancer le polling afin qu’un redémarrage du worker ne crée pas une vidéo en double.

Si des webhooks sont disponibles, vérifiez les signatures, accusez réception rapidement et rendez le gestionnaire idempotent. Un webhook peut être livré plusieurs fois ou arriver après qu’un worker de polling a déjà terminé la tâche.

Étape 6 : ajouter de l’observabilité aux deux niveaux

Surveillez séparément la requête passerelle et la tâche vidéo au niveau produit.

Champs de la passerelle

• environnement et nom du service
• ID de requête interne
• route ou alias de modèle
• statut HTTP
• latence
• nombre de retries
• données d’usage ou de coût visibles dans le tableau de bord

Champs de la tâche vidéo

• ID de tâche externe
• ID utilisateur ou espace de travail
• version du prompt, sans journaliser par défaut le contenu sensible du prompt
• modèle et mode de capacité
• horodatages de mise en file d’attente, de début et de fin
• état terminal et code d’erreur normalisé
• emplacement de l’artefact de sortie et politique de rétention

Le tableau de bord est le point de contrôle opérationnel partagé. Après le test de fumée et la première tâche vidéo contrôlée, comparez les journaux d’application avec les enregistrements d’utilisation Flatkey. Étudiez les enregistrements manquants, les tâches en double, les noms de modèle inattendus ou les changements de coût avant d’augmenter le trafic.

Étape 7 : utiliser un plan de déploiement réversible

Modifier une seule URL de base est simple. Un déploiement sécurisé nécessite néanmoins des contrôles.

1. Exécutez le test de fumée depuis un environnement de développement.
2. Exécutez une tâche d’évaluation Seedance non sensible.
3. Confirmez le traitement du statut de la tâche, la récupération des ressources et la visibilité de l’utilisation.
4. Activez la route pour un compte interne ou un petit pourcentage du trafic.
5. Comparez le taux de réussite, la latence de bout en bout et le coût par ressource terminée.
6. N’augmentez le trafic qu’une fois que le budget d’erreur reste acceptable.
7. Conservez la configuration du fournisseur précédent disponible jusqu’à l’expiration des critères de retour arrière.

Définissez les déclencheurs de retour arrière avant le lancement. Les exemples incluent des erreurs d’authentification répétées, un taux de tâches échouées élevé, des tâches bloquées au-delà du délai de traitement, des enregistrements d’utilisation manquants ou des échecs de récupération des sorties.

Liste de contrôle de migration

Erreurs courantes de migration

Traiter la compatibilité OpenAI comme une compatibilité universelle des points de terminaison

Un client compatible OpenAI peut simplifier l’authentification et les familles de requêtes prises en charge. Cela ne garantit pas que chaque opération multimodale ou vidéo possède le même schéma. Gardez l’adaptateur vidéo explicite.

Modifier la clé, l’URL de base, le modèle et la logique du worker dans une seule version

Cela rend les échecs difficiles à isoler. Prouvez d’abord la connexion à la passerelle, puis modifiez le chemin vidéo.

Réessayer la création de tâche sans stratégie d’idempotence

Un délai d’attente réseau peut survenir après que le fournisseur a accepté la tâche. Créer aveuglément une autre tâche peut produire et facturer une ressource en double.

Utiliser le délai d’attente de la requête HTTP comme délai limite de la vidéo

La requête de création de tâche et le cycle de vie de traitement vidéo sont deux minuteries différentes. Gardez la première requête courte, puis suivez le délai asynchrone dans l’état durable de la tâche.

Ignorer la vérification du tableau de bord

Une réponse d’application réussie ne constitue pas à elle seule une vérification opérationnelle complète. Confirmez que les informations d’utilisation, de modèle, de latence et de coût apparaissent là où l’équipe s’attend à les surveiller.

FAQ

Puis-je intégrer Seedance en changeant uniquement l’URL de base OpenAI ?

Modifier l’URL de base peut simplifier la couche de connexion partagée pour les requêtes compatibles OpenAI prises en charge. La génération vidéo Seedance peut toutefois nécessiter un point de terminaison asynchrone dédié et des paramètres spécifiques au fournisseur. Vérifiez la route actuelle avant l’implémentation.

Qu’est-ce qui doit rester inchangé pendant la migration ?

Conservez l’injection des secrets, le nommage des environnements, les IDs de corrélation, la journalisation, les alertes et l’interface vidéo destinée au produit stables. Limitez les changements spécifiques au fournisseur à la configuration et à l’adaptateur vidéo.

Pourquoi exécuter un test de fumée chat pour un produit vidéo ?

Le test de fumée isole rapidement l’authentification du gateway, l’URL de base, le réseau et les journaux d’utilisation (Usage Logs) du flux vidéo plus long. C’est un test de connexion, pas un test des capacités vidéo.

Dois-je sonder en boucle ou utiliser des webhooks pour la fin de vidéo ?

Utilisez le mécanisme pris en charge par l’API vidéo actuelle et votre infrastructure. Le polling est plus simple mais doit être borné et faire l’objet d’un backoff. Les webhooks réduisent le polling mais nécessitent la vérification de signature, l’idempotence et la réconciliation des événements manqués.

Comment éviter les doublons de tâches vidéo ?

Créez et conservez une clé d’idempotence pour la requête produit, stockez immédiatement l’ID de tâche externe et faites en sorte que les relances reprennent la tâche existante chaque fois que possible.

Où dois-je comparer les coûts avant le déploiement ?

Consultez la page de tarification Flatkey actuelle, puis comparez le coût par vidéo terminée plutôt que seulement le prix par requête ou par seconde. Incluez les tâches échouées et dupliquées dans le calcul.

Construisez d’abord une frontière stable

La migration la plus rapide n’est pas celle où l’on modifie le moins de lignes dès le premier jour. C’est celle qui réduit les futurs changements de fournisseur à une mise à jour de configuration contrôlée et à un petit adaptateur.

Commencez avec une clé Flatkey, faites passer le client partagé vers l’URL de base stable, vérifiez la connexion dans les Usage Logs, puis testez le flux de travail Seedance actuel en tant que système de tâches asynchrones. Une fois les vérifications passées, obtenez une clé et déployez avec des métriques explicites et des déclencheurs de retour arrière.