简介:本文基于有限的Agnes接口测试,说明文本对话与文生图接口的接入方式,给出视频接口返回403时的排查顺序,并分析免费模式对开发者选型与成本控制的影响。读者可以拿到可直接运行的代码示例、生产环境的架构建议,以及降低单一厂商依赖风险的做法。
本文的结论来自有限的接口测试。测试时间、请求节点、完整参数和返回样本没有全部留存,因此下面的”可用””受限”表示测试当时的观察结果,不代表官方承诺。接入前请以官方文档和控制台的最新信息为准。
Agnes API 目前较推荐 https://apihub.agnes-ai.cn/v1 节点。测试中该节点提供 agnes-2.5-flash 文本模型,而 .com 节点尚未同步这一模型,两个节点的模型列表可能不同。调用前应先拉取模型列表确认。
| 能力 | 测试模型 | 观察结果 | 说明 |
|---|---|---|---|
| 文本对话 | agnes-2.0-flash、agnes-2.5-flash、agnes-2.5-pro-alpha | 可调用 | 接口兼容 OpenAI 格式 |
| 文生图 | agnes-image-2.0-flash、agnes-image-2.1-flash | 可调用 | 本次测试中 2.1-flash 表现较稳,样本量较小 |
| 文生视频 | agnes-video-v2.0 | 返回 403 | 测试时不能用于生产链路 |
免费额度、限流、并发上限和 SLA 没有在本次测试中逐项核实。这些信息对能否上生产影响很大,需要到服务商控制台或文档中确认。
文本接口路径为 POST /v1/chat/completions。先用 curl 确认密钥和模型可以正常调用:
curl https://apihub.agnes-ai.cn/v1/chat/completions \-H "Authorization: Bearer $AGNES_API_KEY" \-H "Content-Type: application/json" \-d '{"model": "agnes-2.5-flash","messages": [{"role": "user", "content": "hello"}]}'
已有 OpenAI SDK 的项目,通常只需替换 base_url 和 api_key:
import osfrom openai import OpenAIclient = OpenAI(api_key=os.environ["AGNES_API_KEY"],base_url="https://apihub.agnes-ai.cn/v1")resp = client.chat.completions.create(model="agnes-2.5-flash",messages=[{"role": "user", "content": "hello"}])print(resp.choices[0].message.content)
choices 是列表,必须用 choices[0] 取第一个候选结果。直接写成 resp.choices.message 会报错。API Key 从环境变量读取,不要写进代码。
接入时还要注意三点:
文生图接口路径为 POST /v1/images/generations,示例如下:
curl https://apihub.agnes-ai.cn/v1/images/generations \-H "Authorization: Bearer $AGNES_API_KEY" \-H "Content-Type: application/json" \-d '{"model": "agnes-image-2.1-flash","prompt": "minimalist product poster, soft light","size": "768x1152"}'
本次测试中,单张图片耗时约 15 到 30 秒。耗时受提示词复杂度、服务负载和图片尺寸影响。测试样本不多,这个数字不能当作稳定的性能指标。
因此业务系统不应让用户在页面上同步等待,推荐使用异步任务:
内容安全需要单独处理。接口能调用,不代表生成结果可以直接上线。业务方应在提交前过滤违规提示词,在生成后审核图片,在发布前拦截敏感内容。
agnes-video-v2.0 在测试中返回 403。这个状态码说明请求被拒绝,但没有说明原因。排查时按下面顺序进行,每一步只改变一个变量,方便定位。
视频接口的路径和参数请以官方文档为准。下面用占位路径演示最小复现请求:
```bash
curl -i https://apihub.agnes-ai.cn/v1