Agnes Video v2.0 AI视频生成 API 使用指南

!!! note "" Agnes AI 的视频生成 API，当前为免费使用期，支持 Text-to-Video、Image-to-Video 等多种模式。

基本信息

认证

在请求头中携带 Bearer Token：

Authorization: Bearer <your_api_key>

API Key 存储在服务器本地文件 ~/.agnes_api_key，备用 Key 存储在 ~/.agnes_api_key_old。

API 调用流程

整个流程分为两步：创建任务 → 轮询结果。

1. 创建视频生成任务

POST https://apihub.agnes-ai.com/v1/videos
Content-Type: application/json
Authorization: Bearer <your_api_key>

{
  "model": "agnes-video-v2.0",
  "prompt": "一只橘猫在草地上追蝴蝶，阳光明媚",
  "width": 1152,
  "height": 768,
  "num_frames": 121,
  "frame_rate": 24
}

成功返回：

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

2. 轮询任务状态

GET https://apihub.agnes-ai.com/v1/videos/{task_id}
Authorization: Bearer <your_api_key>

返回示例（进行中）：

{
  "status": "in_progress",
  "progress": 65
}

返回示例（完成）：

{
  "status": "completed",
  "progress": 100,
  "remixed_from_video_id": "https://..."
}

返回示例（失败）：

{
  "status": "failed",
  "progress": 0,
  "error": "error message"
}

请求参数

响应字段

输出规格

支持的功能模式

• Text-to-Video — 纯文本描述生成视频
• Image-to-Video — 参考图片生成视频
• Keyframe — 关键帧控制
• Scene Motion — 场景运动控制

注意事项

1. 每日调用次数限制 — 免费期有配额上限，超出后请求被拒绝
2. 准备多个 Key 备用 — 建议准备多个 API Key 轮流使用，避免单 Key 配额耗尽影响业务
3. 视频 URL 字段名 — 视频下载地址在 remixed_from_video_id 字段中，不是 video_url，注意不要找错字段
4. 异步轮询 — 视频生成需要时间（约 30–60 秒），建议每隔 5–10 秒轮询一次状态

快速示例（curl）

创建任务

curl -s -X POST https://apihub.agnes-ai.com/v1/videos \
  -H "Authorization: Bearer $(cat ~/.agnes_api_key)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "prompt": "日落海滩，海浪拍打沙滩，暖色调光线",
    "width": 1152,
    "height": 768,
    "num_frames": 121,
    "frame_rate": 24
  }'

轮询结果

TASK_ID="<上一步返回的task_id>"
curl -s https://apihub.agnes-ai.com/v1/videos/$TASK_ID \
  -H "Authorization: Bearer $(cat ~/.agnes_api_key)" | jq .

轮询直到完成

TASK_ID="<task_id>"
while true; do
  resp=$(curl -s https://apihub.agnes-ai.com/v1/videos/$TASK_ID \
    -H "Authorization: Bearer $(cat ~/.agnes_api_key)")
  status=$(echo "$resp" | jq -r '.status')
  progress=$(echo "$resp" | jq -r '.progress // 0')
  echo "Status: $status, Progress: $progress%"
  if [ "$status" = "completed" ] || [ "$status" = "failed" ]; then
    echo "$resp" | jq .
    break
  fi
  sleep 5
done

相关配置

API Key 管理方式见 API Key 管理。