Agnes AI 完全指南：免费多模态 API 为 AI Agent 注入文本/图片/视频全能力

多模态 AI 正在成为开发者工具箱的标配——AI Agent 需要理解图片、生成视频、处理各种媒体输入。但现实是，市面上的多模态 API 要么收费高昂，要么不兼容 OpenAI 标准，让集成变得繁琐。

Agnes AI 提供了一个不同的选择：完全免费的多模态 API 网关，兼容 OpenAI 接口规范，覆盖文本、图像、视频三大模态。你只需要一个 API Key，就可以在几分钟内为你的 AI Agent 接入完整的视觉和生成能力。

本文将从注册到实战，完整介绍 Agnes AI 的用法。

核心特性一览

快速开始

1. 注册账号

访问 platform.agnes-ai.com 注册账号。注册后在 Developer Dashboard 中生成一个 API Key，保存到安全位置。

2. 配置客户端

所有 API 请求使用统一的 Base URL 和认证方式：

Base URL: https://apihub.agnes-ai.com/v1
Authorization: Bearer ***

用 curl 测试连接：

curl https://apihub.agnes-ai.com/v1/chat/completions \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-2.0-flash",
    "messages": [{"role": "user", "content": "用中文介绍 Agnes AI"}],
    "stream": true
  }'

如果返回 401，检查 API Key 是否复制正确，Bearer 前缀是否完整。

文本模型：推理、编码与 Agent 工作流

Agnes AI 提供两款文本模型：

两个模型均支持 256K 上下文窗口和 64K 最大输出，以及流式传输（streaming）。

Python 示例：

from openai import OpenAI

client = OpenAI(
    base_url="https://apihub.agnes-ai.com/v1",
    api_key="your-api-key"
)

response = client.chat.completions.create(
    model="agnes-2.0-flash",
    messages=[{"role": "user", "content": "Explain how to integrate OpenAI-compatible APIs"}],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

没错——因为 API 是 OpenAI 兼容的，你可以直接使用标准的 openai Python 库，只需修改 base_url 和 api_key 即可。

工具调用（Function Calling）

agnes-2.0-flash 支持工具调用，这在构建 AI Agent 时尤为重要：

from openai import OpenAI

client = OpenAI(
    base_url="https://apihub.agnes-ai.com/v1",
    api_key="your-api-key"
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定城市的天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "城市名"}
                },
                "required": ["location"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="agnes-2.0-flash",
    messages=[{"role": "user", "content": "北京的天气怎么样？"}],
    tools=tools,
    tool_choice="auto"
)

if response.choices[0].message.tool_calls:
    tool_call = response.choices[0].message.tool_calls[0]
    print(f"调用的函数：{tool_call.function.name}")
    print(f"参数：{tool_call.function.arguments}")

图像生成：文生图与图生图

Agnes AI 提供两个图像模型：

文生图示例

curl https://apihub.agnes-ai.com/v1/images/generations \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "A luminous floating city above a misty canyon at sunrise, cinematic realism",
    "size": "1024x768"
  }'

图像模型支持从 1K 到 4K 的分辨率。免费用户在 1K 分辨率下有 20 RPM 的实际处理速率，4K 分辨率降至 1 RPM。

图生图（Image-to-Image）

通过传入参考图片 URL，可以实现基于已有图片的变体生成（具体参数格式请参考官方文档）。

视频生成：异步任务 API

视频生成是 Agnes AI 最有趣也最复杂的能力。它使用异步任务模式：

第一步：创建视频生成任务

curl -X POST https://apihub.agnes-ai.com/v1/videos \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "prompt": "A cinematic shot of a cat walking on the beach at sunset, soft ocean waves, warm golden lighting, realistic motion",
    "height": 768,
    "width": 1152,
    "num_frames": 121,
    "frame_rate": 24
  }'

参数说明：

• num_frames：最多 121 帧（约 5 秒 @ 24fps）
• frame_rate：推荐 24fps
• height/width：建议 768×1152（竖屏）或 1152×768（横屏）

第二步：轮询结果

API 返回一个 video_id，用此 ID 轮询结果：

GET https://apihub.agnes-ai.com/agnesapi?video_id=

注意：使用返回的 video_id 进行轮询，不要使用 task_id。这是当前推荐的查询方式。

将 Agnes AI 接入你的 Agent 工作流

Agnes AI 的 OpenAI 兼容意味着几乎所有支持 OpenAI 的 AI Agent 框架都可以直接接入。以下是几个使用场景：

在 Claude CLI / Codex 中使用

只需将 Base URL 和 API Key 配置为后端即可：

Models > Custom Provider
Base URL: https://apihub.agnes-ai.com/v1
API Key: 你的 API Key
Model: agnes-2.0-flash

在 Hermes Agents 中集成

Hermes Agents 有专门的集成指南（官方文档）。配置方式与 OpenAI 一致，只需替换 API 端点和模型名。

自定义 Agent 中的多模态处理

利用 agnes-2.0-flash 的视觉理解能力，可以实现：

1. 截图分析：将用户截图传递给模型，提取界面元素信息
2. 文档 OCR：扫描图片中的文字内容
3. 图像描述生成：为图片生成 Alt 文本或详细描述

response = client.chat.completions.create(
    model="agnes-2.0-flash",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "这张图片里有什么？"},
            {"type": "image_url", "image_url": {"url": "https://example.com/screenshot.png"}}
        ]
    }]
)

配额与定价

Agnes AI 对免费用户非常慷慨：

对于个人开发者和原型验证阶段，免费额度完全够用。

总结

Agnes AI 解决了一个实际问题：让开发者零成本接入多模态 AI 能力。它的 OpenAI 兼容性意味着几乎没有学习成本，三个模态的 API 设计都遵循行业标准，从 curl 到 Python SDK 都可以无缝切换。

如果你正在开发一个需要视觉理解的 AI Agent，或者想为你的工具加入图片/视频生成能力，Agnes AI 的免费额度是最低成本的试错方式——注册一个账号、生成 API Key、改两行代码，就能跑起来。

相关链接

• 官网
• 开发者文档
• API 平台
• GitHub 官方仓库
• 模型目录