agnes-media

agnes-media

A DeepSeek Harness (dsh) plugin that registers
two host tools for the Agnes AI media models, so the agent can generate images
and videos during a conversation.

---

🌟 功能特性

• 文生图：使用 agnes-image-2.1-flash 模型生成高质量图片
• 文生视频：使用 agnes-video-2.5-flash 模型生成短视频（4-12秒）
• 免费无限：Agnes AI 提供永久免费的 API 调用
• 双端点支持：自动适配中国大陆和国际节点
• 零依赖：仅使用 Node.js 内置模块，无需额外安装

---

⚠️ 获取 API Key（重要！）

平台地址

地区	URL
中国大陆	platform.agnes-ai.cn
国际	platform.agnes-ai.com

两个平台使用同一个 API Key — 只需要切换端点 URL。

获取步骤

1. 登录与你所在地区匹配的平台
2. 进入 设置 → API 密钥（Settings → API Keys）
3. 点击 "创建新密钥"（Create New Key）
4. 重要：密钥只显示一次！立即复制保存！
5. 密钥格式为 sk-xxxxxxxx...（以 sk- 开头，约 50+ 字符）

常见问题：401 错误（"无效的令牌"）

如果你遇到 401 错误：

检查项	解决方案
复制完整？	确保完整复制 sk-... 字符串，不要截断
多余空格/换行？	去除首尾空格 — 确保没有多余空格
Key 已删除？	去设置 → API 密钥检查 Key 是否还存在
用错 Key？	创建新 Key 并重新测试
区域不匹配？	.cn Key 用于 .cn 端点，.com Key 用于 .com 端点

手动测试你的 Key

# 使用 curl 直接测试，排除插件配置问题
curl -s https://api.agnes-ai.cn/v1/models \
  -H "Authorization: Bearer YOUR_KEY_HERE" | head -c 500

如果返回模型数据，说明 Key 有效；如果返回 {"error":{"message":"无效的令牌"...}}，请重新生成 Key。

---

⚠️ API Key 与端点选择

获取你的 API Key

1. 在 Agnes AI 平台（国内节点）或 国际节点 注册
   • 中国大陆用户：使用 .cn 平台 — 速度更快，无需代理
   • 海外用户：使用 .com 平台
2. 在控制台设置 → API 密钥中创建 API Key
3. 同一个 Key 在 .cn 和 .com 节点都可用

选择合适的端点

默认情况下，插件连接国际节点（api.agnes-ai.com）。

如果你…	这样做
在中国大陆	启动 DSH 前设置 AGNES_MEDIA_DOMAIN=cn 使用国内节点（api.agnes-ai.cn）— 速度更快，无需代理
需要自定义端点	设置 AGNES_MEDIA_BASE_URL=https://your-custom-endpoint/v1
想保持国际默认	无需额外配置；只需设置你的 API Key

Windows PowerShell

$env:AGNES_API_KEY = "sk-xxxxxxxx..."
$env:AGNES_MEDIA_DOMAIN = "cn"   # 中国大陆用户添加这一行
dsh web

macOS / Linux

export AGNES_API_KEY="sk-xxxxxxxx..."
export AGNES_MEDIA_DOMAIN=cn     # 中国大陆用户取消注释这一行
dsh web

---

环境要求

• DeepSeek Harness 0.1.0-rc.7 或更高版本（使用 cordis.patch.yml bundle 格式）
• Agnes AI API Key（免费），通过 AGNES_MEDIA_API_KEY 或 AGNES_API_KEY 暴露

安装

从本地目录：

dsh plugin --profile web add github:LittleBeaverStudio/agnes-media

然后重启 DSH web 服务器。generate_image 和 generate_video 工具会出现在 agent 的工具目录中。

工具

generate_image

使用 agnes-image-2.1-flash 模型从文本提示生成图片。

参数：

• prompt（必需）：图片的详细文本描述。
• size（可选）：输出尺寸，格式为 "WxH"（如 "1920x1080"）或 "{width,1920},{height,1080}"。默认：1024x1024。
• n（可选）：生成的图片数量。默认：1，最大：4。

返回值： 公共 HTTPS URL 数组。工具将结果渲染为 markdown 图片，DSH Web UI 会内联显示。

generate_video

使用 agnes-video-2.5-flash 模型从文本提示生成短视频（新版）。

异步操作：提交任务后，每 3 秒轮询状态端点，直到视频生成完成（最多约 3 分钟）。

参数：

• prompt（必需）：视频的详细文本描述。包括主体、动作、场景、镜头运动、光线和风格。
• duration（可选）：目标时长（秒）。范围：4-12 秒，默认：5 秒。
• size（可选）：输出尺寸，格式为 "WxH"（如 "1280x720"）或 "{width,1280},{height,720}"。默认：1280x720。
• aspect_ratio（可选）：宽高比，支持 16:9（默认）、9:16、1:1、4:3、3:4、21:9。
• negative_prompt（可选）：要避免的内容（如 "模糊、抖动镜头"）。
• seed（可选）：随机种子，用于可重复生成。

返回值： 直接视频 URL。

宽高比说明

Agnes Video 2.5 Flash 支持以下宽高比：

宽高比	分辨率	适用场景
16:9	1280×720	横向视频（默认）
9:16	720×1280	竖屏短视频
1:1	720×720	正方形
4:3	960×720	传统比例
3:4	720×960	竖版海报
21:9	1680×720	超宽 cinematic

环境变量参考

变量	说明	默认值
AGNES_MEDIA_API_KEY	Agnes API Key（推荐）	(必须设置)
AGNES_API_KEY	备用 API Key	—
AGNES_MEDIA_DOMAIN	节点选择：cn 为国内，其他为国际	com
AGNES_MEDIA_BASE_URL	完整自定义 Base URL（覆盖域名）。必须以 /v1 结尾。	(自动从域名生成)

结果如何在对话中显示

• 图片：工具返回公共 HTTPS URL，其结果指示模型使用 markdown 图片语法（![description](url)）回复。DSH Web UI 会内联渲染绝对 HTTPS 图片，生成的图片会直接出现在对话中 — 无需客户端插件。
• 视频：工具返回直接视频 URL。markdown 渲染器没有视频块，因此 agent 会向用户展示链接；浏览器打开时会内联播放。

安全说明

• 永远不要提交 API Key。此仓库故意不包含任何密钥；.gitignore 排除了本地配置和环境文件。
• Key 仅以 Bearer header 形式离开你的机器，发送到 Agnes AI API。
• 插件在调用时从进程环境读取 Key；永远不会持久化或记录。

许可证

MIT

---

版本历史

版本	日期	更新内容
v1.4.0	2026-08-28	升级视频模型至 agnes-video-2.5-flash，支持宽高比参数
v1.2.0	2026-08-21	修正端点 URL：apihub.agnes-ai.cn → api.agnes-ai.cn
v1.1.1	2026-08-21	添加 API Key 获取指南和 401 错误排查表
v1.1.0	2026-08-21	支持国内外双端点，通过 AGNES_MEDIA_DOMAIN 切换
v1.0.1	2026-08-20	初始版本，修复 Agnes Video API 参数对齐问题