Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费

$Agnes AI$ （Sapiens AI 推出）把文本、图像、视频 API 长期免费开放 ------核心模型无过期限制 ，不绑卡、不充值也能用 ，一个 Key、一个 base_url 跑通三类能力。

一、免费到底怎么算？

问题	官方回答
API 免费吗？	核心模型长期免费，无过期限制
多模态也免费？	是。文本、图像、视频、多模态理解与生成均免费
免费用户有限制吗？	仅受 RPM 限制（每分钟请求次数），触顶后稍后重试
要充值吗？	注册送 $0.1 账户初始余额（供付费模型用）；调用免费模型不扣这笔余额；免费用户可直接跳过充值

一句话：注册拿 Key 就能免费用，不用先掏钱。

二、免费能调用什么？

官方 API 免费开放三类能力：

能力	官方描述	对应模型
文本生成与推理	高质量创作、逻辑推理、内容续写	`agnes-2.0-flash`
图像生成与编辑	文生高清图；修改、优化、局部编辑	`agnes-image-2.1-flash`（文生图） `agnes-image-2.0-flash`（图改图）
音画同步视频生成	连贯高质量视频；音频与画面精准同步，无需后期配音	`agnes-video-v2.0`

模型	免费用来干什么
`agnes-2.0-flash`	对话、代码、Agent 工具调用
`agnes-image-2.1-flash`	文生图、海报、概念视觉
`agnes-image-2.0-flash`	图改图、换背景、局部编辑
`agnes-video-v2.0`	短视频样片、分镜预演

免费的文本模型 agnes-2.0-flash 在 Claw-Eval（真实 Agent 场景评测：工具调用、多步规划、任务拆解）中表现不俗：

完整模型列表以控制台 Models 页面为准。

三、免费用起来：官方五步

第一步：创建账户

访问 platform.agnes-ai.com，邮箱或 Google / GitHub 注册。

第二步：生成 API Key

控制台路径：Settings → API Keys → Create new secret key

所有请求须在请求头携带：

makefile 复制代码

Authorization: Bearer YOUR_API_KEY

Key 属于敏感信息，只用环境变量管理，别提交进 Git。

第三步：充值（可跳过）

官方明确：免费用户可以直接跳过充值。

第四步：发第一个免费请求

bash 复制代码

# .env
AGNES_API_KEY=sk-xxxxxxxx
AGNES_BASE_URL=https://apihub.agnes-ai.com/v1

官方 curl：

bash 复制代码

curl https://apihub.agnes-ai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-2.0-flash",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Python------API 完全兼容 OpenAI 风格接口 ，改 base_url 即可：

python 复制代码

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AGNES_API_KEY"],
    base_url=os.environ["AGNES_BASE_URL"],
)

resp = client.chat.completions.create(
    model="agnes-2.0-flash",
    messages=[{"role": "user", "content": "用 Python 实现 LRU 缓存，附单元测试"}],
)
print(resp.choices[0].message.content)

第五步：按需扩展

控制台 Models 页确认可用模型
阅读接口文档（参数、响应、错误处理）
免费接入 Streaming （流式响应）和 Tool Calling（工具调用）

四、免费生图与生视频

以下示例沿用第三节已创建的 client （需先配好 AGNES_API_KEY 和 AGNES_BASE_URL）。

图片（免费）

文生图------比如生成「小猫在足球场上踢足球」：

python 复制代码

img = client.images.generate(
    model="agnes-image-2.1-flash",
    prompt="一只可爱的小猫在绿茵足球场上踢足球，阳光明媚，动感瞬间，高清摄影风格",
    size="1024x1024",
)
print(img.data[0].url)

图改图------先拿上文文生图返回的小猫踢球图片 URL，再传入 extra_body.image 做二次编辑（agnes-image-2.0-flash）。指令写清「保留什么、改什么」：

python 复制代码

# 1. 上文文生图已得到原图 URL
original_url = img.data[0].url

# 2. 基于原图编辑：保留小猫踢球动作，改场景
edit = client.images.generate(
    model="agnes-image-2.0-flash",
    prompt="保留小猫踢足球的动作和足球不变，把场景改成傍晚的专业足球场，看台有观众，球场灯光亮起，电影感",
    size="1024x1024",
    extra_body={
        "image": [original_url]
    },
)
print(edit.data[0].url)

同一原图还可以试不同改法：

「保留小猫和足球，改成水彩插画风格」
「保留主体，背景换成下雪的冬日球场」
「在画面右侧再加一只小猫作为守门员」

视频（免费）

图生视频------拿上文图改图得到的小猫踢球静态图，继续生成动态短片；音画同步，无需后期配音。

硬约束：num_frames 必须是 8n+1 （81 / 121 / 161 / 241）。视频走 /v1/videos 端点，异步任务 ，创建后轮询 GET /v1/videos/{task_id} 取结果。

python 复制代码

import time

# 3. 创建图生视频任务
task = client.post(
    "/videos",
    body={
        "model": "agnes-video-v2.0",
        "prompt": "一只可爱的小猫在傍晚的专业足球场上踢球，看台有观众，球场灯光亮起，电影感",
        "image": edit.data[0].url,
        "num_frames": 121,
        "frame_rate": 24,
        "height": 768,
        "width": 1152,
    },
    cast_to=object,
)
task_id = task["id"]

