面向 Seedance API 产品团队的稳定 OpenAI 兼容基础 URL

将一个文本生成视频产品从一个提供商配置迁移到另一个提供商配置，不应要求重写每一个身份验证辅助函数、环境变量、重试规则和可观测性挂钩。更安全的做法是，将集成中可以保持稳定的部分，与视频生成特有的部分分离开来。

对于已经在使用 OpenAI 风格客户端的团队，Flatkey 提供了一个实用的起点：创建一个 API 密钥，将客户端基础 URL 设置为 https://router.flatkey.ai/v1，运行一个小的兼容请求，并在 Usage Logs 中确认该请求。这可以在你接入 Seedance 特定的异步视频工作流之前，证明共享连接层是可用的。

本指南将展示如何让这次迁移保持可控、可回滚且便于检查。

快速答案

一个稳定的 OpenAI 兼容基础 URL可以减少 AI 集成共享部分的迁移工作：

• API 密钥注入
• 环境配置
• 客户端初始化
• 请求关联
• 重试和超时策略
• 使用量和成本监控

这并不意味着每个文本生成视频提供商都使用相同的请求体或相同的端点。视频生成通常需要单独的异步流程：创建任务、存储任务 ID、轮询或接收 webhook，并获取最终资源。

因此，实现目标不是“强行把 Seedance 变成聊天补全的结构”，而是“保持网关连接稳定，然后把视频相关的任务适配器隔离在一个小接口后面”。

为什么基础 URL 的稳定性对文本生成视频产品很重要

提供商迁移通常失败在模型调用周边的接缝处，而不是失败在那一行只负责命名模型的代码上。生产应用可能在 secrets manager 中保存 API 密钥，在多个服务中使用 HTTP 客户端，还有队列 worker、webhook 处理器、审计日志、支出告警和回滚设置。

如果每个提供商都直接接入这些层，那么新增一个视频模型就会变成一次大规模的基础设施变更。一个稳定的网关边界可以限制影响范围。

结果是更小的迁移面。你的产品代码继续依赖稳定的内部接口，而适配器负责处理视频 API 的差异。

最安全的迁移顺序

使用两项单独的检查，而不是试图在一次请求中验证整条视频路径。

1. 连接冒烟测试：验证身份验证、OpenAI 兼容基础 URL、网络访问以及 Usage Logs。
2. 视频工作流测试：验证当前的 Seedance 路由、可接受参数、异步状态转换、资源交付以及计费行为。

这种分离使故障更容易分类。如果冒烟测试失败，问题很可能出在凭据、基础 URL 配置、网络连接或共享请求处理上。如果冒烟测试通过但视频任务失败，则应重点检查模型路由和视频适配器。

Step 1: move the base URL into configuration

不要在应用逻辑中硬编码提供方 URL。将网关连接放入环境变量中，这样部署和回滚就不需要修改代码。

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

将视频模型值视为部署时配置。模型别名和支持的能力可能会变化，因此在上线前请在 Flatkey 中确认当前路由，而不是从博客文章中复制旧标识符。

Step 2: initialize the existing OpenAI-style client once

如果你的应用已经在使用 OpenAI Python SDK，那么共享连接变更是刻意保持很小的。

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

对应的 TypeScript 配置保持相同的边界：

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

重要的设计选择是，服务导入的是一个已配置好的客户端，而不是在整个代码库中各自构造供应商专属客户端。

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

Flatkey 的快速入门使用 OpenAI 兼容的 chat-completions 请求，然后让你在 Usage Logs 中验证该调用。使用这个小测试来证明共享集成层是否正常。

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

此请求不会测试 Seedance 视频生成。它验证的是两个工作流都依赖的四个前提条件：

• 密钥存在且已被接受
• 基础 URL 正确
• 应用可以连通路由器
• 请求会在控制台中显示，并包含用量数据

有关详细的首次请求演练，请使用 面向产品团队的 Seedance API 快速入门。

步骤 4：将 Seedance 放在异步视频适配器后面

文本转视频生成通常比普通的同步 API 请求耗时更长。公开的 Seedance API 流程描述了先创建任务，然后进行状态检查或通过 webhook 交付。请显式地建模这一生命周期。

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

适配器应将你产品中稳定的内部字段转换为当前视频端点所需的有效载荷。将仅提供方可用的参数保留在该适配器内部，而不是泄露到控制器、UI 代码或队列 schema 中。

不要假设视频端点是 /chat/completions，也不要假设某个聊天响应就能证明所选的 Seedance 路由可用。实现时，请在产品文档或仪表板中确认当前端点、模型别名、参数和值状态。

步骤 5：让轮询安全且有边界

