Agnes 生图生视频 API 接入实战：一个 Skill 的封装过程

Agnes AI 最近在国内上线了 agnes-ai.cn 站点API 响应速度比之前好了很多。我一直在用它做 AI 生图和生视频过程中发现一个问题每次让 Claude Code、Codex 这类 Agent 调用 Agnes API 时它们都会临时猜测模型名、端点路径、密钥来源和视频轮询方式猜对的概率不高。于是我把这些接口细节整理成了一个可复用的 Skill让 Agent 能稳定调用 Agnes 完成图片和视频生成。这篇文章会介绍 Agnes 的图片与视频能力以及我封装 Skill 时踩到的坑和解决思路包括如何配置密钥、如何让 Agent 正确调用图生图和视频接口。一、Agnes 的图片与视频模型Agnes AI 提供了一套面向媒体内容生成的 API可以通过 OpenAI 风格的 HTTP 接口调用图片与视频模型。目前我主要用了以下三类模型创作任务模型适用场景文生图、复杂构图、图生图agnes-image-2.1-flash文章配图、海报、封面、场景概念图图片编辑、多图合成agnes-image-2.0-flash产品图改造、风格转换、多素材合成文生视频、图生视频、关键帧动画agnes-video-v2.0短视频素材、让静态封面动起来、首尾帧转场这三个模型覆盖了日常内容创作中大部分媒体生成需求。图片生成是同步接口视频生成是异步任务两者在调用方式上有明显差异后面会详细说。二、国内站与国际站Agnes 目前有中国站和国际站两套站点的模型契约相同但网关和密钥分别管理。站点API Base URL对应环境变量中国站默认https://api.agnes-ai.cn/v1AGNES_CN_API_KEY国际站https://apihub.agnes-ai.com/v1AGNES_API_KEY实际使用时遵循两个原则中国站密钥不能用于国际站反之亦然需要分别注册获取。没有明确偏好时默认走中国站。若中国站因网络或服务错误失败我会让 Skill 尝试用国际站密钥自动重试一次参数错误和限流不触发切换。这样做的目的主要是避免因服务不可达而重复提交生成任务特别是视频生成有成本和时间消耗不能因为一次请求状态不明确就在两个站点同时创建任务。三、Skill 封装了什么我做的这个 Skill 没有图形界面也不是独立的图片模型它是一套 Agent 调用 Agnes API 的操作规范和工作流包。做它的原因很直接同样是生成一张图如果 Agent 临时猜测模型和端点往往会得到错误的请求参数或无法下载的 URL。这个 Skill 的核心能力包括识别媒体任务识别文生图、图生图、图片编辑、多图合成、文生视频、图生视频和关键帧动画。根据站点意图选路默认中国站用户明确说国际站时才使用国际站。使用正确的 API 契约图片统一请求POST /v1/images/generations视频创建使用POST /v1/videos图生图不是/v1/images/edits而是将输入图片放入extra_body.image视频是异步任务创建后要轮询状态不能假定请求返回时视频已经生成完成交付检查图片下载后检查文件存在且非空并读取实际尺寸视频必须等任务状态为completed、确认metadata.url存在后再下载。四、密钥配置方式要让 Agent 能调用 Agnes API需要先配置密钥。1. 获取密钥在 Agnes 各站点的控制台 API Key 管理页面创建密钥中国站和国际站分别获取。2. 写入环境变量在项目根目录创建.env文件# 中国站 AGNES_CN_API_KEY你的中国站密钥 # 国际站 AGNES_API_KEY你的国际站密钥如果只使用中国站可以只填AGNES_CN_API_KEY。Skill 会优先读取已经注入的环境变量找不到时再从当前目录逐级向上寻找.env。五、图片与视频的调用差异图片生成图片接口是同步等待的典型请求。以中国站为例文生图请求体的关键字段如下{model:agnes-image-2.1-flash,prompt:A luminous floating city above a misty canyon at sunrise, cinematic realism,size:1K,ratio:16:9,extra_body:{response_format:url}}请求路径为POST https://api.agnes-ai.cn/v1/images/generations。需要注意response_format必须位于extra_body内不能放在请求体顶层这个细节容易忽略。成功时图片 URL 位于data[0].url。图生图图生图同样调用POST /v1/images/generations输入图放在extra_body.image数组中{extra_body:{image:[https://example.com/product.png],response_format:url}}输入 URL 需要是 Agnes 服务端能访问的公网 HTTPS 图片。如果只有本地图片需要先转成 Data URI Base64不能把本地文件路径直接当作 URL 提交。视频生成视频是异步任务分两步走。创建任务POST https://api.agnes-ai.cn/v1/videos轮询查询GET https://api.agnes-ai.cn/v1/agnesapi?video_idVIDEO_ID创建后优先读取响应中的video_id按至少 10 秒的间隔轮询。仅当状态为completed时才能从metadata.url获取成品视频地址。视频生成不能按图片接口的思路一次请求立即下载。六、使用示例示例一文生图以下是一个完整的文生图调用指令使用 Agnes 中国站生成一张16:9的文章头图。 画面夜晚的城市数据中心蓝色冷光画面干净预留左侧标题区域不要文字。 保存为 city-data-center.png。示例二图生图基于已有图片生成新图使用 Agnes 中国站进行图生图。 输入图片https://example.com/product.png 编辑目标保留产品外形和主色将背景改为简洁的浅灰色未来感工作室 加入柔和侧逆光和地面倒影适合 B2B SaaS 官网。 规格16:91K。 保存为 product-website-hero.png。示例三图生视频将静态封面图做成 5 秒动态片段使用 Agnes 中国站根据以下封面图生成图生视频 https://example.com/cover.png 动作镜头从轻微虚焦逐渐清晰画面中的纸张边缘被微风吹动 屏幕上的蓝色光点缓慢流动镜头轻微向前推进。 参数24 fps121 帧约 5 秒。 生成完成后下载为 cover-opening-5s.mp4。视频时长计算公式时长 num_frames / frame_rate。121 / 24 ≈ 5.04秒。num_frames必须不大于 441且满足8n1的规则。七、实测效果以下是通过这套工作流生成的一些图片和视频案例以下图片和视频由AI生成。图片效果人物图生成分镜图生成古风图生成海报图生成游戏图生成科幻图生成风景图生成视频效果八、常见问题1. 图生图不走 images/edits 接口Agnes 的图生图和多图合成使用的是POST /v1/images/generations不要自行构造/v1/images/edits。输入图应放进extra_body.image数组中。2. 400/413/415/422 错误这些状态通常表示请求参数、文件格式或内容本身有问题。切换站点不会修复错误反而可能让问题难以追踪。应该优先检查模型名、尺寸、图片 URL、字段位置和请求体格式。3. 视频任务一直没有结果先确认是否拿到了video_id再按照至少 10 秒的间隔查询任务状态。只有在status为completed且metadata.url存在时才应该开始下载。4. 图片尺寸与请求参数不完全一致对于agnes-image-2.1-flash推荐使用1K、2K、3K、4K加ratio。服务会把比例映射到实际像素规格例如请求实际像素1K16:91312×7361K9:16736×13121K1:11024×1024交付前应读取生成图片的实际宽高不要将请求参数直接当作最终文件尺寸。总结Agnes 提供的媒体生成能力是基础而 Skill 封装解决的是怎样让 Agent 稳定调用这些能力的问题。它让 Agent 不只是发出一次 API 请求而是能根据站点选择正确的密钥选用正确的模型和端点等待视频任务完成再把可用文件交付到本地。如果你也在把 AI 生图、生视频接进 Agent 工作流可以参考这个思路把接口细节固定下来让注意力放在创意和提示词上而不是反复处理参数和文件下载。代码仓库在 GitHub 上搜索agnes-ai-media即可找到。