文档
CodeRabbit
Cloudflare
AG Grid
Netlify
Neon
WorkOS
Clerk
Convex
Electric
PowerSync
Sentry
Railway
Prisma
Strapi
Unkey
CodeRabbit
Cloudflare
AG Grid
Netlify
Neon
WorkOS
Clerk
Convex
Electric
PowerSync
Sentry
Railway
Prisma
Strapi
Unkey
类引用
函数引用
接口引用
类型别名引用
变量引用
指南

视频生成

视频生成(实验性)

⚠️ 实验性功能警告

视频生成是一个实验性功能,可能会发生重大变化。在使用此功能之前,请仔细阅读以下注意事项。

主要注意事项

  • API 可能在未来版本中随时更改
  • OpenAI 的 Sora API 处于有限可用状态,可能需要组织验证
  • 视频生成使用作业/轮询架构,与其他同步活动不同
  • 定价、速率限制和配额可能会有所不同,并可能随时更改
  • 并非此处描述的所有功能在您的 OpenAI 帐户中都可用

概述

TanStack AI 通过专用的视频适配器提供对视频生成的实验性支持。与图像生成不同,视频生成是一个异步操作,它使用作业/轮询模式

  1. 创建作业 - 提交提示并接收作业 ID
  2. 轮询状态 - 检查作业状态,直到完成
  3. 检索视频 - 获取下载/查看生成的视频的 URL

当前支持

  • OpenAI:Sora-2 和 Sora-2-Pro 模型(可用时)

基本用法

创建视频作业

typescript
import { generateVideo } from '@tanstack/ai'
import { openaiVideo } from '@tanstack/ai-openai'

// Create a video adapter (uses OPENAI_API_KEY from environment)
const adapter = openaiVideo()

// Start a video generation job
const { jobId, model } = await generateVideo({
  adapter: openaiVideo('sora-2'),
  prompt: 'A golden retriever puppy playing in a field of sunflowers',
})

console.log('Job started:', jobId)

轮询状态

typescript
import { getVideoJobStatus } from '@tanstack/ai'

// Check the status of the job
const status = await getVideoJobStatus({
  adapter: openaiVideo('sora-2'),
  jobId,
})

console.log('Status:', status.status) // 'pending' | 'processing' | 'completed' | 'failed'
console.log('Progress:', status.progress) // 0-100 (if available)

if (status.status === 'failed') {
  console.error('Error:', status.error)
}

获取视频 URL

typescript
import { getVideoJobStatus } from '@tanstack/ai'

// Only call this after status is 'completed'
const result = await getVideoJobStatus({
  adapter: openaiVideo('sora-2'),
  jobId,
})

if (result.status === 'completed' && result.url) {
  console.log('Video URL:', result.url)
  console.log('Expires at:', result.expiresAt)
}

带有轮询循环的完整示例

typescript
import { generateVideo, getVideoJobStatus } from '@tanstack/ai'
import { openaiVideo } from '@tanstack/ai-openai'

async function generateVideo(prompt: string) {
  const adapter = openaiVideo()

  // 1. Create the job
  const { jobId } = await generateVideo({
    adapter: openaiVideo('sora-2'),
    prompt,
    size: '1280x720',
    duration: 8, // 4, 8, or 12 seconds
  })

  console.log('Job created:', jobId)

  // 2. Poll for completion
  let status = 'pending'
  while (status !== 'completed' && status !== 'failed') {
    // Wait 5 seconds between polls
    await new Promise((resolve) => setTimeout(resolve, 5000))

    const result = await getVideoJobStatus({
      adapter: openaiVideo('sora-2'),
      jobId,
    })

    status = result.status
    console.log(`Status: ${status}${result.progress ? ` (${result.progress}%)` : ''}`)

    if (result.status === 'failed') {
      throw new Error(result.error || 'Video generation failed')
    }
  }

  // 3. Get the video URL
  const result = await getVideoJobStatus({
    adapter: openaiVideo('sora-2'),
    jobId,
  })

  if (result.status === 'completed' && result.url) {
    return result.url
  }

  throw new Error('Video generation failed or URL not available')
}

// Usage
const videoUrl = await generateVideo('A cat playing piano in a jazz bar')
console.log('Video ready:', videoUrl)

选项

作业创建选项

选项类型描述
适配器VideoAdapter带有模型(必需)的视频适配器实例
promptstring要生成的视频的文本描述(必需)
sizestring视频分辨率,格式为 WIDTHxHEIGHT
持续时间number视频持续时间(以秒为单位)(映射到 API 中的 seconds 参数)
modelOptions?object模型特定选项(从 providerOptions 重命名)

