简介:面向零基础开发者,提供 Agnes AI 免费 API 接入实操思路:先核验免费额度、限速与商用边界,再完成密钥配置、文本、图像和视频调用,并补齐异步轮询、报错排查、重试与安全提示,帮助读者快速跑通并理解多模态 API 开发流程。
在开始写代码之前,建议先明确一个前提:免费 API 适合学习、验证想法和制作 Demo,但免费策略可能随活动、账号、模型或服务条款变化。因此,不要把“免费”理解为永久可用,也不要默认免费接口一定可以商用。接入 Agnes AI 前,应优先到官方控制台、开发者文档或服务条款中核验以下信息。
| 核验项 | 需要确认什么 | 建议核验位置 |
|---|---|---|
| 免费额度 | 是否有免费 Token、免费图片次数、免费视频时长或赠送额度 | Agnes AI 控制台、费用页、活动页 |
| 速率限制 | 每分钟或每天最多调用多少次,是否有并发限制 | 官方文档、429 报错说明、控制台配额页 |
| 适用期限 | 免费权益是否有活动期限、体验期限或到期自动失效 | 官方活动页、邮件通知、服务条款 |
| 是否可商用 | 生成内容能否用于商业项目、是否允许二次分发或对外售卖 | 服务条款、商用授权说明、官方工单 |
如果官方页面没有清楚说明,不要凭经验猜测,应通过官方渠道确认。本文不提供未经核实的免费额度承诺,也不把示例代码视为最终生产方案。所有接口地址、模型名称、参数尺寸和返回字段,都应以你当前登录 Agnes AI 后看到的最新官方文档为准。
建议零基础读者按下面清单逐项执行:
API Key 相当于调用凭证,不能写死在前端代码中,也不能提交到 Git 仓库。本地开发推荐使用环境变量。例如:
export AGNES_API_KEY="你的API Key"
Windows PowerShell 可临时设置:
$env:AGNES_API_KEY="你的API Key"
如果需要长期管理,建议使用操作系统密钥链、后端配置中心或密钥管理服务。生产环境中,建议所有调用都通过你的后端服务代理完成,不要让用户浏览器直接持有密钥。
文本生成是最适合入门的接口,可用于问答、摘要、文案生成、代码解释、信息抽取等任务。下面示例不写死具体接口地址和模型名,而是要求你从官方文档中获取真实值并写入环境变量。这样可以避免占位符导致误解,也更接近实际工程做法。
import osimport requestsapi_key = os.getenv("AGNES_API_KEY")endpoint = os.getenv("AGNES_CHAT_ENDPOINT") # 从官方文档复制model = os.getenv("AGNES_CHAT_MODEL") # 从官方文档复制if not api_key or not endpoint or not model:raise SystemExit("请先设置 AGNES_API_KEY、AGNES_CHAT_ENDPOINT、AGNES_CHAT_MODEL")headers = {"Authorization": f"Bearer {api_key}","Content-Type": "application/json"}payload = {"model": model,"messages": [{"role": "user", "content": "请用一句话解释什么是大模型 API"}],"temperature": 0.3,"max_tokens": 256}response = requests.post(endpoint, headers=headers, json=payload, timeout=30)print(response.status_code)print(response.json())
不同平台的返回结构可能不同,下面是一个常见的成功响应示意,仅用于帮助你理解字段含义。真实字段请以官方文档为准。
{"id": "chatcmpl-demo-001","object": "chat.completion","choices": [{"index": 0,"message": {"role": "assistant","content": "大模型 API 是开发者通过接口调用大模型能力的服务方式。"},"finish_reason": "stop"}],"usage": {"prompt_tokens": 18,"completion_tokens": 21,"total_tokens": 39}}
关键字段通常可以看 choices、message.content、usage。如果你要接入业务,不要只打印整个 JSON,而应提取你真正需要的内容。
如果密钥错误,可能返回 401。下面是常见错误结构示意:
{"error": {"type": "authentication_error","code": "invalid_api_key","message": "Invalid API Key"}}
如果请求过快,可能返回 429:
{"error": {"type": "rate_limit_error","code": "too_many_requests","message": "Rate limit exceeded"}}
| 参数 | 作用 | 建议 |
|---|---|---|
model |
指定模型名称 | 必须从官方文档复制,不要自行猜测 |
messages |
对话上下文 | 多轮对话时保留历史消息 |
temperature |
控制随机性 | 问答、抽取任务可低一些,创意文案可高一些 |
max_tokens |
限制输出长度 | 避免输出过长导致超时、截断或费用增加 |
stream |
是否流式返回 | 实时交互场景可考虑,但会增加解析复杂度 |
多轮对话可以在 messages 中继续追加历史内容:
messages = [{"role": "system", "content": "你是一个专业的技术助手"},{"role": "user", "content": "什么是 Token?"},{"role": "assistant", "content": "Token 是大模型处理文本的基本单位。"},{"role": "user", "content": "那 API 调用中的 Token 是什么意思?"}]
在正式请求前,建议先做一次基础自检:
import osapi_key = os.getenv("AGNES_API_KEY")if not api_key:raise SystemExit("未检测到 AGNES_API_KEY,请检查环境变量是否生效")
如果请求返回 401,可以按以下顺序排查:
Authorization: Bearer <API_KEY>。401 一般不建议自动重试,因为重试通常不会让错误密钥变成正确密钥。
调用 API 时应避免“失败就一直重试”。更稳妥的做法是:只有限流、服务端临时异常或网络超时才考虑重试,并设置最大重试次数、指数退避和最终失败处理。
import timeimport requestsdef request_with_backoff(method, url, headers=None, json=None, retries=3, timeout=30):delay = 2for attempt in range(retries):try:response = requests.request(method=method,url=url,headers=headers,json=json,timeout=timeout)if response.status_code in (429, 500, 502, 503, 504):if attempt == retries - 1:response.raise_for_status()time.sleep(min(delay, 30))delay *= 2continueresponse.raise_for_status()return responseexcept requests.RequestException as e:if attempt == retries - 1:raise RuntimeError(f"请求最终失败:{e}")time.sleep(min(delay, 30))delay *= 2raise RuntimeError("重试次数已用尽")
建议遵循以下边界:
图像生成接口常用于海报、插画、产品图、概念图、头像和素材草案。接入时通常需要提交提示词,并根据接口返回结果获取图片地址、图片数据或任务 ID。
下面代码同样不写死接口地址、模型名和尺寸,而是从环境变量读取:
import osimport requestsapi_key = os.getenv("AGNES_API_KEY")endpoint = os.getenv("AGNES_IMAGE_ENDPOINT")model = os.getenv("AGNES_IMAGE_MODEL")size = os.getenv("AGNES_IMAGE_SIZE")if not api_key or not endpoint or not model or not size:raise SystemExit("请先设置图像接口相关环境变量")headers = {"Authorization": f"Bearer {api_key}","Content-Type": "application/json"}payload = {"model": model,"prompt": "未来城市夜景,霓虹灯,电影感,高清细节,无文字","size": size}response = requests.post(endpoint, headers=headers, json=payload, timeout=60)print(response.status_code)print(response.json())
{"created": 1710000000,"data": [{"url": "https://example.com/generated-image.png","revised_prompt": "未来城市夜景,霓虹灯,电影感,高清细节"}]}
如果接口是异步任务模式,则可能返回任务 ID:
{"task_id": "task-demo-001","status": "pending"}
若返回任务 ID,应保存该 ID,后续通过查询接口获取结果。如果既没有图片地址,也没有任务 ID,应检查官方文档中的真实返回结构,不要继续盲目轮询。
一个较完整的提示词通常包含以下要素:
示例:
一只机械猫坐在未来城市天台上,赛博朋克风格,霓虹灯反射,电影级光影,高清细节,无文字
对于 4K 或更高分辨率需求,务必先确认官方支持哪些尺寸枚举。不要随意填写未在文档中出现的尺寸,否则可能触发 400 参数错误。
短视频生成通常比文本和图像更耗时,因此多数平台会采用“创建任务—查询状态—获取结果”的异步模式。零基础读者最容易犯的错误是写 while True 无限轮询,这可能导致请求堆积、频率超限或程序长时间挂起。
下面示例加入最大轮询次数、退避等待和任务 ID 缺失处理:
import osimport timeimport requestsapi_key = os.getenv("AGNES_API_KEY")create_url = os.getenv("AGNES_VIDEO_CREATE_ENDPOINT")query_url = os.getenv("AGNES_VIDEO_QUERY_ENDPOINT")model = os.getenv("AGNES_VIDEO_MODEL")if not api_key or not create_url or not query_url or not model:raise SystemExit("请先设置视频接口相关环境变量")headers = {"Authorization": f"Bearer {api_key}","Content-Type": "application/json"}payload = {"model": model,"prompt": "清晨的城市街道,阳光穿过树叶,镜头缓慢推进"}create_response = requests.post(create_url, headers=headers, json=payload, timeout=60)create_data = create_response.json()task_id = create_data.get("task_id")if not task_id:raise ValueError("创建任务未返回 task_id,请核对官方返回字段")task_query_url = f"{query_url}/{task_id}"max_attempts = 30for attempt in range(max_attempts):result = requests.get(task_query_url, headers=headers, timeout=30).json()status = result.get("status")if status in ("completed", "success"):print("任务完成:", result)breakif status in ("failed", "error", "canceled"):print("任务失败:", result)breakwait_seconds = min(2 ** min(attempt, 4), 30)print(f"当前状态:{status},{wait_seconds} 秒后重查")time.sleep(wait_seconds)else:print("超过最大轮询次数,请稍后手动查询任务状态")
| 报错 | 可能原因 | 解决方法 |
|---|---|---|
401 Unauthorized |
API Key 错误、缺失、过期或无权限 | 检查环境变量、请求头和密钥状态 |
400 Bad Request |
参数格式错误、模型名错误、尺寸不支持 | 对照官方文档修改字段 |
404 Not Found |
接口路径或模型不存在 | 核对 Endpoint 和模型名 |
429 Too Many Requests |
请求频率过高 | 降低频率,使用指数退避 |
500 Internal Server Error |
服务端异常 | 稍后重试,仍失败则提交工单 |
| 请求超时 | 视频生成耗时较长 | 改用异步任务与有限轮询 |
通常会有。免费接口往往比付费接口更严格,可能限制每分钟请求数、每日调用次数或并发数。判断方式包括查看官方文档、观察是否出现 429,以及查看控制台配额页面。
建议登录 Agnes AI 控制台,查看费用、配额、赠送额度或活动页面。如果页面只显示“免费体验”,但没有说明额度、期限和商用条款,应向官方确认,不要自行假设。
可以简单按下面规则处理:
免费 API 很适合学习和验证想法,但进入真实项目后,还要考虑密钥安全、日志、成本、降级、合规和多模型管理。
不要在前端代码中暴露 API Key。推荐通过后端服务统一调用模型接口,由服务端负责鉴权、限流、日志和错误处理。生产环境建议使用密钥管理服务,而不是把密钥写进配置文件或环境变量后长期暴露在服务器日志中。
建议记录请求时间、模型名称、输入摘要、输出状态、耗时、错误码和任务 ID。注意不要记录完整敏感内容,避免隐私泄露。日志应支持脱敏、截断和权限控制。
即使接口当前免费,也要关注资源消耗。文本接口关注 Token 消耗,图像接口关注生成次数,视频接口关注任务时长和并发。项目化后建议设置预算告警、失败重试上限和降级策略。
生成式 AI 应用需要注意内容安全、版权、隐私保护和平台使用规范。尤其面向公众提供服务时,应增加内容审核、用户协议、生成内容标识和投诉处理机制。
当你已经跑通单个模型调用,并准备进入多模型应用阶段时,可能会遇到模型选型、价格对比、统一接入和调用管理等问题。此时,可以了解 百度智能云词元所。该页面属于公开第三方产品介绍,仅作为多模型选型和接入管理的可选延伸阅读,不是完成本文 Agnes AI 实操的必要步骤。是否使用取决于你的业务需求、预算和合规要求。
Agnes AI 免费 API 可以作为零基础开发者练习大模型接口的入口。建议你从文本生成开始,依次验证图像生成和短视频异步任务,并在每一步都先确认官方文档中的真实参数。接入前要重点核验免费额度、速率限制、适用期限和商用授权;代码中要使用环境变量管理密钥,并加入有限的重试、退避和最大轮询次数;上线前还要补齐日志、成本控制、内容合规和降级策略。这样才能从“跑通一次 Demo”真正过渡到“稳定接入项目”。