URL base estável compatível com OpenAI para equipas de produto da Seedance API

Mover um produto de texto para vídeo de uma configuração de fornecedor para outra não deve exigir reescrever todos os auxiliares de autenticação, variáveis de ambiente, regras de retry e hooks de observabilidade. O padrão mais seguro é separar as partes da integração que podem permanecer estáveis das partes específicas da geração de vídeo.

Para equipas que já usam um cliente ao estilo OpenAI, a Flatkey oferece um ponto de partida prático: crie uma chave de API, defina a URL base do cliente para https://router.flatkey.ai/v1, execute um pequeno pedido compatível e confirme o pedido nos Logs de Utilização. Isso comprova a camada de ligação partilhada antes de ligar um fluxo de trabalho de vídeo assíncrono específico da Seedance.

Este guia mostra como tornar essa migração controlada, reversível e fácil de inspecionar.

Resposta rápida

Uma URL base estável compatível com OpenAI pode reduzir o trabalho de migração nas partes partilhadas de uma integração de IA:

• injeção da chave de API
• configuração do ambiente
• inicialização do cliente
• correlação de pedidos
• política de retry e timeout
• monitorização de utilização e custos

Isso não significa que todos os fornecedores de texto para vídeo usem o mesmo corpo de pedido ou o mesmo endpoint. A geração de vídeo normalmente precisa de um fluxo assíncrono separado: criar um job, guardar o ID do job, fazer polling ou receber um webhook e obter o ativo final.

O objetivo de implementação, portanto, não é “forçar a Seedance através de uma estrutura de chat-completions”. É “manter a ligação do gateway estável e, depois, isolar o adaptador do job específico de vídeo atrás de uma interface pequena”.

Porque é que a estabilidade da URL base é importante para produtos de texto para vídeo

As migrações de fornecedor normalmente falham nas ligações em torno da chamada do modelo, e não na única linha que referencia um modelo. Uma aplicação em produção pode ter chaves de API num gestor de segredos, clientes HTTP em vários serviços, workers de fila, handlers de webhooks, registos de auditoria, alertas de despesa e definições de rollback.

Se cada fornecedor estiver diretamente ligado a todas essas camadas, adicionar um novo modelo de vídeo torna-se uma ampla alteração de infraestrutura. Um boundary de gateway estável limita o raio de impacto.

O resultado é uma superfície de migração menor. O código do produto continua a depender de uma interface interna estável enquanto o adaptador lida com as diferenças nas APIs de vídeo.

Sequência de migração mais segura

Use duas verificações separadas em vez de tentar validar todo o caminho de vídeo num único pedido.

1. Teste rápido de conexão: verifique a autenticação, a URL base compatível com OpenAI, o acesso à rede e os Registos de Utilização.
2. Teste do fluxo de trabalho de vídeo: verifique a rota atual do Seedance, os parâmetros aceites, as transições assíncronas de estado, a entrega de ativos e o comportamento de faturação.

Esta separação torna as falhas mais fáceis de classificar. Se o teste rápido falhar, o problema provavelmente está nas credenciais, na configuração da URL base, na rede ou no tratamento partilhado dos pedidos. Se o teste rápido passar mas o job de vídeo falhar, concentre-se na rota do modelo e no adaptador de vídeo.

Step 1: move the base URL into configuration

Não codifique uma URL do fornecedor na lógica da aplicação. Coloque a ligação ao gateway em variáveis de ambiente para que a implementação e o rollback não exijam alterações ao 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

Trate o valor do modelo de vídeo como uma definição em tempo de implementação. Os aliases de modelo e as capacidades suportadas podem mudar, por isso confirme a rota atual no Flatkey antes da implementação, em vez de copiar um identificador antigo de uma publicação de blogue.

Step 2: initialize the existing OpenAI-style client once

Se a sua aplicação já usa o SDK Python da OpenAI, a alteração na ligação partilhada é intencionalmente pequena.

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

