零基础上手 Agnes AI 文本与图像 API 接入
作者:JC2026.11.17 03:29浏览量:0简介:本文面向零基础读者,讲解如何用一个 API Key 和 POST 请求接入 Agnes-2.0-Flash 文本模型与 Agnes-Image-2.1-Flash 图像模型。内容包括可直接运行的代码示例、流式输出、图像文件校验、重试策略、常见错误排查和成本估算方法,读完即可完成从零到可用的接入。
先看结论
Agnes AI 目前开放两个模型。文本模型 Agnes-2.0-Flash 适合代码生成、逻辑拆解和文案创作。图像模型 Agnes-Image-2.1-Flash 支持文生图、图生图和多图融合。免费开放的范围、额度和期限可能调整,动手前请以官方公告为准。
接入只需三步:
- 在控制台创建 API Key。
- 从官方文档确认 Base URL 和模型名称。
- 用 POST 请求传入
model、messages(图像接口为prompt)和鉴权头,然后解析返回结果。
如果你已经有开发经验,通常一小时内可以跑通全部示例。前提是账号已开通、网络可以访问服务地址,并且你使用的是最新版官方文档。
一、准备工作
开始前需要三样东西:API Key、Base URL 和目标模型名。Base URL 必须从官方文档中复制,本文不写死具体地址,因为服务地址可能随版本变化。模型名需要与文档保持一致,本文示例使用 Agnes-2.0-Flash 和 Agnes-Image-2.1-Flash。
密钥不要写进代码,也不要提交到代码仓库。建议放在环境变量里:
export AGNES_API_KEY="你的密钥"export AGNES_BASE_URL="官方文档给出的 Base URL"
Python 环境安装依赖:
pip install openai requests pillow
Agnes 的接口风格接近主流的 OpenAI 兼容协议。如果你之前用过 OpenAI SDK,多数情况下只需要替换 base_url 和模型名。图像示例使用 requests 直接发送请求,pillow 用于校验返回的图片文件。
在写代码之前,建议先用 curl 确认密钥和网络都正常。出现问题时,这一步能帮你快速判断是网络原因还是密钥原因:
curl "$AGNES_BASE_URL/chat/completions" \-H "Authorization: Bearer $AGNES_API_KEY" \-H "Content-Type: application/json" \-d '{"model":"Agnes-2.0-Flash","messages":[{"role":"user","content":"你好"}]}'
返回 JSON 且包含 choices 字段,说明连通性正常。
二、文本模型 Agnes-2.0-Flash 实操
2.1 最小可用调用
下面的代码完成一次文本调用。注意返回值是列表,要用 choices[0] 取出第一个结果:
import osfrom openai import OpenAIclient = OpenAI(api_key=os.environ["AGNES_API_KEY"],base_url=os.environ["AGNES_BASE_URL"],)code_snippet = """def f(nums):result = []for i in range(len(nums)):for j in range(len(nums)):if nums[i] == nums[j] and i != j:result.append(nums[i])return result"""resp = client.chat.completions.create(model="Agnes-2.0-Flash",messages=[{"role": "system", "content": "你是一名严谨的 Python 代码审查助手。"},{"role": "user", "content": "找出下面代码的时间复杂度问题,并给出优化版本:\n" + code_snippet},],temperature=0.3,)print(resp.choices[0].message.content)
temperature 控制输出的随机程度。代码审查、数据抽取这类需要稳定结果的任务,建议设为 0.3 以下。文案创作可以适当调高。
2.2 流式输出:改善交互体感
对话类应用如果等整段内容生成完再返回,用户会明显感觉卡顿。加上 stream=True 后,内容会逐段返回。
流式响应中,部分分块的 choices 可能为空列表,所以读取前要先判断:
stream = client.chat.completions.create(model="Agnes-2.0-Flash",messages=[{"role": "user", "content": "用三句话解释什么是向量数据库"}],stream=True,)for chunk in stream:if chunk.choices and chunk.choices[0].delta.content:print(chunk.choices[0].delta.content, end="", flush=True)print()
2.3 长上下文怎么用才不浪费
Agnes-2.0-Flash 官方宣传支持超长上下文。具体窗口大小和超长输入的计费规则,请以官方文档为准。能放进模型的文本量,并不代表效果一定好。实际使用时,有三条经验可以参考。
第一,长文档放在前面,指令放在最后。把”请总结以下内容的三个风险点”这类指令放在材料之后,通常比放在开头更稳定。
第二,注意中间内容容易被忽略。关键信息不要只埋在长文本中段。必要时可以在开头做一次摘要,在结尾重复一次核心要求。
第三,上下文越长,成本和延迟越高。批量处理文本时,先做分段和去噪,只把相关片段送进模型,不要整库灌入。
2.4 三个适合练手的小项目
| 练习方向 | 实现要点 | 能掌握的技能 |
|---|---|---|
| 个人问答助手 | system prompt 加多轮 messages 数组 | 会话状态管理、上下文裁剪 |
| 代码纠错工具 | 低 temperature 加结构化输出要求 | 提示词约束、结果解析 |
| 批量文案生成 | 循环调用、并发控制、失败重试 | 限流处理、任务队列 |
三、图像模型 Agnes-Image-2.1-Flash 实操
图像接口的核心参数是 prompt、尺寸参数(本文示例为 size),以及参考图(图生图和多图融合时需要)。返回结果可能是图片 URL,也可能是 base64 字符串。请在官方文档中确认尺寸参数的合法取值,以及参考图字段的名称和格式。
下面的代码同时处理两种返回形式,并统一返回 bytes 类型:
import base64import ioimport osimport requestsfrom PIL import ImageAPI_KEY = os.environ["AGNES_API_KEY"]BASE_URL = os.environ["AGNES_BASE_URL"]def text_to_image(prompt: str, size: str = "2048x2048") -> bytes:r = requests.post(f"{BASE_URL}/images/generations",headers={"Authorization": f"Bearer {API_KEY}"},json={"model": "Agnes-Image-2.1-Flash", "prompt": prompt, "size": size},timeout=120,)r.raise_for_status()item = r.json()["data"][0]if item.get("b64_json"):return base64.b64decode(item["b64_json"])img = requests.get(item["url"], timeout=120)img.raise_for_status()return img.contentdef check_image(data: bytes) -> None:if not data:raise ValueError("接口返回了空数据")Image.open(io.BytesIO(data)).verify() # 截断或损坏的图片会在这里抛出异常
调用示例如下:
data = text_to_image("极简风格咖啡品牌海报,暖色调,画面上方留出标题区域")check_image(data)with open("poster.png", "wb") as f:f.write(data)
落盘文件的扩展名应与返回的图片格式一致。如果接口返回的是 JPEG,文件名也应改为 .jpg。
图生图和多图融合需要在请求体中增加参考图,通常是 base64 字符串或可访问的图片地址。提示词要写清楚”保留什么、改什么”。
图像生成最容易出问题的是文字。Agnes-Image-2.1-Flash 支持 4K 高清输出,但这主要改善清晰度和细节,不保证文字排版正确。实践中有两种稳妥做法。一是在提示词里明确写出文案内容、字体风格和位置。二是画面中留出空白区域,生成后用设计工具叠加文字。电商素材和品牌视觉图批量生产时,大多采用第二种做法。
批量生成时,请做好两件事。第一,控制并发数,避免触发限流。第二,落盘前校验文件完整性,因为接口偶尔会返回空数据或截断的 base64。
四、常见问题排查
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
| 401 或鉴权失败 | 密钥错误、缺少 Bearer 前缀、环境变量未生效 |
先用 curl 单独验证密钥 |
| 429 或请求过于频繁 | 并发过高,或超出速率限制 | 指数退避重试,任务排队执行 |
| 请求超时 | 长上下文或高分辨率出图耗时较长 | 把 timeout 提高到 120 秒以上,或改用异步任务 |
| 回答跑题、不遵循格式 | system prompt 缺失,或指令被长文本淹没 | 把指令放到末尾,必要时降低 temperature |
| 生成图文字错乱 | 模型直接渲染文字 | 在提示词中写明文案,或后期叠加文字层 |
| 上下文超长报错 | 多轮 messages 不断累积 | 滚动摘要,只保留最近 N 轮对话 |
| 图片无法打开 | 返回数据被截断 | 运行 check_image 检测,失败后重新请求 |
重试逻辑建议统一封装,避免每个调用点各写一套。下面的函数按指数退避等待,等待时间依次为 1.5 秒、3 秒、6 秒:
import timedef call_with_retry(fn, times=3, base=1.5):for attempt in range(times):try:return fn()except Exception:if attempt == times - 1:raisetime.sleep(base * (2 ** attempt))data = call_with_retry(lambda: text_to_image("雪山下的小镇,清晨,油画风格"))
生产环境中,建议只对超时、429 和 5xx 错误重试。鉴权失败和参数错误重试没有意义,应当直接报错。
五、从免费额度走向生产:成本与选型
免费额度适合学习和原型验证。进入生产环境后,需要提前估算成本。文本模型通常按 Token(词元)计费,输入和输出分开计价。单价和计费口径请以官方定价页为准。粗算公式如下:
单次调用成本 = 输入 Token 数 × 输入单价 + 输出 Token 数 × 输出单价月度成本 ≈ 单次调用成本 × 日均调用次数 × 30
假设输入单价为每千 Token 0.002 元,输出单价为每千 Token 0.006 元。一次调用平均输入 1500 Token、输出 500 Token,日调用 2000 次,那么单次成本约为 0.006 元,月度成本约为 360 元。这组数字只用于演示计算方法,实际价格请以官方为准。
图像模型一般按张计费。成本优化主要靠两点:一是提高提示词的一次出图成功率,减少废图;二是按用途分级设置分辨率,草稿用低分辨率,定稿才用 4K。
文本成本的优化方向有三个。第一,压缩输入,包括去重、摘要,以及只检索相关片段。第二,控制输出,限定字数和格式,避免模型长篇铺陈。第三,分级路由,简单请求走轻量模型,复杂推理才调用旗舰模型。
如果你需要在 Agnes、文心 ERNIE、DeepSeek 等多个模型之间比价和切换,逐个注册、逐个对接密钥的成本很高。以下为推广信息:百度智能云词元所是一个大模型撮合交易服务平台,提供模型选型、价格与性能对比、统一 API 接入和调用管理等功能。文中不对其效果作保证,链接为 https://cloud.baidu.com/product-s/token_exchange.html 。
无论是否使用这类平台,都建议把 Base URL、模型名和

登录后可评论,请前往 登录 或 注册