接入 LibTV+

在开始改造前，请确保你已具备:

• LibTV+ 源码或运行环境，能够修改代码并重新部署
• 太行HUB的端点和API KEY信息

项目	值
Base URL	https://api.taiha.cn/v1
API Key	在控制台创建
Model ID	在模型广场查看

改造步骤

第一步：客户端替换

将原 volcenginesdkarkruntime（Ark）客户端替换为标准的 OpenAI SDK 或等价 HTTP 调用，base_url 指向太行HUB端点 /v1，api_key 改为控制台获取的令牌。

Python

import os
from openai import OpenAI

# 原官方直连（注释保留，便于回滚）
# from volcenginesdkarkruntime import Ark
# client = Ark(
#     base_url="https://ark.cn-beijing.volces.com/api/plan/v3",
#     api_key=os.environ["VOLCENGINE_ARK_KEY"]
# )

# 改为中转站 OpenAI 兼容网关
BASE_URL = os.environ.get("SEEDANCE_RELAY_BASE_URL", "https://api.taiha.cn/v1")
TOKEN = os.environ["API_KEY"]

client = OpenAI(base_url=BASE_URL, api_key=TOKEN)

Node.js

const BASE_URL = process.env.SEEDANCE_RELAY_BASE_URL || "https://api.taiha.cn/v1";
const TOKEN = process.env.API_KEY!;

export async function createVideo({
  prompt,
  imageUrl,
  duration = 5,
  aspectRatio = "16:9",
  generateAudio = true,
}: CreateVideoParams) {
  const body = {
    model: "doubao-seedance-2.0-pro",
    prompt,
    duration,
    aspect_ratio: aspectRatio,
    generate_audio: generateAudio,
  };
  if (imageUrl) {
    body.image_with_roles = [{ url: imageUrl, role: "reference_image" }];
  }

  const resp = await fetch(`${BASE_URL}/videos/generations`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${TOKEN}`,
    },
    body: JSON.stringify(body),
  });

  if (!resp.ok) {
    throw new Error(`seedance create failed: ${resp.status}`);
  }

  const data = await resp.json();
  return data.id;
}

以上示例通过环境变量 API_KEY 配置你的API KEY

第二步：字段映射

火山 content_generation 的请求字段需映射为网关约定的字段结构。

火山字段	含义	映射字段
model = "doubao-seedance-2.5"	模型标识	model（如 seedance-2-5）
content[].text	文生视频提示词	input.prompt
content[].image_url	参考图	input.media: [{type: "first_clip", url: "资源地址"}]
duration	时长（秒）	parameters.duration
ratio	画幅比例	parameters.ratio
generate_audio	是否生成音频	parameters.generate_audio
watermark	水印	parameters.watermark
提交返回 task.id	任务 ID	task_id
GET tasks/{id}	查询任务	GET /v1/video/generations/{task_id}

具体映射字段键名，请查阅本技术文档生视频中的请求示例

第三步：异步轮询

生视频为异步任务，提交后返回 task_id，需要通过轮询查询接口获取 video_url。

轮询示例

export async function queryVideo(taskId: string) {
  const resp = await fetch(`${BASE_URL}/video/generations/${taskId}`, {
    headers: {
      Authorization: `Bearer ${TOKEN}`,
    },
  });

  const data = await resp.json();

  return {
    status: data.status, // succeeded / failed / processing
    videoUrl: data.content?.video_url ?? (data.videos && data.videos[0]?.url),
    error: data.error,
  };
}

轮询建议：

• 间隔：5–8 秒
• 超时：建议设置 5–10 分钟超时
• 失败处理：根据 error.code / error.message 进行相应处理

注意

视频 URL 有效期较短（通常为 24-72 小时），获取后应及时下载转存。
对于千问及万相系列返回的资源URL，请先处理Unicode转义后再请求下载。

配置管理

环境变量配置

# 网关地址（注意：需要以 /v1 结尾）
SEEDANCE_RELAY_BASE_URL=https://api.taiha.cn/v1
SEEDANCE_RELAY_TOKEN=<API KEY>
# 回滚开关：1 = 使用官方直连，0 = 使用太行HUB
USE_OFFICIAL=0

密钥管理要求

• 令牌与网关地址强烈建议通过环境变量或配置中心注入。
• 通过 硬编码、入库、下发至客户端等方式及其不安全。
• 令牌泄露时应立即通过控制台对令牌吊销并重新下发。

常见问题

Q：如何确认接入是否成功？

• 设置环境变量后，启动 LibTV+。
• 尝试创建一个文本生视频任务。
• 如果任务成功返回 task_id 并最终生成 video_url，说明接入成功。

Q：接入后生成结果与官方有差异怎么办？

• 首先确认调用的模型别名与官方模型版本的对应关系。
• 检查字段映射是否正确（尤其是 duration、aspect_ratio 等参数）。