| name | agnes-video-gen |
| description | Agnes AI Video Generation API Reference — Video V2.0, text-to-video, image-to-video, keyframe animation. |
| agent_created | true |
Agnes AI · Video Generation API
Agnes AI 电影级视频生成模型，支持文生视频、图生视频、多图视频、关键帧动画，完全免费。
目录
快速开始
1. 获取 API Key
访问 platform.agnes-ai.com 注册，进入设置 → API 密钥。
2. 配置环境变量
export AGNES_API_KEY="sk-your-api-key"
3. 生成第一个视频
curl -X POST https://apihub.agnes-ai.com/v1/videos \
-H "Authorization: Bearer $AGNES_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "agnes-video-v2.0",
"prompt": "A cat walking on the beach at sunset, gentle waves, golden light",
"height": 768,
"width": 1152,
"num_frames": 121,
"frame_rate": 24
}'
curl https://apihub.agnes-ai.com/v1/videos/task_xxx \
-H "Authorization: Bearer $AGNES_API_KEY"
⚠️ 视频生成为异步流程：提交 → 轮询 → 取 remixed_from_video_id 获取视频 URL。
工作流模式
| 模式 | 说明 | 关键参数 |
|---|
文生视频 ti2vid | 纯文本描述生成视频 | prompt + mode: "ti2vid"（默认） |
| 图生视频 | 基于图片生成动态视频 | image 单张 URL |
| 多图视频 | 多张图片合成视频 | image 数组 |
关键帧动画 keyframes | 关键帧控制过渡 | extra_body.mode: "keyframes" + 多张图片 |
API 参考
Base
Base URL: https://apihub.agnes-ai.com/v1
Submit: POST /videos
Poll: GET /videos/{task_id}
Auth: Bearer <API_KEY>
Price: Free
创建任务参数
| 参数 | 类型 | 必填 | 说明 | 推荐值 |
|---|
model | string | ✅ | 固定 agnes-video-v2.0 | — |
prompt | string | ✅ | 视频内容文本描述 | — |
image | string / string[] | | 输入图片 URL，图生视频时必填 | — |
mode | string | | ti2vid（默认）/ keyframes | ti2vid |
height | integer | | 视频高度 | 768 |
width | integer | | 视频宽度 | 1152 |
num_frames | integer | | 总帧数，须为 8n+1 ≤ 441 | 121 |
num_inference_steps | integer | | 推理步数 | 默认 |
seed | integer | | 随机种子，固定可复现 | — |
frame_rate | number | | FPS，范围 1–60 | 24 |
negative_prompt | string | | 负向提示词，描述要避免的内容 | — |
extra_body.image | array | | 多图/关键帧时必须 | — |
extra_body.mode | string | | 关键帧时必须，填 "keyframes" | — |
创建任务响应
{
"id": "task_xxx",
"task_id": "task_xxx",
"object": "video",
"model": "agnes-video-v2.0",
"status": "queued",
"progress": 0,
"created_at": 1780457477,
"seconds": "5.0",
"size": "1152x768"
}
查询结果响应（完成时）
{
"id": "task_xxx",
"model": "agnes-video-v2.0",
"object": "video",
"status": "completed",
"progress": 100,
"seconds": "5.0",
"size": "1152x768",
"error": null,
"remixed_from_video_id": "https://storage.googleapis.com/.../video_xxxxxx.mp4"
}
⚠️ 最终视频 URL 在 remixed_from_video_id 字段，非 url。
num_frames 约束
num_frames 必须同时满足：
1. num_frames ≤ 441
2. num_frames = 8n + 1（n 为正整数）
合法值
| 81 | 121 | 161 | 201 | 241 | 281 | 321 | 361 | 401 | 441 |
|---|
❌ 100、150、200、300 等不满足 8n+1 的值均不合法。
视频时长对照表
时长 = num_frames / frame_rate
| 目标 | num_frames | frame_rate | 实际时长 |
|---|
| ~3 秒 | 81 | 24 | 3.38s |
| ~5 秒 | 121 | 24 | 5.04s |
| ~7 秒 | 161 | 24 | 6.71s |
| ~10 秒 | 241 | 24 | 10.04s |
| ~18 秒 | 441 | 24 | 18.38s |
技巧：想要更长视频 → 降低 frame_rate；想要更流畅 → 提高 frame_rate。
代码示例
文生视频 — Python
import httpx, os, time
API_KEY = os.environ["AGNES_API_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
resp = httpx.post(
"https://apihub.agnes-ai.com/v1/videos",
headers=HEADERS,
json={
"model": "agnes-video-v2.0",
"prompt": "A cinematic shot of waves crashing against rocks at sunset, slow motion, golden light, foam particles",
"height": 768,
"width": 1152,
"num_frames": 121,
"frame_rate": 24
},
timeout=30
)
task_id = resp.json()["task_id"]
print(f"任务已创建: {task_id}")
while True:
result = httpx.get(
f"https://apihub.agnes-ai.com/v1/videos/{task_id}",
headers=HEADERS
).json()
status = result["status"]
print(f"状态: {status} ({result.get('progress', 0)}%)")
if status == "completed":
print(f"视频: {result['remixed_from_video_id']}")
break
elif status == "failed":
print(f"失败: {result.get('error')}")
break
time.sleep(10)
文生视频 — Node.js
const API_KEY = process.env.AGNES_API_KEY;
const HEADERS = { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" };
async function generateVideo(prompt) {
const createResp = await fetch("https://apihub.agnes-ai.com/v1/videos", {
method: "POST",
headers: HEADERS,
body: JSON.stringify({
model: "agnes-video-v2.0",
prompt,
height: 768, width: 1152,
num_frames: 121, frame_rate: 24
})
});
const { task_id } = await createResp.json();
while (true) {
await new Promise(r => setTimeout(r, 10000));
const pollResp = await fetch(`https://apihub.agnes-ai.com/v1/videos/${task_id}`, { headers: HEADERS });
const data = await pollResp.json();
if (data.status === "completed") return data.remixed_from_video_id;
if (data.status === "failed") throw new Error(data.error);
console.log(`${data.status} (${data.progress}%)`);
}
}
const url = await generateVideo("A cat walking on the beach at sunset");
console.log(`Video: ${url}`);
图生视频 — Python
resp = httpx.post(
"https://apihub.agnes-ai.com/v1/videos",
headers={"Authorization": f"Bearer {os.environ['AGNES_API_KEY']}"},
json={
"model": "agnes-video-v2.0",
"prompt": "The character in the image slowly turns their head and smiles, gentle motion, cinematic lighting",
"image": "https://example.com/portrait.jpg",
"height": 768,
"width": 1152,
"num_frames": 81,
"frame_rate": 24
}
)
task_id = resp.json()["task_id"]
关键帧动画 — Python
resp = httpx.post(
"https://apihub.agnes-ai.com/v1/videos",
headers={"Authorization": f"Bearer {os.environ['AGNES_API_KEY']}"},
json={
"model": "agnes-video-v2.0",
"prompt": "Smooth transition between these keyframes, morphing from scene to scene",
"width": 1152,
"height": 768,
"num_frames": 161,
"frame_rate": 24,
"extra_body": {
"mode": "keyframes",
"image": [
"https://example.com/frame1.jpg",
"https://example.com/frame2.jpg",
"https://example.com/frame3.jpg"
]
}
}
)
可复现结果（fixed seed）
resp = httpx.post(
"https://apihub.agnes-ai.com/v1/videos",
headers={"Authorization": f"Bearer {os.environ['AGNES_API_KEY']}"},
json={
"model": "agnes-video-v2.0",
"prompt": "...",
"seed": 42,
"height": 768,
"width": 1152,
"num_frames": 121,
"frame_rate": 24
}
)
Prompt 写作指南
文生视频公式
主体 + 动作 + 场景 + 镜头运动 + 光照 + 风格
[Subject] + [Action/Motion] + [Scene] + [Camera Movement] + [Lighting] + [Style]
示例:
A lone samurai walking through a bamboo forest,
slow camera tracking shot from behind,
sunlight filtering through leaves, dust particles in the air,
cinematic realism, slow motion
最佳实践
- 描述运动：不要只说"一个人"，要说"一个人缓缓走过街道"
- 指定镜头：tracking shot / close-up / wide shot / aerial view
- 光照细节：golden hour / neon lights / soft diffused / dramatic backlight
- 避免复杂场景：单一主体 + 清晰动作效果最好
- 负向提示词：用
negative_prompt 排除模糊、抖动、变形等问题
图生视频
描述图片中哪些元素应运动，同时保持主体稳定
示例:
The water in the lake ripples gently,
leaves on the tree sway in the breeze,
while the mountain and sky remain completely still
任务状态
| 状态 | 说明 | 操作 |
|---|
queued | 排队等待 | 继续轮询 |
in_progress | 生成中 | 继续轮询 |
completed | ✅ 完成 | 从 remixed_from_video_id 获取视频 |
failed | ❌ 失败 | 查看 error 字段排查 |
推荐配置
| 场景 | width | height | num_frames | frame_rate |
|---|
| 标准视频 | 1152 | 768 | 121 | 24 |
| 短视频（社交） | 1152 | 768 | 81 | 24 |
| 流畅运动 | 1152 | 768 | 121 | 30 |
| 长视频 | 1152 | 768 | 241 | 24 |
| 可复现 | — | — | — | 设固定 seed |
错误处理
| 状态码 | 原因 | 解决方案 |
|---|
200 | 成功 | 检查 status 字段，轮询直到 completed |
400 | 参数无效 | 检查 num_frames 是否满足 8n+1 |
401 | Key 无效 | 检查 AGNES_API_KEY |
404 | 任务不存在 | 检查 task_id 是否正确 |
429 | 速率限制 | 等待后重试 |
500 | 服务端错误 | 等待后重试 |
503 | 服务繁忙 | 增加轮询间隔 |
相关链接
