\r \r

Agnes Image & Video Skill\r

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

快速开始\r

\r

1. 配置 API Key\r

\r 在使用前，用户需要前往 Agnes API 平台 注册并创建 API Key，然后通过对话告知助手。\r \r API Key 以环境变量形式存储，在请求时注入到 Header 中：\r

Authorization: Bearer YOUR_API_KEY\r
```\r
\r
### 2. 通用 API 信息\r
\r
- **Base URL**: `https://apihub.agnes-ai.com/v1`\r
- **Content-Type**: `application/json`\r
- **认证**: `Authorization: Bearer {API_KEY}`\r
\r
---\r
\r
## 图像生成：Agnes-Image-2.0-Flash\r
\r
### 端点\r
\r
```\r
POST https://apihub.agnes-ai.com/v1/images/generations\r
```\r
\r
### 参数\r
\r
| 参数 | 类型 | 必填 | 说明 |\r
|------|------|------|------|\r
| `model` | string | 是 | `"agnes-image-2.0-flash"` |\r
| `prompt` | string | 是 | 图像生成的文本提示词 |\r
| `size` | string | 否 | 输出尺寸：`"1024x1024"`, `"1024x768"`, `"768x1024"` |\r
| `seed` | number | 否 | 随机种子，用于结果可复现 |\r
| `tags` | array | 否 | 任务类型标记 |\r
| `extra_body.image` | array | 图生图时是 | 输入图像 URL 数组（支持多张图合成） |\r
| `extra_body.response_format` | string | 否 | 输出格式：`"url"` |\r
\r
### 文生图\r
\r
```python\r
import httpx\r
\r
response = httpx.post(\r
    "https://apihub.agnes-ai.com/v1/images/generations",\r
    headers={"Authorization": "Bearer YOUR_API_KEY"},\r
    json={\r
        "model": "agnes-image-2.0-flash",\r
        "prompt": "一只可爱的金毛犬在阳光下的草地上微笑，高清摄影风格",\r
        "size": "1024x1024",\r
    }\r
)\r
result = response.json()\r
image_url = result["data"][0]["url"]\r
```\r
\r
### 图生图\r
\r
图生图**必须**在 `tags` 中添加 `"img2img"`，否则模型会当作文生图处理：\r
\r
```python\r
response = httpx.post(\r
    "https://apihub.agnes-ai.com/v1/images/generations",\r
    headers={"Authorization": "Bearer YOUR_API_KEY"},\r
    json={\r
        "model": "agnes-image-2.0-flash",\r
        "prompt": "将狗的衣服改成红色",\r
        "tags": ["img2img"],\r
        "extra_body.image": ["https://example.com/input.jpg"],\r
    }\r
)\r
```\r
\r
### 多图合成\r
\r
在 `extra_body.image` 中传入多个图像 URL：\r
\r
```python\r
response = httpx.post(\r
    "https://apihub.agnes-ai.com/v1/images/generations",\r
    headers={"Authorization": "Bearer YOUR_API_KEY"},\r
    json={\r
        "model": "agnes-image-2.0-flash",\r
        "prompt": "将两张图片合成为一张",\r
        "extra_body.image": ["https://example.com/img1.jpg", "https://example.com/img2.jpg"],\r
    }\r
)\r
```\r
\r
### 响应格式\r
\r
```json\r
{\r
  "created": 1774432125,\r
  "data": [\r
    { "url": "https://..." }\r
  ],\r
  "usage": { "generated_images": 1 }\r
}\r
```\r
\r
---\r
\r
## 视频生成：Agnes-Video-V2.0\r
\r
视频生成是**异步**过程，分为"创建任务"和"轮询结果"两步。\r
\r
### 端点\r
\r
- **创建任务**: `POST https://apihub.agnes-ai.com/v1/videos`\r
- **查询结果**: `GET https://apihub.agnes-ai.com/v1/videos/{task_id}`\r
\r
### 创建任务参数\r
\r
| 参数 | 类型 | 必填 | 说明 |\r
|------|------|------|------|\r
| `model` | string | 是 | `"agnes-video-v2.0"` |\r
| `prompt` | string | 是 | 视频内容的文本描述 |\r
| `image` | string/array | 否 | 输入图片 URL（图生视频时） |\r
| `mode` | string | 否 | `"ti2vid"` (文生视频) 或 `"keyframes"` (关键帧) |\r
| `height` | integer | 否 | 视频高度，默认 `768` |\r
| `width` | integer | 否 | 视频宽度，默认 `1152` |\r
| `num_frames` | integer | 否 | 视频总帧数，**必须满足 `8n+1` 且 `\x3C= 441`** |\r
| `num_inference_steps` | integer | 否 | 推理步数，使用默认值即可 |\r
| `seed` | integer | 否 | 随机种子 |\r
| `frame_rate` | number | 否 | 视频 FPS，推荐 `24` (范围 1-60) |\r
| `negative_prompt` | string | 否 | 负向提示词 |\r
| `extra_body.image` | array | 多图/关键帧时是 | 多图或关键帧的输入图片 URL |\r
| `extra_body.mode` | string | 关键帧时是 | `"keyframes"` |\r
\r
### 帧数合法值\r
\r
`num_frames` 必须满足：`8n + 1` (n 为正整数) 且 `num_frames ≤ 441`。\r
\r
**合法值**: 81, 121, 161, 201, 241, 281, 321, 361, 401, 441\r
\r
**非法值**: 100, 150, 200\r
\r
### 视频时长计算\r
\r
```\r
时长(秒) = num_frames / frame_rate\r
```\r
\r
例如 `num_frames=121`, `frame_rate=24` → 时长约 5.04 秒。\r
\r
### 完整调用流程\r
\r
```python\r
import httpx\r
import time\r
\r
# Step 1: 创建视频任务\r
create_resp = httpx.post(\r
    "https://apihub.agnes-ai.com/v1/videos",\r
    headers={"Authorization": "Bearer YOUR_API_KEY"},\r
    json={\r
        "model": "agnes-video-v2.0",\r
        "prompt": "一只猫在日落时的沙滩上散步，电影级镜头",\r
        "height": 768,\r
        "width": 1152,\r
        "num_frames": 121,\r
        "frame_rate": 24,\r
    }\r
)\r
task_id = create_resp.json()["task_id"]\r
\r
# Step 2: 轮询等待结果\r
while True:\r
    result = httpx.get(\r
        f"https://apihub.agnes-ai.com/v1/videos/{task_id}",\r
        headers={"Authorization": "Bearer YOUR_API_KEY"}\r
    )\r
    data = result.json()\r
    status = data.get("status")\r
\r
    if status == "completed":\r
        video_url = data.get("remixed_from_video_id")\r
        print(f"视频就绪: {video_url}")\r
        break\r
    elif status == "failed":\r
        print("生成失败:", data.get("error"))\r
        break\r
    else:\r
        time.sleep(5)  # 每5秒轮询一次\r
```\r
\r
### 响应格式\r
\r
**创建任务响应**:\r
```json\r
{\r
  "id": "task_xxx",\r
  "task_id": "task_xxx",\r
  "object": "video",\r
  "model": "agnes-video-v2.0",\r
  "status": "queued",\r
  "progress": 0,\r
  "created_at": 1780457477,\r
  "seconds": "5.0",\r
  "size": "1280x768"\r
}\r
```\r
\r
**完成时响应**:\r
```json\r
{\r
  "id": "task_xxx",\r
  "model": "agnes-video-v2.0",\r
  "status": "completed",\r
  "progress": 100,\r
  "seconds": "5.0",\r
  "size": "1280x768",\r
  "remixed_from_video_id": "https://storage.../video_xxxxxx.mp4"\r
}\r
```\r
\r
### 任务状态说明\r
\r
| 状态 | 说明 |\r
|------|------|\r
| `queued` | 排队中，继续轮询 |\r
| `in_progress` | 生成中，继续轮询 |\r
| `completed` | 完成，从 `remixed_from_video_id` 获取视频 URL |\r
| `failed` | 失败，检查 `error` 字段 |\r
\r
---\r
\r
## 使用脚本 (scripts/generate.py)\r
\r
本 skill 附带 Python 脚本 `scripts/generate.py`，可快速调用 API 生成图片或视频。\r
\r
### 使用方式\r
\r
```bash\r
# 设置环境变量\r
export AGNES_API_KEY="your-api-key-here"\r
\r
# 生成图片\r
python scripts/generate.py --mode image --prompt "一只可爱的小猫" --size 1024x1024\r
\r
# 生成视频\r
python scripts/generate.py --mode video --prompt "日落时海滩上的猫散步" --height 768 --width 1152 --num_frames 121 --frame_rate 24\r
```\r
\r
---\r
\r
## 注意事项\r
\r
1. **图生图必须加 `tags: ["img2img"]`**，否则模型会当作文生图处理\r
2. **视频 `num_frames` 必须满足 `8n+1` 且 `\x3C= 441`**，否则 API 会返回错误\r
3. 视频生成是异步的，需要轮询 `task_id` 获取结果\r
4. 所有 API 无限期免费，无需绑定信用卡\r
5. 生成的图片和视频默认以 URL 形式返回，下载后保存为本地文件\r