⚠️ 实验性功能警告
视频生成是一个实验性功能,可能会发生重大变化。在使用此功能之前,请仔细阅读以下注意事项。
主要注意事项
- API 可能在未来版本中随时更改
- OpenAI 的 Sora API 处于有限可用状态,可能需要组织验证
- 视频生成使用作业/轮询架构,与其他同步活动不同
- 定价、速率限制和配额可能会有所不同,并可能随时更改
- 并非此处描述的所有功能在您的 OpenAI 帐户中都可用
TanStack AI 通过专用的视频适配器提供对视频生成的实验性支持。与图像生成不同,视频生成是一个异步操作,它使用作业/轮询模式
当前支持
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)
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)
}
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)
}
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 | 带有模型(必需)的视频适配器实例 |
| prompt | string | 要生成的视频的文本描述(必需) |
| size | string | 视频分辨率,格式为 WIDTHxHEIGHT |
| 持续时间 | number | 视频持续时间(以秒为单位)(映射到 API 中的 seconds 参数) |
| modelOptions? | object | 模型特定选项(从 providerOptions 重命名) |
| 尺寸 | 描述 |
|---|---|
| 1280x720 | 16:9 景观 720p - 默认 |
| 720x1280 | 9:16 肖像 720p |
| 1792x1024 | 宽景观 |
| 1024x1792 | 高肖像 |
API 使用 seconds 参数。允许的值
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
}
})
interface VideoJobResult {
jobId: string // Unique job identifier for polling
model: string // Model used for generation
}
interface VideoStatusResult {
jobId: string
status: 'pending' | 'processing' | 'completed' | 'failed'
progress?: number // 0-100, if available
error?: string // Error message if failed
}
interface VideoUrlResult {
jobId: string
url: string // URL to download/stream the video
expiresAt?: Date // When the URL expires
}
| 模型 | 描述 | 用例 |
|---|---|---|
| sora-2 | 更快的生成速度,良好的质量 | 快速迭代,原型设计 |
| sora-2-pro | 更高的质量,更慢 | 生产质量的输出 |
视频生成可能由于各种原因而失败。始终实现适当的错误处理
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 适配器相同的环境变量
对于生产用途或需要显式控制时
import { createOpenaiVideo } from '@tanstack/ai-openai'
const adapter = createOpenaiVideo('your-openai-api-key')
| 方面 | 图像生成 | 视频生成 |
|---|---|---|
| API 类型 | 同步 | 作业/轮询 |
| 返回类型 | ImageGenerationResult | VideoJobResult → VideoStatusResult → VideoUrlResult |
| 等待时间 | 秒 | 分钟 |
| 多个输出 | numberOfImages 选项 | 不支持 |
| 选项字段 | prompt、size、numberOfImages | prompt、size、duration |
⚠️ 这些限制可能会随着功能的演变而发生变化。
此功能是实验性的。未来的版本可能包括
请关注 TanStack AI changelog 以获取更新。