支持的尺寸

基于 OpenAI API 文档

尺寸描述
1280x72016:9 景观 720p - 默认
720x12809:16 肖像 720p
1792x1024宽景观
1024x1792高肖像

支持的持续时间

API 使用 seconds 参数。允许的值

  • 4
  • 8 秒(默认)
  • 12

模型选项

OpenAI 模型选项

基于 OpenAI Sora API

typescript
const { jobId } = await generateVideo({
  adapter: openaiVideo('sora-2'),
  prompt: 'A beautiful sunset over the ocean',
  size: '1280x720',      // '1280x720', '720x1280', '1792x1024', '1024x1792'
  duration: 8,           // 4, 8, or 12 seconds
  modelOptions: {
    size: '1280x720',    // Alternative way to specify size
    seconds: 8,          // Alternative way to specify duration
  }
})

响应类型

VideoJobResult(来自 create)

typescript
interface VideoJobResult {
  jobId: string    // Unique job identifier for polling
  model: string    // Model used for generation
}

VideoStatusResult(来自 status)

typescript
interface VideoStatusResult {
  jobId: string
  status: 'pending' | 'processing' | 'completed' | 'failed'
  progress?: number  // 0-100, if available
  error?: string     // Error message if failed
}

VideoUrlResult(来自 url)

typescript
interface VideoUrlResult {
  jobId: string
  url: string        // URL to download/stream the video
  expiresAt?: Date   // When the URL expires
}

模型变体

模型描述用例
sora-2更快的生成速度,良好的质量快速迭代,原型设计
sora-2-pro更高的质量,更慢生产质量的输出

错误处理

视频生成可能由于各种原因而失败。始终实现适当的错误处理

typescript
try {
  const { jobId } = await generateVideo({
    adapter: openaiVideo('sora-2'),
    prompt: 'A scene',
  })

  // Poll for status...
  const status = await getVideoJobStatus({
    adapter: openaiVideo('sora-2'),
    jobId,
  })

  if (status.status === 'failed') {
    console.error('Generation failed:', status.error)
    // Handle failure (e.g., retry, notify user)
  }
} catch (error) {
  if (error.message.includes('Video generation API is not available')) {
    console.error('Sora API access may be required. Check your OpenAI account.')
  } else if (error.message.includes('rate limit')) {
    console.error('Rate limited. Please wait before trying again.')
  } else {
    console.error('Unexpected error:', error)
  }
}

速率限制和配额

⚠️ 注意:视频生成的速率限制和配额可能会发生变化,并且可能因帐户层级而异。

典型注意事项

  • 视频生成计算成本很高
  • 可能适用并发作业限制
  • 可能存在每月生成配额
  • 更长/更高质量的视频会消耗更多配额

请查看 OpenAI 文档 以获取当前限制。

环境变量

视频适配器使用与其他 OpenAI 适配器相同的环境变量

  • OPENAI_API_KEY:您的 OpenAI API 密钥

显式 API 密钥

对于生产用途或需要显式控制时

typescript
import { createOpenaiVideo } from '@tanstack/ai-openai'

const adapter = createOpenaiVideo('your-openai-api-key')

与图像生成的不同之处

方面图像生成视频生成
API 类型同步作业/轮询
返回类型ImageGenerationResultVideoJobResultVideoStatusResultVideoUrlResult
等待时间分钟
多个输出numberOfImages 选项不支持
选项字段promptsizenumberOfImagespromptsizeduration

已知限制

⚠️ 这些限制可能会随着功能的演变而发生变化。

  1. API 可用性:Sora API 可能并非在所有 OpenAI 帐户中都可用
  2. 生成时间:视频生成可能需要几分钟
  3. URL 过期:生成的视频 URL 可能会在一段时间后过期
  4. 无实时进度:进度更新可能会受到限制或延迟
  5. 音频限制:音频生成支持可能有限
  6. 提示长度:长提示可能会被截断

最佳实践

  1. 实施超时:为轮询循环设置合理的超时时间
  2. 优雅地处理故障:为失败的生成提供后备行为
  3. 缓存 URL:存储视频 URL 并在重新获取之前检查过期时间
  4. 用户反馈:在生成过程中显示清晰的进度指示器
  5. 验证提示:在提交之前检查提示长度和内容
  6. 监控使用情况:跟踪生成使用情况以避免达到配额

未来考虑

此功能是实验性的。未来的版本可能包括

  • 其他视频模型和提供商
  • 流式进度更新
  • 视频编辑和操作
  • 音频轨道生成
  • 批量视频生成
  • 自定义风格/美学控制

请关注 TanStack AI changelog 以获取更新。