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/v1`	`AGNES_CN_API_KEY`
国际站	`https://apihub.agnes-ai.com/v1`	`AGNES_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 文件：

dotenv 复制代码

# 中国站
AGNES_CN_API_KEY=你的中国站密钥

# 国际站
AGNES_API_KEY=你的国际站密钥

如果只使用中国站，可以只填 AGNES_CN_API_KEY。Skill 会优先读取已经注入的环境变量，找不到时再从当前目录逐级向上寻找 .env。

五、图片与视频的调用差异

图片生成

图片接口是同步等待的典型请求。以中国站为例，文生图请求体的关键字段如下：

json 复制代码

{
  "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 数组中：

json 复制代码

{
  "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_id=<VIDEO_ID>

创建后优先读取响应中的 video_id，按至少 10 秒的间隔轮询。仅当状态为 completed 时，才能从 metadata.url 获取成品视频地址。视频生成不能按图片接口的思路"一次请求立即下载"。

六、使用示例

示例一：文生图

以下是一个完整的文生图调用指令：

复制代码

使用 Agnes 中国站生成一张16:9的文章头图。
画面：夜晚的城市数据中心，蓝色冷光，画面干净，预留左侧标题区域，不要文字。
保存为 city-data-center.png。

示例二：图生图

基于已有图片生成新图：

复制代码

使用 Agnes 中国站进行图生图。
输入图片：https://example.com/product.png
编辑目标：保留产品外形和主色，将背景改为简洁的浅灰色未来感工作室，
加入柔和侧逆光和地面倒影，适合 B2B SaaS 官网。
规格：16:9，1K。
保存为 product-website-hero.png。

示例三：图生视频

将静态封面图做成 5 秒动态片段：

复制代码

使用 Agnes 中国站，根据以下封面图生成图生视频：
https://example.com/cover.png

动作：镜头从轻微虚焦逐渐清晰，画面中的纸张边缘被微风吹动，
屏幕上的蓝色光点缓慢流动，镜头轻微向前推进。

参数：24 fps，121 帧，约 5 秒。
生成完成后下载为 cover-opening-5s.mp4。

视频时长计算公式：时长 = num_frames / frame_rate。121 / 24 ≈ 5.04 秒。num_frames 必须不大于 441，且满足 8n+1 的规则。

七、实测效果

以下是通过这套工作流生成的一些图片和视频案例（以下图片和视频由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。服务会把比例映射到实际像素规格，例如：

请求	实际像素
`1K` + `16:9`	1312×736
`1K` + `9:16`	736×1312
`1K` + `1:1`	1024×1024

交付前应读取生成图片的实际宽高，不要将请求参数直接当作最终文件尺寸。

总结

Agnes 提供的媒体生成能力是基础，而 Skill 封装解决的是"怎样让 Agent 稳定调用这些能力"的问题。它让 Agent 不只是发出一次 API 请求，而是能根据站点选择正确的密钥，选用正确的模型和端点，等待视频任务完成，再把可用文件交付到本地。

如果你也在把 AI 生图、生视频接进 Agent 工作流，可以参考这个思路：把接口细节固定下来，让注意力放在创意和提示词上，而不是反复处理参数和文件下载。代码仓库在 GitHub 上，搜索 agnes-ai-media 即可找到。