说明：Agnes AI（agnes-ai.com）是由 Sapiens AI 推出的全模态大模型平台（非阿里内部项目，但与国内大模型生态深度兼容 OpenAI 协议），2026年6月起免费开放Agnes-2.0-Flash（文本/Agent）、Agnes-Image-2.1-Flash（图像）、Agnes-Video-V2.0（视频） 三大核心模型 API，完全兼容 OpenAI SDK，适合快速构建多模态 Agent 与内容生成流水线。
一、Agnes AI 平台与模型矩阵
Agnes AI 定位为"全模态一站式 API"，核心卖点是同一套 Key + 同一套 OpenAI 兼容协议 即可调用文本、图像、视频三种能力，且 Agent 文本模型原生支持 Function Calling / Tool Use / 1M Token 上下文。
模型标识 | 模态 | 核心能力 | 典型用途 |
|---|---|---|---|
| 文本 | 1M 上下文、Tool Use、结构化输出、代码生成 | Agent 规划、RAG、代码助手、多轮对话 |
| 图像 | 文生图、图改图（Img2Img）、局部编辑、多图融合 | 电商海报、人物风格转换、信息图 |
| 视频 | 文生视频(T2V)、首帧/首尾帧生视频、音画同步 | 广告素材、分镜预演、短视频 |
API Base URL：
https://apihub.agnes-ai.com/v1获取 Key：登录 https://platform.agnes-ai.com→ Settings → Create API Key
免费策略：免费层有 RPM/QPD 限额，商用可申请 Token Plan 提额
二、环境准备
# Python pip install openai requests # 设置环境变量（推荐） export AGNES_API_KEY="sk-xxxxxx" export AGNES_BASE_URL="https://apihub.agnes-ai.com/v1"Java 侧使用标准OkHttp+Jackson或直接引入spring-ai-openai-spring-boot-starter并覆写base-url。
三、Python 实践示例
3.1 文本对话 + 多轮（Agent 基座）
# -*- coding: utf-8 -*- from openai import OpenAI import os client = OpenAI( api_key=os.getenv("AGNES_API_KEY"), base_url=os.getenv("AGNES_BASE_URL") ) # ---- 单轮 ---- resp = client.chat.completions.create( model="agnes-2.0-flash", messages=[ {"role": "system", "content": "你是一名资深后端架构师"}, {"role": "user", "content": "用Python写一个带重试机制的HTTP请求工具类，含超时与指数退避"} ] ) print(resp.choices[0].message.content) # ---- 多轮对话 ---- messages = [ {"role": "system", "content": "你是数据分析助手"}, {"role": "user", "content": "帮我分析2025年Q1~Q4的销售额趋势，假设数据是[120,145,130,180]（万元）"} ] resp = client.chat.completions.create(model="agnes-2.0-flash", messages=messages) reply = resp.choices[0].message.content print(reply) messages.append({"role": "assistant", "content": reply}) messages.append({"role": "user", "content": "给出环比增长率并推荐下一步行动"}) resp2 = client.chat.completions.create(model="agnes-2.0-flash", messages=messages) print(resp2.choices[0].message.content)3.2 Function Calling（工具调用 / Agent 核心）
tools = [ { "type": "function", "function": { "name": "get_weather", "description": "获取指定城市的当前天气", "parameters": { "type": "object", "properties": { "city": {"type": "string", "description": "城市名，如'广州'"} }, "required": ["city"] } } } ] messages = [{"role": "user", "content": "广州今天天气怎么样？适合户外拍摄吗？"}] resp = client.chat.completions.create( model="agnes-2.0-flash", messages=messages, tools=tools, tool_choice="auto" ) msg = resp.choices[0].message # 模拟执行工具 if msg.tool_calls: call = msg.tool_calls[0] print(f"→ 调用工具: {call.function.name}, 参数: {call.function.arguments}") # 这里实际应查天气 API，此处模拟返回 weather_result = "晴，28°C，微风" messages.append({"role": "assistant", "content": None, "tool_calls": msg.tool_calls}) messages.append({ "role": "tool", "tool_call_id": call.id, "content": weather_result }) final = client.chat.completions.create(model="agnes-2.0-flash", messages=messages) print("Agent 回复:", final.choices[0].message.content) else: print(msg.content)3.3 文生图 + 图改图（Image）
# 文生图 img_resp = client.images.generate( model="agnes-image-2.1-flash", prompt="赛博朋克风格的未来城市夜景，霓虹灯，飞行汽车，超广角，电影感", size="1024x576", n=1, response_format="url" ) print("图片URL:", img_resp.data[0].url) # 图改图（Img2Img）—— 通过 extra_body 传原图 img_edit = client.images.generate( model="agnes-image-2.0-flash", # 2.0 版支持 img2img prompt="把这张照片改成梵高油画风格，保留主体轮廓", size="1024x1024", extra_body={ "tags": ["img2img"], "image": ["https://your-cdn.com/source.jpg"], # 公网可访问URL "response_format": "url" } ) print("编辑后URL:", img_edit.data[0].url)3.4 文生视频（异步任务模式）
Agnes-Video 使用异步任务接口，需先提交再轮询：
import requests import time import os API_KEY = os.getenv("AGNES_API_KEY") BASE = "https://apihub.agnes-ai.com/v1" headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } # 提交任务 submit = requests.post( f"{BASE}/videos", headers=headers, json={ "model": "agnes-video-v2.0", "prompt": "夕阳下金毛犬在沙滩上追逐飞盘，慢动作，电影感", "width": 1280, "height": 720, "num_frames": 121, # ~5秒 @24fps "frame_rate": 24 } ) submit.raise_for_status() task_id = submit.json()["id"] print(f"Task submitted: {task_id}") # 轮询 while True: res = requests.get(f"{BASE}/videos/{task_id}", headers=headers) data = res.json() status = data.get("status") or data.get("task_status") if status in ("succeeded", "SUCCEEDED"): print("Video URL:", data.get("video_url") or data["output"]["video_url"]) break elif status in ("failed", "FAILED"): raise RuntimeError(f"Video gen failed: {data}") time.sleep(5)四、Java 调用示例（HTTP 方式）
以最常用的文本对话 和文生图 为例，使用 OkHttp + Jackson。
Maven 依赖
<dependency> <groupId>com.squareup.okhttp3</groupId> <artifactId>okhttp</artifactId> <version>4.12.0</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.17.0</version> </dependency>Java 示例——Chat Completions
package com.example.agnes; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import okhttp3.*; import java.io.IOException; import java.util.LinkedHashMap; import java.util.Map; public class AgnesClient { private static final String API_KEY = System.getenv("AGNES_API_KEY"); private static final String BASE_URL = "https://apihub.agnes-ai.com/v1/chat/completions"; private static final OkHttpClient client = new OkHttpClient(); private static final ObjectMapper mapper = new ObjectMapper(); public static String chat(String userMsg) throws IOException { Map<String, Object> msg = Map.of("role", "user", "content", userMsg); Map<String, Object> body = Map.of( "model", "agnes-2.0-flash", "messages", new Object[]{msg} ); String json = mapper.writeValueAsString(body); Request req = new Request.Builder() .url(BASE_URL) .addHeader("Authorization", "Bearer " + API_KEY) .post(RequestBody.create(json, MediaType.parse("application/json"))) .build(); try (Response resp = client.newCall(req).execute()) { JsonNode root = mapper.readTree(resp.body().string()); return root.get("choices").get(0).get("message").get("content").asText(); } } public static void main(String[] args) throws Exception { System.out.println(chat("用一句话介绍 Agnes AI 平台")); } }Java 示例——文生图
public static String generateImage(String prompt) throws IOException { Map<String, Object> body = Map.of( "model", "agnes-image-2.1-flash", "prompt", prompt, "size", "1024x576", "n", 1, "response_format", "url" ); Request req = new Request.Builder() .url("https://apihub.agnes-ai.com/v1/images/generations") .addHeader("Authorization", "Bearer " + API_KEY) .post(RequestBody.create( mapper.writeValueAsString(body), MediaType.parse("application/json"))) .build(); try (Response resp = client.newCall(req).execute()) { JsonNode root = mapper.readTree(resp.body().string()); return root.get("data").get(0).get("url").asText(); } }五、Agent 多模态组合实战思路
Agnes AI 的优势在于同一套 Key 串联三种模态，典型 Agent 工作流：
规划层（agnes-2.0-flash + Function Calling）→ 解析用户意图，判断是否需生图/生视频
创作层 → 调用 Image API 生成角色参考图 / 场景概念图
叙事层 → 调用 Video API 基于文案+参考图生成短片（或配合外部剪辑拼接）
汇报层（agnes-2.0-flash）→ 汇总结果、生成文案说明
这种"LLM 规划 + 多模态执行"的 Pattern 非常适合做短视频自动生产 Agent、电商素材批量生成流水线。
六、注意事项
视频接口是异步的：务必轮询或配置 Webhook，不要同步等待
图片 Img2Img 需通过
extra_body.image传公网 HTTPS URL免费限额：有 RPM（每分钟请求数）和日调用量限制，生产环境建议申请付费 Token Plan
兼容 OpenAI 协议：存量 LangChain / LlamaIndex / Spring AI 代码只需改
base_url+api_key
