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.5-flash 模型生成高质量图片
- 文生视频：使用
agnes-video-2.5-flash 模型生成 4-12 秒短视频（默认 5 秒）
- 图生视频：传入
reference_image_url（单图）或 reference_image_urls（多图数组，最多 5 张）即可使用参考图，支持 429 限流退避重试
- 免费无限：Agnes AI 提供免费 API 调用
- 国内直连：实测
api.agnes-ai.com/.cn 旧节点均 404/401，默认统一走 apihub.agnes-ai.cn
- 凭证集成：支持环境变量或 DSH credentials 系统
- 零依赖：仅使用 Node.js 内置模块，无需额外安装
⚠️ 获取 API Key（重要！）
平台地址
两个平台各自签发 Key — 注意 Key 与节点存在代际绑定，并非处处通用（见下文「API Key 与端点选择」的实测表格）。
获取步骤
- 登录与你所在地区匹配的平台
- 进入 设置 → API 密钥（Settings → API Keys）
- 点击 "创建新密钥"（Create New Key）
- 重要：密钥只显示一次！立即复制保存！
- 密钥格式为
sk-xxxxxxxx...（以 sk- 开头，约 50+ 字符）
常见问题：401 错误（"无效的令牌"）
如果你遇到 401 错误：
| 检查项 | 解决方案 |
|---|
| 复制完整？ | 确保完整复制 sk-... 字符串，不要截断 |
| 多余空格/换行？ | 去除首尾空格 — 确保没有多余空格 |
| Key 已删除？ | 去设置 → API 密钥检查 Key 是否还存在 |
| 用错 Key？ | 创建新 Key 并重新测试 |
| 区域不匹配？ | .cn Key 用于 .cn 端点，.com Key 用于 .com 端点 |
手动测试你的 Key
# 使用 curl 直接测试，排除插件配置问题
curl -s https://apihub.agnes-ai.cn/v1/models \
-H "Authorization: Bearer YOUR_KEY_HERE" | head -c 500
如果返回模型数据，说明 Key 在该节点有效；如果返回 {"error":{"message":"无效的令牌"...}}，
先换一个端点重试（见下文实测表格——Key 与节点有代际绑定），换节点仍 401 再重新生成 Key。
⚠️ API Key 与端点选择
获取你的 API Key
- 在 Agnes AI 平台（国内节点）或 国际节点 注册
- 中国大陆用户：使用
.cn 平台 — 速度更快，无需代理
- 海外用户：使用
.com 平台
- 在控制台设置 → API 密钥中创建 API Key
- 创建 API Key（Key 与签发它的节点存在代际绑定，见下方实测表格）
选择合适的端点
端点现状（2026-09-02 实测，中国大陆网络，platform.agnes-ai.cn 签发的 key）：
节点与 key 存在代际绑定，同一把 key 并非在所有节点都有效：
| 端点 | 实测结果 |
|---|
api.agnes-ai.cn | ✅ 200（旧平台体系 key 的正确节点） |
apihub.agnes-ai.cn — 本插件默认 | ❌ 401 无效的令牌（对上述 key） |
apihub.agnes-ai.com | ✅ 200 |
api.agnes-ai.com | ❌ 404 |
本插件默认指向 apihub.agnes-ai.cn（对 dsh 生态新签发的 key 有效）。
遇到 401 无效的令牌 时先换端点、再换 key：设置
AGNES_MEDIA_BASE_URL=https://api.agnes-ai.cn 通常即可恢复。
AGNES_MEDIA_DOMAIN 保留仅为向后兼容，不再影响端点选择。
| 如果你… | 这样做 |
|---|
| 在中国大陆 | 无需任何配置，默认即 apihub.agnes-ai.cn |
| 在海外 / 需要自定义端点 | 设置 AGNES_MEDIA_BASE_URL=https://apihub.agnes-ai.com（插件会自动追加 /v1） |
| 使用 DSH credentials | 在 DSH 凭证管理中添加 AGNES_MEDIA_API_KEY |
Windows PowerShell
$env:AGNES_API_KEY = "sk-xxxxxxxx..."
# 国内无需额外配置；海外用户取消下一行注释
# $env:AGNES_MEDIA_BASE_URL = "https://apihub.agnes-ai.com"
dsh web
macOS / Linux
export AGNES_API_KEY="sk-xxxxxxxx..."
# 国内无需额外配置；海外用户取消下一行注释
# export AGNES_MEDIA_BASE_URL=https://apihub.agnes-ai.com
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 credentials 系统（支持图形界面配置 API Key）
安装
从本地目录：
dsh plugin --profile web add github:LittleBeaverStudio/agnes-media
然后重启 DSH web 服务器。generate_image 和 generate_video 工具会出现在 agent 的工具目录中。
工具
generate_image
使用 agnes-image-2.5-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 秒轮询一次 /agnesapi 状态端点，直到视频生成完成（最多约 6 分钟；12 秒任务实测推理约 2 分钟）。
参数：
prompt（必需）：视频的详细文本描述。包括主体、动作、场景、镜头运动、光线和风格。duration（可选）：目标时长（秒）。范围：4-12，默认：5。aspect_ratio（可选）：宽高比，"16:9"（默认）、"9:16"、"1:1"、"4:3"、"3:4"、"21:9"。size（可选）：分辨率档位。Flash 模型固定 720P，插件会自动传 "720P"。reference_image_url（可选）：公网可访问的 HTTPS 图片 URL。传入即走 mode=reference 图生视频，并放入 images[]；不传走 mode=text。注意：Agnes 不接受本地文件路径。seed（可选）：随机种子，用于可重复生成。negative_prompt（可选，保留）：参数定义保留以避免调用报错，但 Agnes 2.5 Flash 接口会 400 拒收该字段，插件不会实际发送。
返回值： 直接视频 URL（按 metadata.url → url → video_url → data.url 依次回退提取）。
宽高比说明
Agnes Video 2.5 Flash 固定 720P，支持以下宽高比：
| 宽高比 | 分辨率 | 适用场景 |
|---|
| 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（推荐，也可存到 DSH credentials） | (必须设置) |
AGNES_API_KEY | 备用 API Key | — |
AGNES_MEDIA_BASE_URL | 完整自定义 Base URL（海外/自定义端点用）。插件自动追加 /v1 | https://apihub.agnes-ai.cn |
AGNES_MEDIA_DOMAIN | 已保留但不再影响端点（实测旧节点 404/401，统一走 apihub） | — |
DSH Credentials 支持
插件支持从 DSH 凭证系统读取 API Key，无需设置环境变量：
- 在 DSH Web UI 中打开设置
- 进入 凭证管理（Credentials）
- 添加新凭证：
AGNES_MEDIA_API_KEY = sk-xxxxxxxx...
- 保存后重启 DSH
凭证优先级：环境变量 > DSH credentials > 错误提示
结果如何在对话中显示
- 图片：工具返回公共 HTTPS URL，其结果指示模型使用 markdown 图片语法（
）回复。DSH Web UI 会内联渲染绝对 HTTPS 图片，生成的图片会直接出现在对话中 — 无需客户端插件。
- 视频：工具返回直接视频 URL。markdown 渲染器没有视频块，因此 agent 会向用户展示链接；浏览器打开时会内联播放。
安全说明
- 永远不要提交 API Key。此仓库故意不包含任何密钥；
.gitignore 排除了本地配置和环境文件。
- Key 仅以
Bearer header 形式离开你的机器，发送到 Agnes AI API。
- 插件在调用时从进程环境读取 Key；永远不会持久化或记录。
- 如果使用 DSH credentials，Key 会加密存储在本地凭证数据库中。
版本历史
| 版本 | 日期 | 更新内容 |
|---|
| v1.8.3 | 2026-09-02 | 文生图模型升级 agnes-image-2.1-flash → agnes-image-2.5-flash（最新） |
| v1.8.2 | 2026-09-02 | 修复 AGNES_MEDIA_BASE_URL 双 /v1（传 /v1 结尾值会打出 /v1/v1 得到误导性 404，现幂等兼容两种写法）；实测修正端点文档：key 与节点存在代际绑定（platform 签发的 key 在 apihub.agnes-ai.cn 401、在 api.agnes-ai.cn 200），401 时先换端点再换 key；negative_prompt 参数描述标注为 DEPRECATED（API 400 拒收该字段，插件从不发送） |
| v1.8.1 | 2026-09-01 | 修复多图参考支持：index.js 代码已包含 reference_image_urls 数组参数，兼容旧 reference_image_url，最多 5 张参考图 |
| v1.8.0 | 2026-09-01 | 新增多图参考支持（README + package.json，index.js 遗漏未提交） |
| v1.7.0 | 2026-09-01 | 新增 429 限流退避重试：瞬态错误（429/5xx/网络抖动）退避 10 秒继续轮询，不再直接报错；轮询间隔 3s→5s，上限约 10 分钟 |
| v1.6.0 | 2026-09-01 | 实测修复：默认端点统一 apihub.agnes-ai.cn；视频切换到 agnes-video-2.5-flash（seconds/mode/size='720P'/aspect_ratio 参数）；新增图生视频 reference_image_url；轮询改为 /agnesapi?video_id=&model_name=；轮询上限 3→6 分钟；停止发送 negative_prompt |
| v1.5.0 | 2026-08-31 | 修正端点 URL 到 apihub，支持 DSH credentials 系统 |
| 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 参数对齐问题 |
许可证
MIT
