【国际域名 .com】Agnes AI 国际站接入 WorkBuddy · 零基础向导（生图 + 生视频）
> 节点标签：国际域名 .com 节点（国际站） · 文本生图 / 文生视频 / 图生视频
> 给谁用：零基础 AI 爱好者，一步步把 Agnes AI 国际站（.com）接进 WorkBuddy，既能生图、又能生视频。
> 🔒 安全承诺：本技能包不含任何 API 密钥。密钥由你自己去国际站官网创建，只在你本机 ~/.workbuddy/.apikeys.env 里保存。
> 与 .cn 的区别：本包接的是国际站（platform.agnes-ai.com / api.agnes-ai.com / apihub.agnes-ai.com）；中国站（.cn）是另一个独立包 yrns-agnes-gen，密钥平台与 API 主机都不同，两个包互不干扰。
一、它能做什么
Agnes AI 国际站（.com）接入后，你可在 WorkBuddy 里：
- 写文案 / 推理：文本模型 Agnes-2.0-Flash
- 文本生图 / 图生图：agnes-image-2.1-flash
- 文生视频 / 图生视频：agnes-video-v2.0（异步任务，自动轮询）
> 国际站官网：https://agnes-ai.com/ ｜ 开发者文档：https://agnes-ai.com/doc/overview
> ⚠️ 节点提醒（最容易踩坑）：Agnes 国际站有两个 API 主机 api.agnes-ai.com 与 apihub.agnes-ai.com，Key 与主机是绑定的，用错会 401。你不用自己选——本技能的接线脚本会自动探测哪台主机接受你的 Key 并写入配置。
二、零基础第一步：打开国际站官网，自己创建 API 密钥
- 打开国际站 API 平台：👉
https://platform.agnes-ai.com→ 用邮箱注册 / 登录（支持 QQ、Gmail）。 - 进入「设置 → API 密钥」→ 点「创建新的密钥」，命名后保存。
- 立即复制 ⚠️：密钥以
sk-开头，只显示一次，关掉页面就只能重新生成。先存进记事本备用。
> 🔒 安全提醒：密钥是你的私人凭证，不要发到聊天框或公开仓库。接线后它会写进你本机两处：~/.workbuddy/.apikeys.env（仅存密钥）与 ~/.workbuddy/models.json（WorkBuddy 调用模型所必需，含明文 key）。两处文件接线脚本都会收紧为仅当前用户可读写；请勿把 models.json 分享或提交到仓库。
三、零基础第二步：让技能帮你接进 WorkBuddy
python "C:\Users\Administrator\.workbuddy\skills\yrns-agnes-gen-com\scripts\wire_agnes_com.py"
运行后会让你粘贴密钥（输入时不显示）；或避免进命令行历史：
python "C:\Users\Administrator\.workbuddy\skills\yrns-agnes-gen-com\scripts\wire_agnes_com.py" --key-file "C:\Users\Administrator\Desktop\agnes_com_key.txt"
脚本自动完成（你什么都不用管）：
1. 逐个探测候选主机（/models 看谁返回 200），选中你 Key 所属的正确主机——避免 401。
2. 写 ~/.workbuddy/.apikeys.env → AGNES_COM_API_KEY=sk_... + AGNES_COM_BASE_URL=<探测到的主机>
（注意：用 AGNES_COM_* 而不是 .cn 包的 AGNES_*，两个站互不覆盖）
3. 写 ~/.workbuddy/models.json → 新增/更新 Agnes-2.0-Flash 文本模型（聊天框下拉可选）
4. 联网验证，只打印 HTTP 状态与尾号指纹，绝不回显完整密钥
看到 [完成] Agnes AI 国际站已接入 WorkBuddy 即成功。
四、零基础第三步：生图 / 生视频
生图（文生图，可下载到本地）：
python "C:\Users\Administrator\.workbuddy\skills\yrns-agnes-gen-com\scripts\generate_image.py" ^
--prompt "一座赛博朋克风格的城市夜景，霓虹灯闪烁，雨水反射蓝紫光影" ^
--size 1024x1024 --download --output "C:\Users\Administrator\Desktop\agnes_com_img.png"
生视频（文生视频 / 图生视频，异步轮询 + 可下载）：
python "C:\Users\Administrator\.workbuddy\skills\yrns-agnes-gen-com\scripts\generate_video.py" ^
--prompt "一只猫在夕阳下的海滩上散步，海浪轻拍，暖金色光线" ^
--width 1152 --height 768 --num-frames 121 --frame-rate 24 --download ^
--output "C:\Users\Administrator\Desktop\agnes_com_video.mp4"
- 图生视频：在上面的命令里加
--image <公开可访问的图片 URL>。 - 模型精确名字（拼错会 503）：生图
agnes-image-2.1-flash、生视频agnes-video-v2.0。若某模型名返回 503，请以https://agnes-ai.com/doc/overview当前文档为准。
五、故障排查（速查）
| 现象 | 根因 | 处理 |
|---|---|---|
| 新 Key 报 401，但 Key 确实有效 | 主机用错（Key 与主机绑定） | 重跑带自动探测的 wire_agnes_com.py；或显式 --base-url https://api.agnes-ai.com/v1 |
| 脚本报"未找到 API Key" | .apikeys.env 未写 / wire 没跑 |
重跑 wire_agnes_com.py 写入 AGNES_COM_API_KEY |
| 生图模型 503 | 模型名拼错 | 用精确名 agnes-image-2.1-flash，或查 agnes-ai.com/doc/overview |
| 视频偶发 403/503 | 国际站视频不稳定 | 重试；或直接在网页版 agnes-ai.com 做视频 |
六、接口要点（给想深入了解的人）
| 能力 | 方法 / 路径 | 关键参数 |
|---|---|---|
| 生图 | POST {base}/images/generations |
model, prompt, size, n；返回 data[].url |
| 创建视频 | POST {base}/videos |
model, prompt, image?, height, width, num_frames, frame_rate；返回 video_id |
| 查询视频 | GET {root}/agnesapi?video_id= |
root = base 去掉 /v1；status=="completed" 时 metadata.url 为视频地址 |
完整契约、模型名与历史踩坑见 references/api_reference.md。
Resources
scripts/wire_agnes_com.py— 自动探测主机 + 一键写入并验证（安全：不回显 key）。scripts/generate_image.py— 文本生图 / 图生图，支持下载。scripts/generate_video.py— 文生视频 / 图生视频，异步轮询，支持下载。references/api_reference.md— 接口契约、模型名、踩坑。
