agnes-video-gen

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 电影级视频生成模型，支持文生视频、图生视频、多图视频、关键帧动画，完全免费。

目录

• 快速开始
• 工作流模式
• API 参考
• num_frames 约束
• 视频时长对照表
• 代码示例
• Prompt 写作指南
• 任务状态
• 推荐配置
• 错误处理

---

快速开始

1. 获取 API Key

访问 platform.agnes-ai.com 注册，进入设置 → API 密钥。

2. 配置环境变量

export AGNES_API_KEY="sk-your-api-key"

3. 生成第一个视频

# Step 1: 提交任务
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
  }'
# → { "task_id": "task_xxx", "status": "queued" }

# Step 2: 轮询结果（替换 task_id）
curl https://apihub.agnes-ai.com/v1/videos/task_xxx \
  -H "Authorization: Bearer $AGNES_API_KEY"
# → { "status": "completed", "remixed_from_video_id": "https://..." }

⚠️ 视频生成为异步流程：提交 → 轮询 → 取 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}"}

# Step 1: 提交任务
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}")

# Step 2: 轮询直到完成
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)  # 每 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,       # 固定 seed
        "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	服务繁忙	增加轮询间隔

---

相关链接

资源	地址
官网	https://agnes-ai.com
注册	https://platform.agnes-ai.com
API 文档	https://agnes-ai.com/doc/overview
视频文档	https://agnes-ai.com/doc/agnes-video-v20
API Base	https://apihub.agnes-ai.com/v1