pi-video-gen (英语)

Pi扩展用于视频创建. video_generate 直接为一个片段调用视频模型; video_compose 通过无损失的集合、FFmpeg时间表或可信赖的再动项目来组装现有媒体; video_render 执行一个已准备好的批次脚本,其中包含生成的和已有的镜头,持续远程任务恢复和可选组装。 这个 video-gen 技术解释如何选择每个镜头. video_capabilities 财务报告和审定财务报表 /video-gen 提供模型信息和直接命令.

供应商

登记册条目是根据供应商文件(每个适配器的抬头注明来源)编写的,有待实时烟雾测试与真实账户核对 /video-gen doctor + 一个小的付费剪接后再重用. 种子 2.5 留在路线图上,直到其官方API ID和参数合同公布.

种子信任的肖像资产:种子可能拒绝包含可识别真实人物的普通图像/视频引用. 对于这些镜头,在用于生成的同一Volcengine Ark账户/项目中选择一个预设的相机或活动授权人资产,然后通过它 asset-... 身份证(或 asset://asset-... URI)通过 referenceAssets。扩展支持信任 image, (中文(简体) ), video,以及 audio 用于内置种子2.0模型的资产,并将其映射到方舟公司 asset:// 请求格式。 快速文本将其顺序称为 Image 1, (中文(简体) ), Video 1,以及 Audio 1 从来没有通过资产身份.

该邮包船将公共材料卡和预设人物图书馆的快照日期定在 skills/video-gen/references/,包括: referenceAssets。Volcengine不将这些ID记录为永久或交叉账户,因此如果拒绝一个快照ID,则使用从活动账户库复制的ID重试。 私人或授权人员的资产总是要求用户提供活期账户/项目的实际身份。 身份验证,授权H5流量,活化,上传,资产-图书馆管理仍然不在此包外. 见"沃尔肯吉" 预设版本指南, (中文(简体) ), 授权人员资产指南,以及 种子请求格式。 。 。 .

设置

全球设置( E)~/.pi/agent/settings.json:

{
  "pi-video-gen": {
    "defaultModel": "seedance-2.0",              // alias of doubao-seedance-2-0-260128
    "providers": {
      "ark": { "apiKey": "${ARK_API_KEY}" }      // Volcengine Ark key
    },
    "rateLimit": { "maxRequestsPerMinute": 2, "maxRequestsPerDay": 20 },
    "concurrency": { "clips": 2 }
  }
}

自定义提供者 (和pi-image-gen的相同的想法——将任何相兼容的方舟端点指向自己的模型;字符串模型得到保守的能力,对象模型宣布它们). 当一个自定义模型 id 命名一个内置模型(例如:. "MiniMax-H3" 中继后,内置能力表和默认自动继承——未宣布 capabilities, (中文(简体) ), defaultResolution编号 :defaultAspectRatio编号 :defaultDurationSec 返回注册值, 而不是保守的 720p/16:9 配置, 而您所声明的任何字段都会覆盖继承的 :

{
  "pi-video-gen": {
    "defaultModel": "fast9",
    "customProviders": {
      "myproxy": {
        "api": "ark",
        "baseUrl": "https://proxy.example/api/v3",
        "apiKey": "${MY_PROXY_KEY}",
        "models": [
          "seedance-lite-x",
          { "id": "remote-model-9", "alias": "fast9",
            "capabilities": { "maxReferenceImages": 9,
              "maxReferenceVideos": 3, "maxReferenceAudios": 3, "durations": [2, 30],
              "resolutions": ["480p", "720p", "1080p"], "aspectRatios": ["16:9", "9:16"],
              "nativeAudio": true, "supportsFirstLastFrame": true,
              "referenceAssetModalities": ["image", "video", "audio"] } }
        ]
      }
    }
  }
}

新API 注释 (单位:千美元)视频格式文件: NewAPI是一个自我托管的中继器,所以 newapi 线条格式没有默认终点—— baseUrl 是强制的,解析失败,无法准确设置路径来修复它。 两个服务器根( R)"https://newapi.example.com")和 OpenAI 风格 "…/v1" 表格被接受。 频道特定参数乘入 metadata 以上游文献为例: aspect_ratio + 键 resolution (Jimeng/Vidu风格), image_tail 最后一个框架( Kling 样式) 和 image_urls 用于额外参考图像( Jimeng 样式); 第一个框架在顶层 image 字段。 没有有文件记录的音频切换或自失能密钥, 因此模糊的提交被停放用于人工解析, 而不是自动重审 :

{
  "pi-video-gen": {
    "defaultModel": "kling-v1",
    "customProviders": {
      "newapi": {
        "api": "newapi",
        "baseUrl": "https://newapi.example.com",   // REQUIRED
        "apiKey": "${NEWAPI_API_KEY}",
        "models": ["kling-v1", "jimeng_vgfm_t2v_l20", "viduq1"]
      }
    }
  }
}

最小标记 (v2 API, 创建 编号 : 查询: MiniMax-H3 说出一个多模式任务 API——一个中的快+帧骑 content 以 first_frame 编号 : last_frame 编号 : reference_image 角色(第一/最后一帧和参考图像相互排斥;最后一帧需要第一帧). 决议是 768P 或者说 2K4-15s,比例 16:9|4:3|1:1|3:4|9:16|21:9 ——文本到视频需要且不适应,一有第一帧就被忽略(强制适应). 没有音频切换、无自失能键和无文件记录的取消端点,所以模糊的提交被停放在手动解决,而不是自动重审。 Auth 是一个普通的 Bearer 键 (providers.minimax.apiKey环境 MINIMAX_API_KEY),而密钥是区域锁定的:默认终点是国际 api.minimax.io ——中国大陆需要钥匙 providers.minimax.baseUrl 设置为 https://api.minimaxi.com (反之,401意味着错误的区域). 结果 URL 有时间限制; 剪辑立即下载, 任务可查询7天 .

Kling 笔记 (通过浏览器对kling.ai/document-api进行验证,2026-07):当前Kling API 2.0使用平面API键(plain API)providers.kling.apiKey环境 KLING_API_KEY——"JWT ak/sk"计划为后遗症. 该模型生活在 URL 路径中(kling-3.0-turbo 编号 : kling-3.0; 默认基础 api-singapore.klingai.com (区域终点通过 baseUrl. Kling 3.0 (英语). Omni支持后方帧,原生音频和4k;Turbo是第一方帧并沉默. 提交携带 external_task_id (我们要求的指纹),所以先检查模棱两可的失败;停放一个没有结果的检查,以便手动解决,而不是盲目重新提交.

快乐的豪斯笔记:没有本地音频,也没有最后框插入(nativeAudio: false, (中文(简体) ), supportsFirstLastFrame: false 在能力表中,因此工具隐藏/拒绝这些选项。 一个呼叫需要第一个框架(i2v) 或参考图像(r2v, 提示为 [Image 1], (中文(简体) ), [Image 2],... ),并非两者兼有. 默认终点是经典 dashscope.aliyuncs.com (不需要工作空间 ID); 如果您使用新的 Bailian 工作空间, 设置 providers.dashscope.baseUrl 改为 https://{workspaceId}.cn-beijing.maas.aliyuncs.com. 视频/任务URL在24h后过期——片段立即被下载.

信任边界数字 : providers.*, (中文(简体) ), customProviders.* 财务报告和审定财务报表 ffmpegPath 仅来自全局/代理目录设置——项目一级 .pi/settings.json 可以设置 outputDir, (中文(简体) ), defaultModel, (中文(简体) ), rateLimit, (中文(简体) ), concurrency 只有(并且只有在项目被信任时). 恶意重播无法重定向您的 API 密钥或交换二进制 .

ffmpeg 数据:需要多发相接器,并通过平台专用的可选npm包与插件自动安装. 主插件保持小块, 而 pi install npm:@amaster.ai/pi-video-gen 只下载匹配当前OS和CPU的平台有效载荷. 该有效载荷包含一个默认的 LGPL 架构外加单独命名的 GPL ffmpeg-gpl编号 :ffprobe-gpl libx264用于请求的H.264时间表输出的二进制. 被支持的捆绑目标有:macOS 11+ arm64/x64,glibc Linux arm64/x64(建于Ubuntu 22.04),和Windows x64;musl Linux通过PATH使用一个系统FFmpeg. 分辨率命令 : ffmpegPath 设置 FFMPEG_PATH env-已安装平台包 ffmpeg-static(只开发) → PATH. 一个自动捆绑但不能运行的候选设备被跳过,因此它不能遮盖工作过的 PATH 安装 。 检查 /video-gen doctor. Release CI 从被绑定的官方 FFmpeg 源头构建每个平台包, 外部- 图书馆自动检测被禁用; 准确的 FFmpeg, zlib, 和 x264 源文件, 在 二进制边构建脚本、 许可证和出处船 .

工具

有结构的提示

两种付费工具都采用结构化的即时字段,从不使用预接字符串. 插件组装标签的即时文本( E)[Style] 编号 : [Character] 编号 : [Scene] 编号 : [Visuals] 编号 : [Action] 编号 : [Effects] 编号 : [Audio] + 一致性/负性指令),所以每个镜头都可靠地携带了胶片级指令:

• 电影一级 —— 说 style (类别/质量/文字), characters (单位:千美元){id, description} 登记册, consistency (身份/无驾驶指令), negative (例如"没有文字,水印,或字幕").
• 射击级别 (单位:千美元)prompt 目标) - visuals (相机/香料)和 action 总是需要; scene 加胶片级 style 为: 无时需要 第一帧锁定镜头 (文本到视频不得只行动出去); effects 包含时间变化的内容 静态框架无法表达 (转换、照明转换、大气); audio 带 [Sound Effect] … / [Speaker] … 提示; visibleCharacters 插入 引用字符描述 .
• 受托资产参考 —— 说 referenceAssets 命令数组 {modality: "image"|"video"|"audio", assetId: "asset-..."}公众 API 还接受 asset://asset-... 并让它正常化。 只有模型声明 请求模式接受它; 在已付款的提交之前, 不支持输入失败 . 内建种子2.0模型执行单独请求最大值:9个图像 参考总数(当地框架加图像资产)、3个视频资产和3个 音频资产.

图标

选择路径

选择每次拍摄的来源: 重用已有的视频, 呼叫 video_generate 直接用于缺失的模型剪辑,或在Remotion中绘制精确的文本/UI/图动画. 使用 video_render 当一个准备的批次需要自动化和可靠的回收时。 相册,人物肖像和一相/后相框是可选的创意辅助. 见 技术, (中文(简体) ), 翻译脚本示例 财务报告和审定财务报表 调试交接。 。 。 .

video_compose 接受 <jobDir>/remotion-input.json 绝对值 projectDir, (中文(简体) ), compositionId选项 entryPoint, (中文(简体) ), assets, (中文(简体) ), inputProps 财务报告和审定财务报表 browserExecutable。项目必须在一个可信任的工作目录中进行,并安装了本地的Remotion依赖性加Chrome/Chrimium。 原文 public/ 以相对路径复制文件; 通过 inputProps.videoGenAssets 财务报告和审定财务报表 staticFile()。 。 。 . video_render 使用同一合同 assembly.type: "remotion";在任何模型提交之前,它先用占位符飞行项目。 该插件在渲染过程中不安装 Remotion 或下载浏览器.

复数规格也接受 qcTimesSec,最多32个非阴性时间戳 严格在组成期限内。 使用这些来审查移动前,期间和之后的关键交割. New makes 从实际的 MP4 中提取出第一/中/上个审查框架加上这些时间并返回 qcFrames 财务报告和审定财务报表 qcReportPath。对于批量组装,返回的框架清单还包括 " Remotion审查框架 " ;批量质量控制报告将其SHA约束的报告连接在下面 remotion. 抽样使用视频轨道持续时间,所以音频尾巴不能将帧推过图片. 框架/报告的散列情况在恢复时得到核实;丢失或更改的证据被拒绝。 没有QC散列的老年工作恢复,没有记录QC. 见 动议撰写 可编辑的 持续运动演示。两者都以现有的恢复路径为基础,没有其他技能或运行时间.

对于回旋批量渲染,成分必须被曝光 props.videoGenShotTimesSec 每个镜头ID有一个入胶片样本时间(秒). 它可能通过 defaultProps 或计算 calculateMetadata 从实际资产。 占位符在飞行前检查每个镜头在付费提交之前是否有有效时间;最后的QC使用所制成的成分返回的值. 默认 Concat 和 FFmpeg 时间表 QC 使用实际剪接或已解析的分段持续时间代替 .

保留 Remotion 源文件并导入到视频输出目录之外;该目录被排除在被冻结的项目指纹之外,因此其他工作不能使有报酬的工作无效. 如果输入点在输出目录内, 输出目录不能在工程目录内, 则拒绝输入点 public/ 树.

Remotion是由本地项目安装的,而不是用这个包来分配. 审查 退职执照 FAQ 在部署自动渲染服务之前,先说明项目的用途和组织.

源产品演示,见 构成部分整合 编辑 共享业务组成部分实例. 该实例还提供了可独立编辑的音乐/效果以样本-峰值校正和参考报告来源;其样本产品不是Pi的UI.

磁盘上的工作

<cwd>/.video-gen/<jobId>/
├── render-input.json   # immutable spec (revisions = new job dir)
├── assets.json         # semantic assets ↔ image_generate's real returned paths
├── manifest.json       # state + per-shot remote handles/local hashes + final SHA-256
├── shots/<shotId>/first_frame.png|last_frame.png|video.mp4
├── qc/shot_<shotId>.png # one frame per source shot with content hashes
├── qc/final_part_<n>.png # samples from the assembled MP4
├── assembly/            # separate child job for timeline or Remotion mode
└── final_video.mp4      # default concat mode; assembly modes return assembly/final_video.mp4

崩溃还是取消中途降落? 重运行相同的 spec 路径——生成射击手柄恢复通过 inspect 并检查当地枪声 与被冻结的内容散开。 已完成的任务验证其最后的 MP4 和 QC 散列而不是重编 。 全本地任务从指纹中省略模型/提供者,不需要 API 密钥 。 遗产 done 在没有保存的最后SHA-256的情况下显示其内容,无法验证其旧片;从所保存的片断中创建一个新的作曲工作。 取消只停止当地投票;远程任务可能继续运行和可收费。 如果提交完成度不明确,请使用 /video-gen recover <jobId> 检查提供者控制台后.

从预结构格式升级: 提供工作 render-input.json 仍然使用旧的 videoPrompt 字符串已无法解析或恢复(结构 prompt 对象故意替换,没有相容层。 如果飞行中付费的任务被升级所困住,则从提供者控制台手动下载其剪辑——任务URL过期(Ark:24h). 单剪工作不受影响:其被冻结 input.json 被读取,而不是重排.

结构化结果(Pi 0.99+)

所有四个工具都声明 outputSchema 返回范围 structuredContent;编码器直接接收对象. 生成返回 jobId, (中文(简体) ), state, (中文(简体) ), videoPath,且可用 taskId编号 :bytes; 组成/返回 jobId, (中文(简体) ), state, (中文(简体) ), finalVideoPath,及其现有的构成元数据. video_capabilities 曝光情况 activeId, (中文(简体) ), activeResolved, (中文(简体) ), provider, (中文(简体) ), keyReady, (中文(简体) ), capabilities, (中文(简体) ), models,以及 totalModels,没有提供者证书或URL.

qcStatus: "recorded" 表示结果包括现有的QC框架/报告路径. 这并不意味着通过人或目视检查. qcStatus: "not_performed" 覆盖单个片段, Concat, 或历史工作而不录入QC. 可用 qcFrames, (中文(简体) ), qcReportPath, (中文(简体) ), subtitlePath,直接返回可编辑的工程路径。 失败者返回 { error, truncated } 与 isError: true 并持续提供 jobId编号 :state编号 :taskId 或变相射击状态。 一项含糊不清或中断的有薪工作必须检查/恢复,而不是再次提交.

const image = await tools.image_generate({ prompt: "A blue product illustration" });
if (image.error) throw new Error(image.error);
await tools.write({ path: ".video-gen/demo/timeline-input.json", content: JSON.stringify({
  output: { resolution: "640x360", fps: 25 },
  segments: [{ id: "s1", image: image.images[0].path, durationSec: 1, motion: "static" }]
}) });
const video = await tools.video_compose({ composeSpecPath: ".video-gen/demo/timeline-input.json" });
if (video.error) throw new Error(video.error);
text({ path: video.finalVideoPath, qcStatus: video.qcStatus, frames: video.qcFrames });

示例的图像调用需要普通的图像提供器配置和授权. tests/structured-workflows.test.ts 在真实的 Pi 编码器中练习相同的链( )on 财务报告和审定财务报表 only)具有固定的图像提供器固定和真实的本地FFmpeg渲染,没有付费/网络生成.

结构化输出限于12个KiB,而顶级列表则限于100个完整的记录. truncated: true 表示省略的记录; total 保留已有的原始数。 超大小记录,带有 id 保留完整的ID和小分级元数据,省略大字段,并携带 truncated: true 在记录和信封上;呼叫者必须在重新使用内容进行更新之前检查该旗帜。 没有记录ID的超大小结果返回打出输出限制错误,而不是剪接路径或内容. 当发生这种情况时, 写入可能已经完成: 在重试前检查保存状态 。 可读文本和渲染器细节是独立限定的.

参考资料

• 华夏运动技巧:用于创意方向,运动节奏,音乐和出口审查的参考. pi-video-gen使用自己的工具和组成工作流程.

FFmpeg,编码器,和字体探测器同步运行并接受呼叫器取消. 同一并发的探测器共享一个进程;取消一个调用器会让其他调用器运行,最后被取消的调用器终止共享进程. 每个探测器有一个覆盖元数据搜索和处理等待的最后期限:二进制探测器5秒,全已知-font/fontconfig检查2秒. 儿童流程仅获得所余预算。 等待呼叫者可以取消或超时,即使文件系统元数据从未结算;后期元数据结果无法启动一个进程或充入缓存. 重叠调用者共享第一个过程所剩的运行时间,而他们自己的等待期限保持独立;最多32个成功结果被缓存30秒. 在明确的路径上替换二进制会使其缓存结果无效 。 字体检查同步检查已知的平台字体文件,并在引用字体配置前荣誉取消.