视频工作器需要与聊天请求不同的可靠性规则。无休止轮询并不是重试策略。

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

生产环境中的轮询还应遵循提供方指导以及任何 Retry-After 标头。开始轮询前先保存外部任务 ID，这样工作器重启时就不会创建重复的视频。

如果支持 webhook，请验证签名、快速确认，并使处理程序具备幂等性。一个 webhook 可能会被投递多次，或者在轮询工作器已经完成任务后才到达。

步骤 6：在两个层面添加可观测性

分别监控网关请求和产品层级的视频任务。

网关字段

• 环境和服务名称
• 内部请求 ID
• 路由或模型别名
• HTTP 状态
• 延迟
• 重试次数
• 仪表板中可见的用量或成本数据

视频任务字段

• 外部任务 ID
• 用户或工作区 ID
• 提示词版本，默认情况下不要记录敏感的提示词内容
• 模型和能力模式
• 排队、开始和完成时间戳
• 终态和规范化错误代码
• 输出资源位置和保留策略

仪表板是共享的运营检查点。在烟雾测试和第一次受控视频任务之后，将应用程序日志与 Flatkey 使用记录进行比对。在扩展流量之前，先调查缺失记录、重复任务、意外的模型名称或成本变化。

Step 7: use a reversible rollout plan

更改一个基础 URL 很简单。安全地逐步上线仍然需要控制措施。

1. 从开发环境运行烟雾测试。
2. 运行一个非敏感的 Seedance 评估任务。
3. 确认任务状态处理、资产检索和用量可见性。
4. 为内部账户或一小部分流量启用该路由。
5. 比较成功率、端到端延迟以及每个已完成资产的成本。
6. 只有在错误预算仍然可接受之后，才增加流量。
7. 在回滚条件失效之前，保留之前的提供商配置可用。

在上线前定义回滚触发条件。示例包括重复的身份验证错误、升高的失败任务率、超过处理截止时间仍停留的任务、缺失的用量记录或输出检索失败。

迁移检查清单

常见迁移错误

Treating OpenAI compatibility as universal endpoint compatibility

兼容 OpenAI 的客户端可以简化身份验证和受支持的请求类型。它并不能保证每一种多模态或视频操作都具有相同的 schema。请保持视频适配器的显式性。

在一个版本中同时更改密钥、基础 URL、模型和工作器逻辑

这会让故障难以隔离。先证明网关连接正常，然后再更改视频路径。

在没有幂等策略的情况下重试任务创建

在提供商已接受任务之后，网络超时也可能发生。盲目创建另一个任务可能会生成并计费一个重复资产。

将 HTTP 请求超时用作视频截止时间

创建任务请求和视频处理生命周期是两个不同的计时器。保持第一次请求简短，然后在持久化的任务状态中跟踪异步截止时间。

跳过仪表板验证

成功的应用响应并不等于完整的运行检查。请确认使用量、模型、延迟和成本信息是否出现在团队预期监控的位置。

FAQ

我可以只更改 OpenAI 基础 URL 来集成 Seedance 吗？

更改基础 URL 可以简化受支持的 OpenAI 兼容请求的共享连接层。Seedance 视频生成可能仍然需要专用的异步端点和特定于提供商的参数。在实施前请先确认当前路由。

迁移期间应保持哪些内容不变？

保持密钥注入、环境命名、关联 ID、日志记录、告警以及面向产品的视频接口稳定。将特定于提供商的更改限制在配置和视频适配器中。

为什么视频产品要运行 chat 冒烟测试？

该冒烟测试可以快速将网关身份验证、基础 URL、网络和 Usage Logs 与较长的视频工作流区分开来。它是连接测试，不是视频能力测试。

视频完成应使用轮询还是 webhook？

请使用当前视频 API 和你的基础设施所支持的机制。轮询更简单，但必须设置上限并进行退避。Webhook 可减少轮询，但需要签名验证、幂等性以及对遗漏事件的对账。

如何防止重复的视频任务？

为产品请求创建并持久化幂等键，立即存储外部任务 ID，并在可能的情况下让重试继续现有任务。

上线前应该在哪里比较成本？

先查看当前的 Flatkey pricing page，然后比较每个已完成视频的成本，而不仅仅是每次请求或每秒的价格。计算时应包含失败和重复的任务。

先构建稳定边界

最快的迁移并不是第一天改动行数最少的迁移，而是能将未来的提供商变更缩减为一次受控的配置更新和一个小型适配器的迁移。

先使用一个 Flatkey key，将共享客户端迁移到稳定的基础 URL，在 Usage Logs 中验证连接，然后将当前的 Seedance 工作流作为异步任务系统进行测试。检查通过后，获取一个 key，并带着明确的指标和回滚触发条件逐步发布。