# 4. 轮询直到完成
while True:
    result = client.get(f"/videos/{task_id}", cast_to=object)
    if result["status"] == "completed":
        print(result["remixed_from_video_id"])  # 视频 URL
        break
    time.sleep(10)

五、免费接进 Claude Code / Cursor / Agent

任何支持自定义 Base URL 的工具都能免费用。其中 Claude Code + CC-Switch 是官方文档重点推荐的接入方式，配置完成后在 Claude Code 交互框架里直接走 Agnes 免费模型。

官方手册：Claude CLI 接入方法

CC-Switch + Claude Code（推荐）

$CC-Switch$ 是社区开源的 CLI 供应商管理工具，一键切换 Claude Code、Codex、Gemini CLI 等工具的 API 配置。用它把 Claude Code 的请求经本地路由转发到 Agnes API Gateway，底层实际调用 agnes-2.0-flash，全程免费（注意 RPM）。

前置条件：

已安装 Claude Code（Claude CLI）
已安装 CC-Switch（GitHub Releases 下载对应系统安装包）
已有 Agnes API Key
若系统里手动设过 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_BASE_URL，先清除，避免与 CC-Switch 冲突

配置步骤

步骤	操作
1. 拿 Key	platform.agnes-ai.com → API Key 页面创建并复制
2. 打开 CC-Switch	顶部工具栏选择 Claude CLI
3. 添加供应商	右上角 `+` → Claude Provider → Custom Provider
4. 填 API Key	粘贴 Agnes Key（一般无需手动加 `Bearer` 前缀）
5. 请求地址	`https://apihub.agnes-ai.com/v1`
6. API 格式	OpenAI Chat Completions
7. 认证字段	默认即可；手动填时用 `ANTHROPIC_AUTH_TOKEN`
8. 模型映射	点「获取模型列表」确认连通后，推荐映射如下
9. 自定义参数	见下方 JSON（提高兼容性）
10. 保存	确认各项无误后保存，列表出现 Agnes 条目
11. 开路由	Route → Local Route → 启用 Claude 路由开关
12. 启用	供应商列表找到 Agnes Provider，点击启用
13. 验证	打开 Claude Code，发起对话或编码任务，确认走 Agnes 模型

模型映射（官方推荐）：

复制代码

Sonnet  →  agnes-2.0-flash
Opus    →  agnes-2.0-flash
Haiku   →  agnes-2.0-flash

自定义参数（避免 Claude Code 与 OpenAI 兼容接口的参数冲突）：

json 复制代码

{
  "allowed_openai_params": [
    "thinking",
    "context_management"
  ],
  "litellm_settings": {
    "drop_params": true
  }
}

启用后，Claude Code 的请求经 CC-Switch 转发到 Agnes API Gateway，用免费文本模型完成本地 Agent 和编码任务。

常见问题（官方排查要点）：

现象	检查项
无法获取模型列表	Base URL 是否为 `https://apihub.agnes-ai.com/v1`
鉴权失败	API Key 是否正确、是否过期
请求报错 / 参数不兼容	自定义参数是否已加 `drop_params`
Claude Code 没走 Agnes	CC-Switch 路由是否开启、Agnes Provider 是否已启用
响应异常	模型映射是否指向 `agnes-2.0-flash`

Cursor

Settings → Models → Add Custom Model

配置项	值
Base URL	`https://apihub.agnes-ai.com/v1`
API Key	你的 Key
Model ID	`agnes-2.0-flash`

LangChain / 其他 Agent

python 复制代码

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="agnes-2.0-flash",
    openai_api_key=os.environ["AGNES_API_KEY"],
    openai_api_base=os.environ["AGNES_BASE_URL"],
)

Hermes、Aider 等终端 Agent 填 OPENAI_API_KEY + base_url + model 三项即可。

一套 Key 跑全模态

arduino 复制代码

文本（agnes-2.0-flash）
    ↓
图片（agnes-image-2.1-flash）
    ↓
视频（agnes-video-v2.0）

三个模态共用同一 Key 和 Base URL，全程不扣费（注意 RPM）。

六、踩坑备忘

问题	处理
请求被拒 / 429	触达 RPM 上限，加 `sleep` 或队列后重试
视频报错	检查 `num_frames` 是否为 8n+1
图改图效果差	指令写清保留区、修改区、光照
Key 泄露	只用环境变量，不进 Git；丢失后在控制台重新生成
Claude Code 没走 Agnes	检查 CC-Switch 路由是否开启、Provider 是否已启用
接口参数对不上	以官方文档为准

简要总结

免费范围：文本、生图、生视频长期免费，不绑卡、不充值可用，仅 RPM 限制
最短路径 ：注册 → 创建 API Key → 跳过充值 → curl / Python 跑通 agnes-2.0-flash
核心模型 ：agnes-2.0-flash / agnes-image-2.1-flash / agnes-image-2.0-flash / agnes-video-v2.0
Claude Code ：CC-Switch + 官方接入手册
官方文档 ：agnes-ai.com/doc