Agnes AI 国际版 API 配置指南:文生文/图/视频三族接入

一、简介与适用场景

Agnes AI 国际版（agnes-ai.com）提供文生文 / 文生图 / 文生视频三族模型的聚合网关，形制为 New API（OpenAI 兼容）。对本站用户最大的价值是两条：

图像全档 $0、视频 $0/秒，当前限免（原价 $0.025/秒），适合低成本打样 AI 图像/视频玩法；
CORS 已实测放行浏览器跨域（2026-09-28 curl 验证：OPTIONS 预检 204 + Access-Control-Allow-Origin: *，连 401 响应都带 CORS 头），意味着本站「图像生成工坊」「视频生成工坊」可以浏览器直连，不需要任何服务器中转。

📖 官方文档：wiki.agnes-ai.com —— 有 llms.txt 索引，页面加 .md 后缀可直取纯文本（中文页 /zh-Hans/docs/xxx.md）。模型清单、免费额度与限流策略以官方控制台与文档为准，本文数字为 2026-09 实测口径。

与国内版（agnes-ai.cn）账号互不通用，Key 不能混用。本文基于 2026-09-28 的实抓核实，取代 2026-08-23 的占位版记录。

二、注册与获取 Key

打开 agnes-ai.com 注册账号。
进入控制台找到 API Keys 入口，创建密钥并完整复制（多数平台只完整展示一次）。
免费额度：图像/视频为限免政策，文本走平台 credits——额度政策可能调整，以控制台实际显示为准。

三、Base URL 与鉴权

Base URL：https://apihub.agnes-ai.com/v1（实测口径；旧记录中的 api.agnes-ai.com 未在实测中出现，勿用）
鉴权方式：Authorization: Bearer <你的 Key>
端点：对话 /chat/completions · 图像 /images/generations · 视频 POST /videos（创建）+ /agnesapi?video_id=...&model_name=...（轮询）

四、模型族清单

模型标识	模态	说明
agnes-2.0-flash / agnes-2.5-flash / agnes-2.5-pro / agnes-2.5-pro-beta / agnes-3.0-flash	文本	OpenAI 完全兼容，`/chat/completions` 即插即用
agnes-image-2.5-flash	图像生成	文生图 / 图生图 / 多图合成，`size` 档位 1K-4K、`ratio` 8 种
agnes-video-2.5-flash	视频	4-12 秒 720P，text / keyframe / reference 三种模式，异步两段式

五、curl 示例

对话（OpenAI 完全兼容）：

curl https://apihub.agnes-ai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -d '{"model": "agnes-2.5-flash", "messages": [{"role": "user", "content": "用一句话解释什么是 API"}]}'

图像（注意坑：response_format 不能放顶层，必须放 extra_body；参考图按官方示例放 extra_body.image）：

curl https://apihub.agnes-ai.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -d '{
    "model": "agnes-image-2.5-flash",
    "prompt": "雪山脚下的木屋，黄昏，胶片质感",
    "size": "2K",
    "ratio": "16:9",
    "return_base64": true
  }'

视频（两段式：创建拿 video_id，再轮询；seconds 是字符串、size 仅接受 720P）：

# ① 创建任务
curl https://apihub.agnes-ai.com/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -d '{"model": "agnes-video-2.5-flash", "prompt": "航拍海岸线，日落", "seconds": "5", "mode": "text", "size": "720P", "aspect_ratio": "16:9"}'

# ② 轮询（1-2 秒一次；status=completed 后取顶层 url）
curl "https://apihub.agnes-ai.com/agnesapi?video_id=<上一步返回的ID>&model_name=agnes-video-2.5-flash" \
  -H "Authorization: Bearer $AGNES_API_KEY"

Python / Node.js 走 OpenAI SDK 时，base_url 填 https://apihub.agnes-ai.com/v1 即可；图像与视频接口 SDK 未覆盖，直接用 HTTP 请求（SDK 调用时把文档里 extra_body 内的字段传给 OpenAI SDK 的 extra_body 参数）。

六、浏览器直连（本站工具联动）

实测结论：网关放行浏览器跨域，纯静态站可以直连。本站的联动路径：

「AI 配置」点 Agnes AI 云端预设 → 地址自动填入；
注册后把控制台生成的 Key 粘贴保存（只存你本机浏览器）；
「图像生成工坊」「视频生成工坊」「模型对话台」会自动带上这套连接。

红线口径：本站不预置任何 Key，请求由你的浏览器直发网关，站点服务器不经手密钥与素材。

七、常见错误排查

错误	现象	原因	解决方案
401	请求被拒	Key 缺失 / 错误 / 用了国内版 Key	用国际版控制台创建的 Key，注意前后空格
400	`detail` 形错误体	参数不合规（size 非 1K-4K、seconds 不是 4-12 字符串、参考图超量等）	按本文示例核对参数；非法请求不建任务不计费
400	图像接口拒绝	`response_format` 放了顶层（坑）	必须放 `extra_body.response_format`；参考图放 `extra_body.image`
429	限流	限免期间高峰	等几秒重试；文本侧减少并发
404	路径不存在	Base URL 写成 `api.agnes-ai.com` 或少了 `/v1`	用 `https://apihub.agnes-ai.com/v1`
轮询无果	一直 running	排队偶发较长	等待或稍后继续轮询，不要重复创建任务

⚠️ 限免风险提示：图像全档 $0 与视频 $0/秒均为限免政策，随时可能恢复原价或调整额度；文生文按平台 credits 计费。接入前以官方控制台实际展示为准，不要在依赖免费额度的生产链路里硬编码这些假设。