agnes-ai-generation
Call Agnes AI / Sapiens AI generation APIs for text, image, and video. Use when the user asks to use Agnes models, Agnes Image, Agnes Video, Agnes 2.0 Flash, apihub.agnes-ai.com, or to generate text, images, edit images, create videos, animate images, create keyframe videos, or test Agnes API calls.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/yacey-agnes-ai-generation-skill)HTML
<a href="/listings/yacey-agnes-ai-generation-skill"><img src="/api/listings/yacey-agnes-ai-generation-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 115 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: agnes-ai-generation
- description: Call Agnes AI / Sapiens AI generation APIs for text, image, and video. Use when the user asks to use Agnes models, Agnes Image, Agnes Video, Agnes 2.0 Flash, apihub.agnes-ai.com, or to generate text, images, edit images, create videos, animate images, create keyframe videos, or test Agnes API calls.
- ---
- # Agnes AI Generation
- Use this skill to call Agnes text, image, and video generation APIs through `https://apihub.agnes-ai.com`.
- ## Quick Start
- 1. Read `references/api.md` when endpoint details, parameters, or response fields are needed.
- 2. Use `scripts/agnes_api.py` for real API calls instead of rewriting curl by hand.
- 3. Require an API key in `AGNES_API_KEY`, `AGNES_API_TOKEN`, or `APIHUB_AGNES_API_KEY`. Never print the key.
- 4. For light live verification, run `smoke-test`; it avoids video creation by default. Add `--include-image-edit` for image-to-image, and add `--video-case <case>` explicitly for video modes. Treat the skill as fully tested only when basic text, text streaming, text tool calling, text-to-image, image-to-image, text-to-video, image-to-video, multi-image video, keyframe video, and video retrieval return successful responses.
- ## Commands
- Text generation:
- ```bash
- python scripts/agnes_api.py text --prompt "Write a concise product tagline for an AI assistant."
- ```
- Streaming text:
- ```bash
- python scripts/agnes_api.py text --prompt "Write a short product intro." --stream
- ```
- Streaming output is normalized and includes aggregated `content`, `events`, `done`, and a short `raw_prefix`.
- Image generation:
- ```bash
- python scripts/agnes_api.py image --prompt "A luminous floating city above a misty canyon at sunrise, cinematic realism" --size 1024x768
- ```
- Image-to-image:
- ```bash
- python scripts/agnes_api.py image --prompt "Turn the scene into a rainy cyberpunk night while preserving composition" --image https://example.com/input.png --size 1024x768
- ```
- Text-to-video with polling:
- ```bash
- python scripts/agnes_api.py video --prompt "A cinematic shot of a cat walking on the beach at sunset" --poll
- ```
- Image-to-video:
- ```bash
- python scripts/agnes_api.py video --prompt "Animate subtle camera movement and natural lighting" --image https://example.com/image.png --poll
- ```
- Keyframe / multi-image video:
- ```bash
- python scripts/agnes_api.py video --prompt "Create a smooth cinematic transition between the two keyframes" --image https://example.com/a.png --image https://example.com/b.png --mode keyframes --poll
- ```
- Retrieve a video task:
- ```bash
- python scripts/agnes_api.py video-get video_123456
- ```
- Light live smoke test:
- ```bash
- python scripts/agnes_api.py smoke-test
- ```
- Image edit smoke test:
- ```bash
- python scripts/agnes_api.py smoke-test --include-image-edit
- ```
- Single video smoke test:
- ```bash
- python scripts/agnes_api.py smoke-test --video-case text-to-video
- ```
- ## Workflow
- - Prefer `agnes-2.0-flash` for text chat/completions.
- - Do not use Agnes Responses API multi-turn function calling for autonomous tool workflows. Live testing showed the provider can return `function_call` with overall `status=completed`, and submitting `function_call_output` with `previous_response_id` may fail. Use this skill's chat completions path for text generation and treat tool-calling as best-effort request-shape compatibility only.
- - Prefer `agnes-image-2.1-flash` for text-to-image, image-to-image, and high-information-density image generation. High-density generation is prompt-driven; include subject hierarchy, environment, secondary details, lighting, composition, and quality requirements.
- - Prefer `agnes-video-v2.0` for text-to-video, image-to-video, multi-image video, keyframe animation, prompt-based motion and scene control, cinematic output, asynchronous task creation, polling-based result retrieval, and seed-based reproducibility.
- - For image and video generation, convert any non-English user prompt to a fluent English generation prompt before calling the image/video API. English prompts are more stable for Agnes video generation. Preserve concrete visual details, style, lighting, composition, motion, camera instructions, and constraints during translation.
- - For videos, remember the API is asynchronous: create a task first, then poll or retrieve by `video_id` when the create response includes it. The script falls back to legacy `task_id` lookup only when `video_id` is absent.
- - The script validates image sizes, video frame counts, frame rates, and dimensions before sending requests. `num_frames` must be `8n + 1` and `<= 441`; `81` or `121` are good short values.
- - The video command defaults to `num_frames=121` and `frame_rate=24` for more stable generation. Video smoke tests default to `num_frames=81` and `frame_rate=24`.
- - Warn the user before costly or long-running live video generation unless they explicitly asked to test or generate video.
- - Test video capabilities one at a time with `smoke-test --video-case <case>` to avoid creating many tasks at once. Supported cases are `text-to-video`, `image-to-video`, `multi-image`, and `keyframes`.
- ## Current Validation Notes
- - Confirmed locally: skill metadata validation and Python syntax.
- - Confirmed by live API: basic text, streaming text, tool-calling request shape, text-to-image, image-to-image, high-information-density text-to-image, Chinese prompt translation for image/video, completed text-to-video URL retrieval, and completed image-to-video URL retrieval.
- - Caveat: Agnes may accept tool-calling request parameters without consistently returning `tool_calls`; use `smoke-test --strict-tools` when strict tool-call validation is required.
- - Caveat: Agnes Responses API multi-turn function calling is not reliable for agent tool loops; do not rely on it for Codex/Claude-style automatic tool continuation.
- - Supported by the script and smoke-test selector, but not re-run end-to-end in the latest pass: multi-image video and keyframe animation.
- - Not yet confirmed end-to-end: completed URL retrieval for every multi-image video and keyframe animation task. A previous text-to-video task returned a provider-side `division by zero` error, so keep video retries visible and report provider errors clearly.
- ## Output Handling
- - Return generated image/video URLs directly by default. Do not download, save, open, or inspect generated media unless the user explicitly asks for a local file or visual inspection.
- - For image responses, expect URL-style results when `extra_body.response_format` is `url`.
- - For video responses, extract URLs from `video_url`, `url`, or `remixed_from_video_id` when `status` is `completed`.
- - For video retrieval, prefer `GET /agnesapi?video_id=...&model_name=agnes-video-v2.0`; legacy `GET /v1/videos/{task_id}` remains a fallback.
- - If a request fails, report HTTP status and provider error body without exposing the API key.
README.md · README · 265 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Agnes AI Generation Skill
- [English](README_EN.md)
- 用于 Agent Skills 的 Agnes AI 生成技能,封装 Agnes 官方文本、图片、视频 API。它采用标准 `SKILL.md` 结构,可安装到 Codex、Claude Code、OpenClaw、Cursor、Windsurf 等支持 Agent Skills 的客户端。安装后,你可以让 AI 直接调用 Agnes 模型完成文生图、图生图、文生视频、图生视频、多图视频、关键帧动画等操作。
- 官网与 API 平台:[https://platform.agnes-ai.com/](https://platform.agnes-ai.com/)
- 最新版本:[v0.1.0 - Agnes Generation Skill](https://github.com/Yacey/agnes-ai-generation-skill/releases/tag/v0.1.0)
- 本版本重点修复:Agnes Video V2.0 优先使用新版 `video_id` 查询接口;生成图片/视频后默认只返回 `urls`,不主动下载媒体;明确 Agnes Responses API 多轮函数调用暂不适合作为 agent 自动工具循环。完整说明见 [Releases](https://github.com/Yacey/agnes-ai-generation-skill/releases)。
- ## 功能
- - 文本生成:`agnes-2.0-flash`
- - 流式文本响应
- - OpenAI 兼容的工具调用请求结构
- - 文生图:`agnes-image-2.1-flash`
- - 图生图 / 图片编辑:`agnes-image-2.1-flash`
- - 高信息密度图片生成
- - 文本转视频:`agnes-video-v2.0`
- - 图像转视频:`agnes-video-v2.0`
- - 多图像视频生成
- - 关键帧动画
- - 基于提示词的运动与场景控制
- - 电影感视觉输出
- - 异步视频任务创建
- - 轮询式视频结果检索
- - 基于 seed 的可重复生成
- - 自动将非英文图片/视频提示词翻译为英文提示词,提高 Agnes 视频生成稳定性
- ## 快速开始
- ### 1. 申请 Agnes API Key
- 1. 打开 Agnes API 平台:[https://platform.agnes-ai.com/](https://platform.agnes-ai.com/)
- 2. 注册或登录账号。
- 3. 在平台中申请 / 创建 API Key。
- 4. 拿到 API Key 后,可以在可信任的当前 AI 会话里发送给 AI,或配置为本机环境变量。
- 安全提醒:不要把 API Key 写入 Git 仓库、README、截图或公开聊天记录。
- ### 2. 安装本 Skill
- 安装到当前 Agent:
- ```powershell
- npx skills add Yacey/agnes-ai-generation-skill
- ```
- 安装到所有支持的 Agent:
- ```powershell
- npx skills add Yacey/agnes-ai-generation-skill --all
- ```
- 安装后,当你要求已安装的 AI Agent 使用 Agnes 生成图片或视频时,AI 会自动触发本 skill。
- ### 3. 配置 API Key
- 临时配置当前 PowerShell 会话:
- ```powershell
- $env:AGNES_API_KEY="YOUR_API_KEY"
- ```
- Windows 用户级持久配置:
- ```powershell
- [Environment]::SetEnvironmentVariable("AGNES_API_KEY", "YOUR_API_KEY", "User")
- ```
- 脚本也会识别以下变量名:
- - `AGNES_API_KEY`
- - `AGNES_API_TOKEN`
- - `APIHUB_AGNES_API_KEY`
- ### 4. 开始使用
- 你可以直接对 AI 说:
- ```text
- 使用 Agnes 帮我生成一张高信息密度的未来城市图片。
- ```
- 或:
- ```text
- 使用 Agnes 把这张图片生成一段电影感视频。
- ```
- 如果你已经把 API Key 发送给当前 AI,AI 可以配置环境变量并调用本 skill。之后即可解锁生图、生视频等相关操作。
- ## 命令示例
- 文本生成:
- ```powershell
- python scripts/agnes_api.py text --prompt "Write a concise product tagline for an AI assistant."
- ```
- 文生图:
- ```powershell
- python scripts/agnes_api.py image --prompt "A luminous floating city above a misty canyon at sunrise, cinematic realism" --size 1024x768
- ```
- 中文提示词文生图,脚本会先自动翻译成英文:
- ```powershell
- python scripts/agnes_api.py image --prompt "一座高信息密度的未来城市集市,拥挤人群,飞行汽车,全息招牌,电影感写实风格"
- ```
- 图生图:
- ```powershell
- python scripts/agnes_api.py image --prompt "Turn the scene into a rainy cyberpunk night while preserving composition" --image https://example.com/input.png
- ```
- 文生视频:
- ```powershell
- python scripts/agnes_api.py video --prompt "A cinematic shot of a cat walking on the beach at sunset" --poll
- ```
- 视频命令默认使用 `--num-frames 121 --frame-rate 24`,以减少缺少关键视频参数导致的不稳定。脚本会在请求前检查 `num_frames` 是否满足 `8n + 1` 且不超过 `441`,并检查帧率、尺寸等基础参数。
- 图生视频:
- ```powershell
- python scripts/agnes_api.py video --prompt "Animate subtle camera movement and natural lighting" --image https://example.com/image.png --poll
- ```
- 多图 / 关键帧视频:
- ```powershell
- python scripts/agnes_api.py video --prompt "Create a smooth cinematic transition between the two keyframes" --image https://example.com/a.png --image https://example.com/b.png --mode keyframes --poll
- ```
- 查询视频任务:
- ```powershell
- python scripts/agnes_api.py video-get video_123456
- ```
- 默认输出会整理出常用字段,例如 `content`、`urls`、`translated_prompt`、`next_steps`,同时保留 `raw` 原始响应,方便 AI 和人工继续处理。
- 默认情况下,生成图片或视频后直接返回 `urls` 即可;除非用户明确要求下载、保存或检查本地文件,否则不需要把媒体下载到本地。
- 流式文本也会聚合输出 `content`,同时保留事件数量、是否完成和原始响应前缀,便于快速判断流式接口是否正常。
- 视频创建接口如果返回 `video_id`,脚本会优先使用新版 `video_id` 查询接口:`/agnesapi?video_id=...`。如果旧响应没有 `video_id`,脚本才回退到兼容的 `task_id` 查询接口。视频完成后,脚本会从 `video_url`、`url` 或 Agnes 实测返回中的 `remixed_from_video_id` 提取可直接访问的 mp4 链接,并放入 `urls`。
- 注意:Agnes Responses API 的多轮函数调用目前不适合作为 Codex / Claude Code 这类 agent 的自动工具循环模型。本 skill 的脚本使用 chat completions 路径;工具调用只应视为请求结构兼容能力,而不是稳定的多轮工具执行能力。
- 若只想看 Agnes 原始响应,可以加:
- ```powershell
- --raw
- ```
- 运行测试:
- ```powershell
- python scripts/agnes_api.py smoke-test
- ```
- 默认测试覆盖文本、流式文本、工具调用请求结构和文生图,不会创建视频任务。工具调用请求有时会被 Agnes 接收但不返回 `tool_calls`,默认只输出 warning;如果你想把这种情况视为失败,可以使用:
- ```powershell
- python scripts/agnes_api.py smoke-test --strict-tools
- ```
- 测试图生图:
- ```powershell
- python scripts/agnes_api.py smoke-test --include-image-edit
- ```
- 单独测试某个视频能力,避免一次创建太多视频任务:
- ```powershell
- python scripts/agnes_api.py smoke-test --video-case text-to-video
- ```
- 可选的视频测试项:
- - `text-to-video`
- - `image-to-video`
- - `multi-image`
- - `keyframes`
- ## 提示词语言策略
- Agnes 视频生成使用英文提示词更稳定。因此本 skill 的脚本默认会检测图片/视频提示词中的非英文字符,并先调用 `agnes-2.0-flash` 翻译成英文生成提示词,再调用图片或视频 API。
- 翻译时会保留:
- - 主体
- - 场景
- - 风格
- - 光照
- - 构图
- - 镜头运动
- - 动作描述
- - 负面提示词或约束
- 如果你确实想跳过自动翻译,可以加:
- ```powershell
- --no-translate-prompt
- ```
- 示例:
- ```powershell
- python scripts/agnes_api.py video --prompt "中文提示词" --no-translate-prompt
- ```
- ## 测试状态
- 已通过真实 API 测试:
- - 基础文本生成
- - 流式文本
- - 工具调用请求结构
- - 文生图
- - 图生图
- - 高信息密度文生图
- - 中文提示词自动翻译后文生图
- - 中文提示词自动翻译后文生视频任务创建
- - 文生视频完成并返回 mp4 URL
- - 图生视频完成并返回 mp4 URL
- 已支持但本轮未完整端到端重测:
- - 多图视频
- - 关键帧视频
- 尚未完整端到端验证:
- - 每一种多图视频 / 关键帧视频任务都成功返回最终视频 URL
- 说明:曾有一次真实文生视频任务在查询时返回 Agnes 服务端 `division by zero` 错误;后续短文生视频任务已成功完成并返回 mp4 URL。因此视频能力在 skill 中已支持,但仍建议逐个模式测试并保留 provider 错误信息。
- ## 仓库结构
- ```text
- .
- ├── SKILL.md
- ├── README.md
- ├── README_EN.md
- ├── LICENSE
- ├── agents/
- │ └── openai.yaml
- ├── references/
- │ └── api.md
- └── scripts/
- └── agnes_api.py
- ```
- ## 许可证
- MIT License. See [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.