Provider-neutral TypeScript SDK for AI video generation.
Raccord 用一个类型安全的 task contract 直连 ByteDance、BytePlus、MiniMax、Kling、Google、 HappyHorse 与 Wan。它统一输入校验、异步任务生命周期、输出结构和失败语义，同时保留各厂商真正不同的能力。
Core SDK 运行在你的应用中：不代理请求、不托管任务、不保存 API key。需要持久化或 HTTP API 时， 可以按需使用独立的 PostgreSQL、Redis adapter 和仓库内的 self-hosted server。
- 一个任务合同：统一创建、查询、取消、等待和状态流，返回标准
VideoTask。 - 在请求前失败：每个 model 都有严格的 Zod schema，非法字段和不支持的组合不会发往厂商。
- 保留厂商差异：稳定字段进入公共 input；厂商专属能力通过经过校验的
providerOptions暴露。 - 安全的 Provider fallback：只在确定远程任务尚未创建时切换 Provider，避免重复生成和重复计费。
- 可恢复但不强绑定基础设施：core 默认零数据库 driver；PostgreSQL 和 Redis 通过独立 package 接入。
- 生产可观测：提供 lifecycle hooks、OpenTelemetry spans、持久 webhook outbox 与 HMAC 签名。
pnpm add raccordCore 要求 Node.js 20 或更高版本。
Provider 使用独立 subpath 导入，因此只会加载你实际使用的 adapter：
import { RaccordClient } from "raccord"
import {
BYTEDANCE_MODELS,
createBytedance,
} from "raccord/providers/bytedance"
const client = new RaccordClient({
providers: [createBytedance({ apiKey: process.env.ARK_API_KEY! })],
})
const task = await client.createTask(
{
provider: "bytedance",
model: BYTEDANCE_MODELS.SEEDANCE_2_0_FAST,
input: {
prompt: "A paper boat crosses a rainy neon street",
duration: 8,
resolution: "720p",
},
},
{ idempotencyKey: "order_123_scene_4" },
)
const completed = await client.waitForTask(task, {
intervalMs: 2_000,
timeoutMs: 15 * 60_000,
})
console.log(completed.status, completed.outputs)Model ID 是 provider-relative 的。同名 model 可以指向不同地区或厂商的上游 ID，但任务始终记录真正 接单的 Provider。
| Provider | 导出枚举 | 当前 model | 取消能力 |
|---|---|---|---|
| ByteDance | BYTEDANCE_MODELS |
Seedance 2.0 / Fast / Mini，普通与 Reference | 仅 queued |
| BytePlus | BYTEPLUS_MODELS |
Seedance 2.0 / Fast / Mini，普通与 Reference | 仅 queued |
| MiniMax | MINIMAX_MODELS |
H3、H3 Reference | 仅 queued |
| Kling | KLING_MODELS |
3.0、3.0 Omni、3.0 Turbo | 暂不支持 |
GOOGLE_MODELS |
Gemini Omni Flash Preview | 上游 cancel endpoint | |
| HappyHorse | HAPPYHORSE_MODELS |
T2V、I2V、R2V、VideoEdit | 暂不支持 |
| Wan | WAN_MODELS |
2.7 T2V、I2V、R2V、VideoEdit | 暂不支持 |
import { createBytePlus } from "raccord/providers/byteplus"
import { createGoogle } from "raccord/providers/google"
import { createHappyHorse } from "raccord/providers/happyhorse"
import { createKling } from "raccord/providers/kling"
import { createMiniMax } from "raccord/providers/minimax"
import { createWan } from "raccord/providers/wan"各 model 的字段、枚举、媒体数量和组合限制见 Provider contracts。
普通 model 使用 prompt 和可选 frames。只有 prompt 是文生视频；加入首帧或首尾帧后就是图生视频：
const input = {
prompt: "The camera slowly pushes in",
frames: {
first: { url: "https://cdn.example.com/first.png" },
last: { url: "https://cdn.example.com/last.png" },
},
duration: 6,
}Reference / Omni model 使用带 type、role 和 id 的 references，不维护三组容易漂移的
images、videos、audios 字段：
import { KLING_MODELS } from "raccord/providers/kling"
const request = {
provider: "kling",
model: KLING_MODELS.V3_OMNI,
input: {
prompt: "Keep @image_1's identity and follow @video_1's motion",
references: [
{
type: "image",
role: "reference",
id: "image_1",
url: "https://cdn.example.com/character.png",
},
{
type: "video",
role: "reference",
id: "video_1",
url: "https://cdn.example.com/motion.mp4",
},
],
},
} as constproviderOptions 只承载某个厂商独有且经过 schema 校验的字段，不是任意 extraBody。
VideoTask 是远程任务在某一时刻的 snapshot。Raccord 把厂商状态归一为五种：
| 状态 | 终态 | watchTask() / waitForTask() |
|---|---|---|
queued |
否 | 继续 polling |
processing |
否 | 继续 polling |
succeeded |
是 | 返回并停止 |
failed |
是 | 返回并停止 |
canceled |
是 | 返回并停止 |
for await (const snapshot of client.watchTask(task, {
intervalMs: 2_000,
jitterRatio: 0.2,
retry: { maxAttempts: 3, initialDelayMs: 1_000 },
})) {
console.log(snapshot.status, snapshot.outputs)
}读取请求会对网络错误、408、425、429 和 5xx 做 bounded retry，并遵守 Retry-After。
创建请求不会盲目重试：网络中断后无法证明远程任务是否已经创建，自动重提可能产生重复视频。
modelProviders 为调用侧 model 声明一个有序 Provider 列表。只有明确未创建远程任务的错误才会进入
下一个 Provider；提交结果未知时立即停止。
const client = new RaccordClient({
providers: [relay, bytedance],
modelProviders: {
"seedance-2.0": [
{ provider: "relay", model: "relay-seedance-v2" },
"bytedance",
],
},
})
const task = await client.createTask({
model: "seedance-2.0",
input: { prompt: "A paper boat crosses a rainy street" },
})任务创建后会记录实际 provider 和 model；后续查询与取消不再经过 fallback 配置。
默认 MemoryTaskStore 和 MemoryWebhookDeliveryStore 适合单进程开发。生产环境可以安装独立 adapter：
| Package | 用途 | Peer dependency |
|---|---|---|
raccord-postgres |
PostgreSQL TaskStore 与 webhook outbox | pg、@types/pg |
raccord-redis |
Redis TaskStore 与 webhook outbox | redis |
pnpm add raccord raccord-postgres pg
# 或
pnpm add raccord raccord-redis redisimport { Pool } from "pg"
import { RaccordClient } from "raccord"
import {
createPostgresStores,
createPostgresStoreSchemaSql,
} from "raccord-postgres"
const pool = new Pool({ connectionString: process.env.DATABASE_URL })
// 在部署 migration 阶段执行，不要放进请求 handler。
await pool.query(createPostgresStoreSchemaSql())
const client = new RaccordClient({
providers,
...createPostgresStores(pool),
})持久 store 区分安全拒绝与 submission_unknown，并通过 lease 恢复中断的 task submission 和 webhook
delivery。完整安装、安全要求与原子性合同见
Storage adapters 和 Durability contracts。
- Completion webhook 使用
v1=HMAC_SHA256(secret, timestamp + "." + rawBody)签名。 - 持久 outbox 保存固定 delivery ID 和 payload，按 at-least-once 语义投递。
- Named lifecycle hooks 覆盖 request、response、retry、error 与 task status event。
- OpenTelemetry 记录
raccord.create、raccord.get、raccord.cancel、raccord.provider.*和raccord.webhook.deliverspans。 - Prompt、媒体 URL、API key 与 webhook secret 不会进入 spans；event 可通过
eventRedactor脱敏。
defineVideoProvider() 可以接入官方 API、中转服务或私有 model。自定义 adapter 拥有自己的 Zod input
schema，并负责把远程协议映射为标准 VideoTask。Raccord 不要求 manifest、动态发现或统一上游字段。
完整实现合同和示例见 Custom providers。
apps/server 提供可自行部署的 Hono HTTP API、OpenAPI 3.1 文档、PostgreSQL 权威状态和 Graphile
Worker。它与 core SDK 的边界不同：credential 只从 server 环境变量读取，创建请求通过
Idempotency-Key 入库后异步执行。
Server 要求 Node.js 22.18+ 和 PostgreSQL 12+。运行方式见 Server README。
apps/
└── server/ # self-hosted HTTP API 与 worker
packages/
├── core/ # raccord
├── postgres/ # raccord-postgres
└── redis/ # raccord-redis
| 文档 | 内容 |
|---|---|
| Provider contracts | 各厂商 model、字段、组合限制与官方资料 |
| Custom providers | 自定义 adapter 的类型推导与提交合同 |
| Storage adapters | PostgreSQL / Redis 安装、配置与运行约束 |
| Durability contracts | 幂等、lease、submission unknown 与恢复语义 |
| Provider pricing | 成本估算规则与实际 billing evidence |
Raccord 统一协议，但不假装所有 Provider 完全相同：
- 不提供托管 gateway、API key vault、全局 queue、账号限流或动态调度策略。
- 不在无法确认提交结果时自动重试创建请求。
- 不隐式下载媒体来校验编码、像素、文件大小或真实时长。
- 不把 provider 原始响应当作稳定公共 API。
如果需要不同的调度、限流或运行时策略，应由宿主应用或 self-hosted server 明确拥有。
pnpm install
pnpm check
pnpm build
# 只运行一个 package
pnpm turbo run test --filter=raccord-postgres