用途
jimeng-api-video-gen 用于通过火山引擎（Volcengine）即梦视频 3.0 Pro API 生成高质量 AI 视频。当用户需要从文本提示词或图片生成视频时，可以使用该技能。
主要能力
该技能支持文本生成视频（t2v）和图片生成视频（i2v），并覆盖多个版本与模式：
Pro 版本（1080P HD）
- ti2v_pro（req_key: jimeng_ti2v_v30_pro）：文本生成视频 + 图片生成视频（首帧）Pro
1080P 版本
- t2v_1080p（jimeng_t2v_v30_1080p）：文本生成视频 1080P
- i2v_first_1080p（jimeng_i2v_first_v30_1080）：图片生成视频（首帧）1080P
- i2v_first_tail_1080p（jimeng_i2v_first_tail_v30_1080）：图片生成视频（首尾帧）1080P
720P 版本
- t2v_720p（jimeng_t2v_v30）：文本生成视频 720P
- i2v_first_720p（jimeng_i2v_first_v30）：图片生成视频（首帧）720P
- i2v_first_tail_720p（jimeng_i2v_first_tail_v30）：图片生成视频（首尾帧）720P
- i2v_recamera_720p（jimeng_i2v_recamera_v30）：图片生成视频（运镜）720P
视频规格
时长选项：4 秒（快速片段、社交媒体）、5 秒（默认，通用）、6 秒（短场景）、8 秒（中等长度内容）、10 秒（较长叙事）。 帧率选项：24（电影感，默认）、25（PAL 视频标准）、30（流畅运动，NTSC 标准）。
使用方式
配置环境变量
需要先获取 Access Key / Secret Key，并在 ~/.zshrc 或 ~/.zshenv 中配置：
export VOLC_ACCESSKEY="your_access_key_id"
export VOLC_SECRETKEY="your_secret_access_key"
命令行调用
scripts/generate_video.py PROMPT [OPTIONS]
参数：
- PROMPT：视频生成的文本提示词（必填）
- --mode MODE：生成模式（默认 t2v_720p），可选 ti2v_pro；t2v_1080p、i2v_first_1080p、i2v_first_tail_1080p；t2v_720p、i2v_first_720p、i2v_first_tail_720p、i2v_recamera_720p
- --duration SECS：视频时长：4、5、6、8、10（默认 5）
- --fps FPS：每秒帧数：24、25、30（默认 24）
- --image URL：图生视频（首帧）的输入图片 URL
- --tail-image URL：首尾帧模式的尾帧图片 URL
- --seed INT：可复现的随机种子
- --output PATH：将视频下载到文件
- --json：输出原始 JSON 响应
环境变量：
- VOLC_ACCESSKEY：Access Key ID（必填）
- VOLC_SECRETKEY：Secret Access Key（必填）
- JIMENG_VIDEO_API_URL：API 端点（默认 https://visual.volcengineapi.com）
- JIMENG_VIDEO_API_TIMEOUT：请求超时秒数（默认 300）
- JIMENG_VIDEO_POLL_INTERVAL：轮询间隔秒数（默认 5）
- JIMENG_VIDEO_MAX_POLL_ATTEMPTS：最大轮询次数（默认 120）
输出行为
视频生成成功后，必须直接向用户展示视频，并按以下格式输出：
Generated Video:
Download Video
Generation Info:
Prompt: [用户的原始提示词]
Duration: [视频长度，单位秒]
Mode: [使用的生成模式]
FPS: [每秒帧数]
Save Path: [本地文件路径，如适用]
示例输出：
Generated Video:
Download Video
Generation Info:
Prompt: A golden retriever running through a field of sunflowers, warm afternoon sunlight
Duration: 5 seconds
Mode: t2v_720p
FPS: 24
Save Path: /generated_videos/dog_sunflowers.mp4
API 配置
| 参数 | 值 | 说明 |
|---|---|---|
| Endpoint | https://visual.volcengineapi.com | API 基础 URL |
| Submit Action | CVSync2AsyncSubmitTask | 提交异步生成任务 |
| Query Action | CVSync2AsyncGetResult | 查询任务结果 |
| Version | 2022-08-31 | API 版本 |
| Service | cv | 签名用服务名 |
| Region | cn-north-1 | 签名用区域 |
鉴权
该技能使用火山引擎 IAM v4 签名认证（HMAC-SHA256）。签名流程：
- 使用请求头构建规范请求：content-type;host;x-content-sha256;x-date
- 计算规范请求的 SHA256 哈希
- 派生签名密钥：secret_key → date → region → service → "request"
- 使用派生密钥对 string-to-sign 签名
- 在请求中添加 Authorization 请求头
参考：HTTP请求示例（https://www.volcengine.com/docs/6444/1390583）
错误码
| 代码 | 消息 | 说明 |
|---|---|---|
| 10000 | Success | 请求成功 |
| 50411 | Pre Img Risk Not Pass | 输入图片未通过内容检查 |
| 50511 | Post Video Risk Not Pass | 输出视频未通过内容检查 |
| 50412 | Text Risk Not Pass | 输入文本未通过内容检查 |
| 50429 | Request Has Reached API Limit | 超过速率限制，稍后重试 |
| 50500 | Internal Error | 服务器错误 |
| timeout | Request timeout | 请求超时，增大 JIMENG_VIDEO_API_TIMEOUT |
输入/输出限制
输入图片（用于图片生成视频）：仅支持 JPEG、PNG 格式；每张图片最大 15MB；最大分辨率 4096×4096。
输出：格式为 MP4；URL 有效期为 24 小时；生成时间根据时长和模式约为 2 到 10 分钟。
适用场景
适用于需要从文本提示词或图片生成视频的场景，可按需选择不同分辨率（1080P、720P）、时长和帧率，并可选用首帧、首尾帧或运镜等图生视频模式。
限制
使用前必须配置火山引擎 Access Key 和 Secret Key；输入图片需符合格式、大小和分辨率限制；输出视频需经过内容检查；视频 URL 仅 24 小时有效。
参考文档
- Jimeng Video 3.0 Pro API Documentation（https://www.volcengine.com/docs/85621/1777001）
- Jimeng Video 3.0 720P API（https://www.volcengine.com/docs/85621/1792710）
- Jimeng Video 3.0 1080P API（https://www.volcengine.com/docs/85621/1792711）
- HTTP Request Example（https://www.volcengine.com/docs/6444/1390583）
- Volcengine Console（https://console.volcengine.com）
- API Key Management（https://console.volcengine.com/iam/key_manage/）