A configuração equivalente em TypeScript mantém a mesma fronteira:

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

A decisão de design importante é que os serviços importem um cliente configurado em vez de construírem os seus próprios clientes específicos de fornecedor ao longo da base de código.

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

O quickstart da Flatkey usa um pedido de chat-completions compatível com OpenAI e depois pede-lhe que verifique a chamada nos Registos de Utilização. Use esse pequeno teste para provar a camada de integração partilhada.

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

Este pedido não testa a geração de vídeo do Seedance. Verifica quatro pré-requisitos de que ambos os fluxos dependem:

• a chave está presente e foi aceite
• a URL base está correta
• a aplicação consegue الوصول ao router
• o pedido aparece no painel com dados de utilização

Para um walkthrough detalhado da primeira requisição, use o guia de início rápido da Seedance API para equipas de produto.

Step 4: manter a Seedance atrás de um adaptador de vídeo assíncrono

A geração de texto para vídeo normalmente demora mais do que um pedido API síncrono normal. O fluxo público da Seedance API descreve a criação de tarefas seguida de verificações de estado ou entrega por webhook. Modele esse ciclo de vida explicitamente.

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

O adaptador deve traduzir os campos internos estáveis do seu produto para o payload exigido pelo endpoint de vídeo atual. Mantenha os parâmetros específicos do fornecedor dentro desse adaptador, em vez de os expor em controllers, código da UI ou esquemas de fila.

Não assuma que o endpoint de vídeo é /chat/completions, e não assuma que uma resposta de chat prova que a rota Seedance selecionada está disponível. Confirme o endpoint atual, o alias do modelo, os parâmetros e os valores de estado na documentação do produto ou no dashboard no momento da implementação.

Step 5: tornar o polling seguro e limitado

Um worker de vídeo precisa de regras de fiabilidade diferentes de um pedido de chat. Fazer polling para sempre não é uma estratégia 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"Video job {job_id} exceeded its processing deadline")

O polling em produção também deve respeitar a orientação do fornecedor e qualquer cabeçalho Retry-After. Guarde o ID externo da tarefa antes de fazer polling para que um reinício do worker não crie um vídeo duplicado.

Se houver webhooks disponíveis, verifique assinaturas, confirme rapidamente o recebimento e torne o handler idempotente. Um webhook pode ser entregue mais do que uma vez ou chegar depois de um worker de polling já ter concluído a tarefa.

Step 6: adicionar observabilidade em ambas as camadas

Monitorize o pedido do gateway e a tarefa de vídeo ao nível do produto separadamente.

Gateway fields

• environment and service name
• internal request ID
• route or model alias
• HTTP status
• latency
• retry count
• usage or cost data visible in the dashboard

Video job fields

• external job ID
• user or workspace ID
• prompt version, without logging sensitive prompt content by default
• model and capability mode
• queue, start, and completion timestamps
• terminal state and normalized error code
• output asset location and retention policy

O painel é o ponto de controlo operacional partilhado. Depois do teste de smoke e do primeiro trabalho de vídeo controlado, compare os registos da aplicação com os registos de utilização do Flatkey. Investigue registos em falta, trabalhos duplicados, nomes de modelo inesperados ou alterações de custo antes de aumentar o tráfego.

Passo 7: use um plano de implementação reversível

Mudar um único URL base é simples. Fazer a implementação em segurança ainda requer controlos.

1. Execute o teste de smoke a partir de um ambiente de desenvolvimento.
2. Execute um trabalho de avaliação do Seedance não sensível.
3. Confirme o tratamento do estado do trabalho, a recuperação de ativos e a visibilidade da utilização.
4. Ative a rota para uma conta interna ou para uma pequena percentagem do tráfego.
5. Compare a taxa de sucesso, a latência de ponta a ponta e o custo por ativo concluído.
6. Aumente o tráfego apenas depois de a margem de erro continuar aceitável.
7. Mantenha a configuração do fornecedor anterior disponível até os critérios de reversão expirarem.

