agnes-image-video

API key required

使用 Agnes AI 的 Agnes-Image-2.0-Flash 模型生成和编辑图片，以及使用 Agnes-Video-V2.0 模型生成视频。支持文生图、图生图、文生视频、图生视频、多图合成等场景。当用户需要 AI 生成图片、编辑图片、生成视频，或明确提到使用 Agnes Image / Agnes Video 模型时触发此 skill。

Install

openclaw skills install agnes-image-video

Agnes Image & Video Skill

使用 Agnes AI 全模态 API 进行图片和视频生成。Agnes AI 无限期免费开放文本、图像、视频三大模态 API，OpenAI 兼容接口。

快速开始

1. 配置 API Key

在使用前，用户需要前往 Agnes API 平台注册并创建 API Key，然后通过对话告知助手。

API Key 以环境变量形式存储，在请求时注入到 Header 中：

Authorization: Bearer YOUR_API_KEY

2. 通用 API 信息

Base URL: https://apihub.agnes-ai.com/v1
Content-Type: application/json
认证: Authorization: Bearer {API_KEY}

图像生成：Agnes-Image-2.0-Flash

端点

POST https://apihub.agnes-ai.com/v1/images/generations

参数

参数	类型	必填	说明
`model`	string	是	`"agnes-image-2.0-flash"`
`prompt`	string	是	图像生成的文本提示词
`size`	string	否	输出尺寸：`"1024x1024"`, `"1024x768"`, `"768x1024"`
`seed`	number	否	随机种子，用于结果可复现
`tags`	array	否	任务类型标记
`extra_body.image`	array	图生图时是	输入图像 URL 数组（支持多张图合成）
`extra_body.response_format`	string	否	输出格式：`"url"`

文生图

import httpx

response = httpx.post(
    "https://apihub.agnes-ai.com/v1/images/generations",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "agnes-image-2.0-flash",
        "prompt": "一只可爱的金毛犬在阳光下的草地上微笑，高清摄影风格",
        "size": "1024x1024",
    }
)
result = response.json()
image_url = result["data"][0]["url"]

图生图

图生图必须在 tags 中添加 "img2img"，否则模型会当作文生图处理：

response = httpx.post(
    "https://apihub.agnes-ai.com/v1/images/generations",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "agnes-image-2.0-flash",
        "prompt": "将狗的衣服改成红色",
        "tags": ["img2img"],
        "extra_body.image": ["https://example.com/input.jpg"],
    }
)

多图合成

在 extra_body.image 中传入多个图像 URL：

response = httpx.post(
    "https://apihub.agnes-ai.com/v1/images/generations",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "agnes-image-2.0-flash",
        "prompt": "将两张图片合成为一张",
        "extra_body.image": ["https://example.com/img1.jpg", "https://example.com/img2.jpg"],
    }
)

响应格式

{
  "created": 1774432125,
  "data": [
    { "url": "https://..." }
  ],
  "usage": { "generated_images": 1 }
}

视频生成：Agnes-Video-V2.0

视频生成是异步过程，分为"创建任务"和"轮询结果"两步。

端点

创建任务: POST https://apihub.agnes-ai.com/v1/videos
查询结果: GET https://apihub.agnes-ai.com/v1/videos/{task_id}

创建任务参数

参数	类型	必填	说明
`model`	string	是	`"agnes-video-v2.0"`
`prompt`	string	是	视频内容的文本描述
`image`	string/array	否	输入图片 URL（图生视频时）
`mode`	string	否	`"ti2vid"` (文生视频) 或 `"keyframes"` (关键帧)
`height`	integer	否	视频高度，默认 `768`
`width`	integer	否	视频宽度，默认 `1152`
`num_frames`	integer	否	视频总帧数，必须满足 `8n+1` 且 `<= 441`
`num_inference_steps`	integer	否	推理步数，使用默认值即可
`seed`	integer	否	随机种子
`frame_rate`	number	否	视频 FPS，推荐 `24` (范围 1-60)
`negative_prompt`	string	否	负向提示词
`extra_body.image`	array	多图/关键帧时是	多图或关键帧的输入图片 URL
`extra_body.mode`	string	关键帧时是	`"keyframes"`

帧数合法值

num_frames 必须满足：8n + 1 (n 为正整数) 且 num_frames ≤ 441。

合法值: 81, 121, 161, 201, 241, 281, 321, 361, 401, 441

非法值: 100, 150, 200

视频时长计算

时长(秒) = num_frames / frame_rate

例如 num_frames=121, frame_rate=24 → 时长约 5.04 秒。

完整调用流程

import httpx
import time

# Step 1: 创建视频任务
create_resp = httpx.post(
    "https://apihub.agnes-ai.com/v1/videos",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "agnes-video-v2.0",
        "prompt": "一只猫在日落时的沙滩上散步，电影级镜头",
        "height": 768,
        "width": 1152,
        "num_frames": 121,
        "frame_rate": 24,
    }
)
task_id = create_resp.json()["task_id"]

# Step 2: 轮询等待结果
while True:
    result = httpx.get(
        f"https://apihub.agnes-ai.com/v1/videos/{task_id}",
        headers={"Authorization": "Bearer YOUR_API_KEY"}
    )
    data = result.json()
    status = data.get("status")

    if status == "completed":
        video_url = data.get("remixed_from_video_id")
        print(f"视频就绪: {video_url}")
        break
    elif status == "failed":
        print("生成失败:", data.get("error"))
        break
    else:
        time.sleep(5)  # 每5秒轮询一次

响应格式

创建任务响应:

{
  "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": "1280x768"
}

完成时响应:

{
  "id": "task_xxx",
  "model": "agnes-video-v2.0",
  "status": "completed",
  "progress": 100,
  "seconds": "5.0",
  "size": "1280x768",
  "remixed_from_video_id": "https://storage.../video_xxxxxx.mp4"
}

任务状态说明

状态	说明
`queued`	排队中，继续轮询
`in_progress`	生成中，继续轮询
`completed`	完成，从 `remixed_from_video_id` 获取视频 URL
`failed`	失败，检查 `error` 字段

使用脚本 (scripts/generate.py)

本 skill 附带 Python 脚本 scripts/generate.py，可快速调用 API 生成图片或视频。

使用方式

# 设置环境变量
export AGNES_API_KEY="your-api-key-here"

# 生成图片
python scripts/generate.py --mode image --prompt "一只可爱的小猫" --size 1024x1024

# 生成视频
python scripts/generate.py --mode video --prompt "日落时海滩上的猫散步" --height 768 --width 1152 --num_frames 121 --frame_rate 24

注意事项

图生图必须加 tags: ["img2img"]，否则模型会当作文生图处理
视频 num_frames 必须满足 8n+1 且 <= 441，否则 API 会返回错误
视频生成是异步的，需要轮询 task_id 获取结果
所有 API 无限期免费，无需绑定信用卡
生成的图片和视频默认以 URL 形式返回，下载后保存为本地文件