Agnes AI 接入指南:文本与图像调用实操

作者:半吊子全栈工匠2026.11.17 03:39浏览量:0

简介:本文面向零基础开发者,讲解 Agnes AI API 中文本模型 Agnes-2.0-Flash 与图像模型 Agnes-Image-2.1-Flash 的首次调用方法。内容涵盖密钥的环境变量管理、可运行的 Python 示例、图像返回格式处理,以及 401、429、超时等常见错误的排查。读完后,你可以独立完成一次文本与图像的串联调用。

Agnes AI 的接入可以拆成五步:准备密钥、选择模型、发送请求、解析结果、处理异常。本文按这个顺序,先用两个模型完成最小可用调用,再把它们串成一个小流程。

一、接入前需要确认的四项信息

  1. API Key:鉴权凭证,决定你能调用哪些服务。
  2. Base URL:接口地址。本文代码中的 AGNES_API_BASE 只是占位,需要替换为官方文档给出的地址。
  3. 模型名称:文本模型为 Agnes-2.0-Flash,图像模型为 Agnes-Image-2.1-Flash。以控制台或官方模型列表为准。
  4. 调用工具:curl,或安装了 requests 库的 Python 3。

本文不假设免费额度、限流数值、上下文长度、图片分辨率上限和商用条件。这些内容变化较快,请以官方文档和控制台显示的信息为准。

二、用环境变量保存密钥

不要把 API Key 写进代码。在终端中设置环境变量:

  1. export AGNES_API_KEY="你的密钥"
  2. export AGNES_API_BASE="官方文档给出的 Base URL"

检查变量是否已设置,同时不显示密钥内容:

  1. [ -n "$AGNES_API_KEY" ] && echo "API Key 已设置" || echo "API Key 未设置"

不要使用 echo $AGNES_API_KEY 直接输出密钥。密钥可能留在终端历史、屏幕录像或日志中。如果项目使用 .env 文件保存配置,要把该文件加入 .gitignore,避免提交到 Git 仓库。

三、文本模型:先跑通一次调用

下面的 curl 示例使用的路径和字段遵循常见的对话接口格式。实际路径与字段必须与官方文档核对:

  1. curl -X POST "$AGNES_API_BASE/chat/completions" \
  2. -H "Authorization: Bearer $AGNES_API_KEY" \
  3. -H "Content-Type: application/json" \
  4. -d '{
  5. "model": "Agnes-2.0-Flash",
  6. "messages": [
  7. {"role": "user", "content": "请用 Python 实现二分查找,并说明时间复杂度。"}
  8. ]
  9. }'

Python 版本的完整示例如下:

  1. import os
  2. import requests
  3. api_key = os.getenv("AGNES_API_KEY")
  4. api_base = os.getenv("AGNES_API_BASE", "").rstrip("/")
  5. if not api_key or not api_base:
  6. raise RuntimeError("请先设置 AGNES_API_KEY 和 AGNES_API_BASE 环境变量")
  7. url = f"{api_base}/chat/completions"
  8. headers = {
  9. "Authorization": f"Bearer {api_key}",
  10. "Content-Type": "application/json",
  11. }
  12. payload = {
  13. "model": "Agnes-2.0-Flash",
  14. "messages": [
  15. {"role": "user", "content": "请用 Python 实现二分查找,并说明时间复杂度。"}
  16. ],
  17. }
  18. resp = requests.post(url, headers=headers, json=payload, timeout=30)
  19. resp.raise_for_status()
  20. choices = resp.json().get("choices") or []
  21. if not choices:
  22. raise RuntimeError("接口没有返回 choices 字段,请对照官方文档检查响应结构")
  23. content = choices[0].get("message", {}).get("content", "")
  24. print(content)

这段代码有几处需要注意:

  • timeout=30 限制等待时间,避免程序无限期挂起。
  • raise_for_status() 会把 401、400、429 等 HTTP 错误转换为异常。这样错误页面不会被当成正常结果处理。
  • choices 是列表,必须先取第一个元素,再读取 message.content。如果直接对列表调用 .get(),程序会报错。
  • 解析前先判断字段是否存在,不要假设返回结构永远不变。

四、图像模型:文生图

图像生成耗时通常比文本长,因此超时时间设为 60 秒。示例如下:

  1. import base64
  2. import os
  3. import requests
  4. api_key = os.getenv("AGNES_API_KEY")
  5. api_base = os.getenv("AGNES_API_BASE", "").rstrip("/")
  6. if not api_key or not api_base:
  7. raise RuntimeError("请先设置 AGNES_API_KEY 和 AGNES_API_BASE 环境变量")
  8. url = f"{api_base}/images/generations"
  9. headers = {
  10. "Authorization": f"Bearer {api_key}",
  11. "Content-Type": "application/json",
  12. }
  13. payload = {
  14. "model": "Agnes-Image-2.1-Flash",
  15. "prompt": "科技感 AI 产品海报,蓝色渐变背景,中心留白,简洁未来风格",
  16. "size": "1024x1024",
  17. }
  18. resp = requests.post(url, headers=headers, json=payload, timeout=60)
  19. resp.raise_for_status()
  20. items = resp.json().get("data") or []
  21. if not items:
  22. raise RuntimeError("响应中没有 data 字段,请检查官方文档中的返回结构")
  23. item = items[0]
  24. if item.get("b64_json"):
  25. with open("output.png", "wb") as f:
  26. f.write(base64.b64decode(item["b64_json"]))
  27. print("图片已保存为 output.png")
  28. elif item.get("url"):
  29. print("图片地址:", item["url"])
  30. else:
  31. raise RuntimeError("响应中既没有 b64_json,也没有 url")

不同平台可能返回图片 URL,也可能返回 Base64 编码。代码应同时处理这两种情况。保存 Base64 图片时,先确认字段非空,再进行解码。

五、文本与图像串联

一个常见的入门项目是“文案加海报”。流程分为三步:用文本模型写出文案,把文案放进图像提示词,再调用图像模型生成配图