简介:本文面向零基础开发者,讲解 Agnes AI API 中文本模型 Agnes-2.0-Flash 与图像模型 Agnes-Image-2.1-Flash 的首次调用方法。内容涵盖密钥的环境变量管理、可运行的 Python 示例、图像返回格式处理,以及 401、429、超时等常见错误的排查。读完后,你可以独立完成一次文本与图像的串联调用。
Agnes AI 的接入可以拆成五步:准备密钥、选择模型、发送请求、解析结果、处理异常。本文按这个顺序,先用两个模型完成最小可用调用,再把它们串成一个小流程。
AGNES_API_BASE 只是占位,需要替换为官方文档给出的地址。Agnes-2.0-Flash,图像模型为 Agnes-Image-2.1-Flash。以控制台或官方模型列表为准。本文不假设免费额度、限流数值、上下文长度、图片分辨率上限和商用条件。这些内容变化较快,请以官方文档和控制台显示的信息为准。
不要把 API Key 写进代码。在终端中设置环境变量:
export AGNES_API_KEY="你的密钥"export AGNES_API_BASE="官方文档给出的 Base URL"
检查变量是否已设置,同时不显示密钥内容:
[ -n "$AGNES_API_KEY" ] && echo "API Key 已设置" || echo "API Key 未设置"
不要使用 echo $AGNES_API_KEY 直接输出密钥。密钥可能留在终端历史、屏幕录像或日志中。如果项目使用 .env 文件保存配置,要把该文件加入 .gitignore,避免提交到 Git 仓库。
下面的 curl 示例使用的路径和字段遵循常见的对话接口格式。实际路径与字段必须与官方文档核对:
curl -X POST "$AGNES_API_BASE/chat/completions" \-H "Authorization: Bearer $AGNES_API_KEY" \-H "Content-Type: application/json" \-d '{"model": "Agnes-2.0-Flash","messages": [{"role": "user", "content": "请用 Python 实现二分查找,并说明时间复杂度。"}]}'
Python 版本的完整示例如下:
import osimport requestsapi_key = os.getenv("AGNES_API_KEY")api_base = os.getenv("AGNES_API_BASE", "").rstrip("/")if not api_key or not api_base:raise RuntimeError("请先设置 AGNES_API_KEY 和 AGNES_API_BASE 环境变量")url = f"{api_base}/chat/completions"headers = {"Authorization": f"Bearer {api_key}","Content-Type": "application/json",}payload = {"model": "Agnes-2.0-Flash","messages": [{"role": "user", "content": "请用 Python 实现二分查找,并说明时间复杂度。"}],}resp = requests.post(url, headers=headers, json=payload, timeout=30)resp.raise_for_status()choices = resp.json().get("choices") or []if not choices:raise RuntimeError("接口没有返回 choices 字段,请对照官方文档检查响应结构")content = choices[0].get("message", {}).get("content", "")print(content)
这段代码有几处需要注意:
timeout=30 限制等待时间,避免程序无限期挂起。raise_for_status() 会把 401、400、429 等 HTTP 错误转换为异常。这样错误页面不会被当成正常结果处理。choices 是列表,必须先取第一个元素,再读取 message.content。如果直接对列表调用 .get(),程序会报错。图像生成耗时通常比文本长,因此超时时间设为 60 秒。示例如下:
import base64import osimport requestsapi_key = os.getenv("AGNES_API_KEY")api_base = os.getenv("AGNES_API_BASE", "").rstrip("/")if not api_key or not api_base:raise RuntimeError("请先设置 AGNES_API_KEY 和 AGNES_API_BASE 环境变量")url = f"{api_base}/images/generations"headers = {"Authorization": f"Bearer {api_key}","Content-Type": "application/json",}payload = {"model": "Agnes-Image-2.1-Flash","prompt": "科技感 AI 产品海报,蓝色渐变背景,中心留白,简洁未来风格","size": "1024x1024",}resp = requests.post(url, headers=headers, json=payload, timeout=60)resp.raise_for_status()items = resp.json().get("data") or []if not items:raise RuntimeError("响应中没有 data 字段,请检查官方文档中的返回结构")item = items[0]if item.get("b64_json"):with open("output.png", "wb") as f:f.write(base64.b64decode(item["b64_json"]))print("图片已保存为 output.png")elif item.get("url"):print("图片地址:", item["url"])else:raise RuntimeError("响应中既没有 b64_json,也没有 url")
不同平台可能返回图片 URL,也可能返回 Base64 编码。代码应同时处理这两种情况。保存 Base64 图片时,先确认字段非空,再进行解码。
一个常见的入门项目是“文案加海报”。流程分为三步:用文本模型写出文案,把文案放进图像提示词,再调用图像模型生成配图