Agnes AI 技能

通过 Agnes AI 平台 API（https://apihub.agnes-ai.com/v1）生成图像与视频。所有模型均可免费使用。

快速参考

前提条件

1. 在 platform.agnes-ai.com 获取 API 密钥
2. 配置方式（优先级顺序）：
   • 方式 1（推荐）： 编辑 config.json 文件，设置 "api_key": "your-api-key"
   • 方式 2： 设置环境变量 AGNES_API_KEY=sk-...
   • 方式 3： 在技能目录下的 .env 文件中添加 AGNES_API_KEY=sk-...
3. 基础 URL：https://apihub.agnes-ai.com/v1
4. 认证方式：Authorization: Bearer YOUR_API_KEY

图像生成

文本生成图像（Text-to-Image）

仅使用文本生成图像时，请调用 agnes-image-2.1-flash 模型。

接口地址： POST /v1/images/generations

请求体：

{
  "model": "agnes-image-2.1-flash",
  "prompt": "一只可爱的小猫在绿茵足球场上踢足球，阳光明媚，动感瞬间，高清摄影风格",
  "size": "1024x1024",
  "seed": null
}

响应体：

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

图像编辑（Img2Img）

对已有图像进行编辑或执行多图合成时，请使用 agnes-image-2.0-flash 模型。

接口地址： POST /v1/images/generations

请求体：

{
  "model": "agnes-image-2.0-flash",
  "prompt": "保留小猫踢足球的动作和足球不变，把场景改成傍晚的专业足球场",
  "size": "1024x768",
  "tags": ["img2img"],
  "extra_body": {
    "image": ["https://example.com/source-image.jpg"],
    "response_format": "url"
  }
}

关键参数说明：

• tags: ["img2img"] — 图像到图像模式必需
• extra_body.image — 图像 URL 数组（支持单张或多张参考图像）
• seed — 设置固定值以获得可复现结果

支持的尺寸： 1024x768、1024x1024、768x1024

视频生成

视频生成使用 agnes-video-v2.0 模型，且为异步操作：需先创建任务，再轮询获取结果。

支持的模式： 文本生成视频（Text-to-Video）、图像生成视频（Image-to-Video）、关键帧动画（Keyframe Animation）

创建视频任务

接口地址： POST /v1/videos

请求体：

{
  "model": "agnes-video-v2.0",
  "prompt": "一只可爱的小猫在傍晚的专业足球场上踢球",
  "image": "https://example.com/source-image.jpg",
  "num_frames": 121,
  "frame_rate": 24,
  "height": 768,
  "width": 1152
}

硬性约束： num_frames 必须满足 8n+1 形式，最大值为 441（例如：81、121、161、241、441）。

时长计算公式： seconds = num_frames / frame_rate → 121 帧 @ 24fps ≈ 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": "1152x768"
}

重要提示： 请保存 task_id（或 id，二者值相同），用于后续轮询结果。

轮询结果

接口地址： GET /v1/videos/{task_id}

状态生命周期：queued → in_progress → completed / failed

响应体（已完成时）：

{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "status": "completed",
  "progress": 100,
  "seconds": "5.0",
  "size": "1152x768",
  "error": null,
  "remixed_from_video_id": "https://storage.../video_xxx.mp4"
}

重要提示： 视频下载地址位于 remixed_from_video_id 字段中 —— 而非 video_url 或 url。这是 API 文档中已知的不一致问题。

视频参数说明

实现模式（仅使用标准库，无需 httpx）

import urllib.request, json, time

BASE_URL = "https://apihub.agnes-ai.com/v1"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# 步骤 1：创建任务
payload = {
    "model": "agnes-video-v2.0",
    "prompt": prompt,
    "num_frames": 121,
    "frame_rate": 24,
    "height": 768,
    "width": 1152,
}
if image_url:
    payload["image"] = image_url

req = urllib.request.Request(
    f"{BASE_URL}/videos",
    data=json.dumps(payload).encode("utf-8"),
    headers=headers,
    method="POST"
)
resp = urllib.request.urlopen(req, timeout=120)
task = json.loads(resp.read().decode("utf-8"))
task_id = task["task_id"]  # 同样可通过 task["id"] 获取
print(f"任务已创建：{task_id} | 时长：{task['seconds']}s")

# 步骤 2：轮询直至完成（5 秒视频生成耗时约 2–3 分钟）
while True:
    time.sleep(30)
    poll_req = urllib.request.Request(
        f"{BASE_URL}/videos/{task_id}",
        headers=headers,
        method="GET"
    )
    result = json.loads(urllib.request.urlopen(poll_req, timeout=60).read().decode("utf-8"))
    status = result["status"]
    progress = result.get("progress", 0)
    print(f"  状态：{status} | 进度：{progress}%")
    
    if status == "completed":
        # ⚠️ 下载地址在 remixed_from_video_id 中，而非 video_url 或 url
        video_url = result.get("remixed_from_video_id") or result.get("video_url") or result.get("url")
        print(f"完成！视频地址：{video_url}")
        break
    elif status == "failed":
        raise Exception(f"视频生成失败：{result.get('error')}")

Python SDK 替代方案

该 API 完全兼容 OpenAI SDK：

from openai import OpenAI

client = OpenAI(
    api_key=API_KEY,
    base_url="https://apihub.agnes-ai.com/v1"
)

# 图像生成
img = client.images.generate(
    model="agnes-image-2.1-flash",
    prompt="A futuristic city",
    size="1024x1024",
)
print(img.data[0].url)

# 视频生成
task = client.post(
    "/videos",
    body={
        "model": "agnes-video-v2.0",
        "prompt": "A cat playing soccer",
        "image": img.data[0].url,
        "num_frames": 121,
    },
    cast_to=object,
)
task_id = task["id"]
# 轮询：client.get(f"/videos/{task_id}", cast_to=object)

限制与注意事项

• 无服务等级协议（SLA）： 免费计划不保证可用性；高峰期可能出现 500/502/503 错误
• 视频排队： 视频生成为异步操作，可能存在队列等待时间
• 每分钟请求数（RPM）限制： 免费用户受每分钟调用次数限制；必要时请加入退避重试逻辑
• 无计费机制： 所有模型均免费，不消耗账户余额
• 安全性： API 密钥应存于环境变量中，切勿提交至 Git 仓库

选型指南

使用工作流

1. 用户发起图像或视频生成请求
2. 向用户索取提示词（如为 Img2Img 或视频生成，还需索取源图像）
3. 构建并发送 HTTP 请求（通过 Python 脚本或直接调用 API）
4. 图像生成：直接返回响应中的 URL
5. 视频生成：持续轮询直至 status == "completed"，然后返回视频 URL