Agnes Video Gen

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。

工作流模式

API 参考

Base

Base URL:  https://apihub.agnes-ai.com/v1
Submit:    POST /videos
Poll:      GET  /videos/{task_id}
Auth:      Bearer <API_KEY>
Price:     Free

创建任务参数

创建任务响应

{
  "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 为正整数）

合法值

❌ 100、150、200、300 等不满足 8n+1 的值均不合法。

视频时长对照表

时长 = num_frames / frame_rate

技巧：想要更长视频 → 降低 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

任务状态

推荐配置

错误处理

相关链接