AI 视频生成 API：用 TypeScript 实现文生视频

AI 视频生成 API 通过异步任务把提示词变成视频：启动 Video Generator，使用返回的运行 ID 查询状态，并在任务完成后从资源中读取视频 URL。Pipe2 的 TypeScript SDK 直接提供这些公开操作，因此可以用很少的代码完成文生视频集成。

使用 TypeScript SDK 运行文生视频

安装 @pipe2-ai/sdk，把 Pipe2 令牌放在 PIPE2_TOKEN 中，然后使用 Node 运行下面的模块。示例只描述一个可观察的动作和一段简短时间线，让生成器面对一个清晰的单镜头任务。

import { createClient } from '@pipe2-ai/sdk';

const input = {
  prompt: '[0-3s] A paper airplane circles above a classroom. [3-6s] It lands beside a notebook. Gentle room ambience, no music.',
};
const client = createClient(process.env.PIPE2_TOKEN);
const { run_pipeline } = await client.RunPipeline({
  pipeline_slug: 'video-generator',
  input,
});

while (true) {
  const { pipeline_runs_by_pk: run } = await client.GetPipelineRun({
    id: run_pipeline.run_id,
  });
  if (run?.status === 'completed') {
    console.log(run.assets?.[0]?.url);
    break;
  }
  if (run?.status === 'failed') throw new Error(run.error_message ?? 'Video generation failed');
  await new Promise((resolve) => setTimeout(resolve, 3000));
}

去掉身份验证和轮询代码后，同一个流水线请求如下：

{
  "pipeline_slug": "video-generator",
  "input": {
    "prompt": "[0-3s] A paper airplane circles above a classroom. [3-6s] It lands beside a notebook. Gentle room ambience, no music."
  }
}

TypeScript SDK 文档介绍了安装、身份验证、流水线运行、状态查询、订阅、资源上传和点数操作。

理解运行、轮询与资源获取流程

RunPipeline 接收流水线 slug 和一个 JSON 输入对象。它不会让请求一直等待视频生成完成，而是返回新任务的标识符。请保存 run_pipeline.run_id，因为 GetPipelineRun 需要使用这个 ID。

每次轮询都会返回最新的运行记录。状态为 completed 的任务可以包含生成的资源，示例会输出第一个资源的 URL。状态为 failed 的任务会提供错误信息，集成程序应该展示或记录它。生产代码还应设置整体超时时间；如果任务不存在，应将其视为错误，而不是无限轮询。

对于小型脚本，每隔几秒查询一次就足够了。如果服务需要持续接收更新，SDK 还提供 WatchPipelineRun，可以通过异步迭代器读取同一任务的状态。

从最简单的有效输入开始

该请求只包含 prompt。这是文生视频最小且实用的输入，并让模型选择保持为 Auto。Video Generator 也可以使用起始帧或结束帧，还支持可选的图像、视频和音频参考素材。兼容的时长、分辨率、宽高比和参考素材数量取决于所选模型路径。

只在产品确实需要时添加设置。例如，发布平台可能要求特定宽高比，主体一致性可能需要参考图像，更长的视频则可能需要另一条兼容路径。在提交成本更高或包含更多媒体的请求前，可以使用相同的 pipeline_slug 与 input 调用 EstimatePipelineCost。

为一个生成镜头编写提示词

即使使用 API，也需要准确的镜头说明。描述画面中的动作、镜头运动、环境、时间安排和声音，并确保动作能在指定时长内自然完成。

示例虽然使用两个时间段，但表达的是一个连续事件：纸飞机先盘旋，然后落在笔记本旁边。它不要求切换地点、增加多个角色或进行多次剪辑。因此，动作连续性、物体形状、降落时刻和音频都更容易检查。

对于更大的制作，应先分别生成并确认各个镜头，再进行组装。AI 视频制作指南进一步介绍了这次 API 调用之后的规划、审核、剪辑、字幕和成片处理。

明确处理身份验证与失败状态

使用 Pipe2 令牌创建客户端，并把令牌保存在服务器或安全的本地环境变量中。不要把它写入发送到浏览器的源代码、提交到代码库，也不要放进流水线输入。

应区分提交错误和运行失败。请求可能因为没有身份验证、输入无效或无法预留所需点数，而在任务开始前失败。成功创建的任务也可能稍后进入 failed 状态，此时应检查 error_message。只有状态为 completed 时才使用资源 URL。

如果工作流从图像开始，请按照 SDK 文档中的资源流程上传或引用图像，并参考图生视频指南准备素材和描述运动。