# Agnes Video Gen

> Agnes AI Video Generation API Reference — Video V2.0, text-to-video, image-to-video, keyframe animation.

- Skill: `chenoneto/agnes-video-gen` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add chenoneto/agnes-video-gen`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chenoneto/agnes-video-gen/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: chenoneto (https://skillmd.com/u/chenoneto)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chenoneto/agnes-video-gen

---


# Agnes AI · Video Generation API

> [Agnes AI](https://agnes-ai.com) 电影级视频生成模型，支持文生视频、图生视频、多图视频、关键帧动画，**完全免费**。

## 目录

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

---

## 快速开始

### 1. 获取 API Key

访问 [platform.agnes-ai.com](https://platform.agnes-ai.com) 注册，进入设置 → API 密钥。

### 2. 配置环境变量

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

### 3. 生成第一个视频

```bash
# 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"` | — |

### 创建任务响应

```json
{
  "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"
}
```

### 查询结果响应（完成时）

```json
{
  "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

```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

```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

```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

```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）

```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": "...",
        "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 |