Defina os gatilhos de reversão antes do lançamento. Os exemplos incluem erros de autenticação repetidos, uma taxa elevada de trabalhos falhados, trabalhos presos para além do prazo de processamento, registos de utilização em falta ou falhas na recuperação da saída.

Lista de verificação de migração

Erros comuns de migração

Tratar a compatibilidade com OpenAI como compatibilidade universal de endpoint

Um cliente compatível com OpenAI pode simplificar a autenticação e as famílias de pedidos suportadas. Isso não garante que todas as operações multimodais ou de vídeo tenham o mesmo esquema. Mantenha o adaptador de vídeo explícito.

Alterar a chave, o URL base, o modelo e a lógica do worker numa única versão

Isso dificulta isolar falhas. Comprove primeiro a ligação ao gateway e só depois altere o caminho do vídeo.

Tentar novamente a criação do trabalho sem uma estratégia de idempotência

Um timeout de rede pode ocorrer depois de o fornecedor ter aceite o trabalho. Criar cegamente outro trabalho pode produzir e faturar um ativo duplicado.

Usar o timeout do pedido HTTP como prazo limite do vídeo

O pedido de criação do trabalho e o ciclo de vida do processamento de vídeo são temporizadores diferentes. Mantenha o primeiro pedido curto e depois acompanhe o prazo assíncrono no estado durável do trabalho.

Ignorar a verificação do painel

Uma resposta de aplicação bem-sucedida não é a verificação operacional completa. Confirme se as informações de uso, modelo, latência e custo aparecem onde a equipa espera monitorizá-las.

FAQ

Posso integrar a Seedance alterando apenas a URL base da OpenAI?

Alterar a URL base pode simplificar a camada de ligação partilhada para pedidos compatíveis com OpenAI suportados. A geração de vídeo da Seedance ainda pode exigir um endpoint assíncrono dedicado e parâmetros específicos do fornecedor. Verifique a rota atual antes da implementação.

O que deve permanecer inalterado durante a migração?

Mantenha estáveis a injeção de segredos, a nomenclatura dos ambientes, os IDs de correlação, o logging, os alertas e a interface de vídeo voltada para o produto. Limite as alterações específicas do fornecedor à configuração e ao adaptador de vídeo.

Por que executar um smoke test de chat para um produto de vídeo?

O smoke test isola rapidamente a autenticação do gateway, a URL base, a rede e os Usage Logs do fluxo de trabalho de vídeo mais longo. É um teste de conexão, não um teste de capacidade de vídeo.

Devo fazer polling ou usar webhooks para a conclusão do vídeo?

Use o mecanismo suportado pela API de vídeo atual e pela sua infraestrutura. O polling é mais simples, mas deve ter limites e backoff. Os webhooks reduzem o polling, mas exigem verificação de assinatura, idempotência e reconciliação para eventos perdidos.

Como evito jobs de vídeo duplicados?

Crie e persista uma chave de idempotência para o pedido do produto, guarde imediatamente o ID do job externo e faça com que as novas tentativas retomem o job existente sempre que possível.

Onde devo comparar o custo antes da implementação em produção?

Revise a atual página de preços da Flatkey e depois compare o custo por vídeo concluído em vez de considerar apenas o preço por pedido ou por segundo. Inclua jobs com falha e duplicados no cálculo.

Construa primeiro a fronteira estável

A migração mais rápida não é a que altera menos linhas no primeiro dia. É a que reduz futuras mudanças de fornecedor para uma atualização controlada de configuração e um pequeno adaptador.

Comece com uma chave da Flatkey, mova o cliente partilhado para a URL base estável, verifique a conexão em Usage Logs e, em seguida, teste o fluxo de trabalho atual da Seedance como um sistema de jobs assíncronos. Quando as verificações passarem, obtenha uma chave e faça a implementação progressiva com métricas explícitas e gatilhos de rollback.