Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yacey-agnes-ai-generation-skill/badge.svg)](/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

i

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)

  1. ---
  2. name: agnes-ai-generation
  3. 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.
  4. ---
  5. # Agnes AI Generation
  6. Use this skill to call Agnes text, image, and video generation APIs through `https://apihub.agnes-ai.com`.
  7. ## Quick Start
  8. 1. Read `references/api.md` when endpoint details, parameters, or response fields are needed.
  9. 2. Use `scripts/agnes_api.py` for real API calls instead of rewriting curl by hand.
  10. 3. Require an API key in `AGNES_API_KEY`, `AGNES_API_TOKEN`, or `APIHUB_AGNES_API_KEY`. Never print the key.
  11. 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.
  12. ## Commands
  13. Text generation:
  14. ```bash
  15. python scripts/agnes_api.py text --prompt "Write a concise product tagline for an AI assistant."
  16. ```
  17. Streaming text:
  18. ```bash
  19. python scripts/agnes_api.py text --prompt "Write a short product intro." --stream
  20. ```
  21. Streaming output is normalized and includes aggregated `content`, `events`, `done`, and a short `raw_prefix`.
  22. Image generation:
  23. ```bash
  24. python scripts/agnes_api.py image --prompt "A luminous floating city above a misty canyon at sunrise, cinematic realism" --size 1024x768
  25. ```
  26. Image-to-image:
  27. ```bash
  28. 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
  29. ```
  30. Text-to-video with polling:
  31. ```bash
  32. python scripts/agnes_api.py video --prompt "A cinematic shot of a cat walking on the beach at sunset" --poll
  33. ```
  34. Image-to-video:
  35. ```bash
  36. python scripts/agnes_api.py video --prompt "Animate subtle camera movement and natural lighting" --image https://example.com/image.png --poll
  37. ```
  38. Keyframe / multi-image video:
  39. ```bash
  40. 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
  41. ```
  42. Retrieve a video task:
  43. ```bash
  44. python scripts/agnes_api.py video-get video_123456
  45. ```
  46. Light live smoke test:
  47. ```bash
  48. python scripts/agnes_api.py smoke-test
  49. ```
  50. Image edit smoke test:
  51. ```bash
  52. python scripts/agnes_api.py smoke-test --include-image-edit
  53. ```
  54. Single video smoke test:
  55. ```bash
  56. python scripts/agnes_api.py smoke-test --video-case text-to-video
  57. ```
  58. ## Workflow
  59. - Prefer `agnes-2.0-flash` for text chat/completions.
  60. - 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.
  61. - 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.
  62. - 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.
  63. - 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.
  64. - 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.
  65. - 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.
  66. - 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`.
  67. - Warn the user before costly or long-running live video generation unless they explicitly asked to test or generate video.
  68. - 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`.
  69. ## Current Validation Notes
  70. - Confirmed locally: skill metadata validation and Python syntax.
  71. - 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.
  72. - 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.
  73. - 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.
  74. - 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.
  75. - 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.
  76. ## Output Handling
  77. - 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.
  78. - For image responses, expect URL-style results when `extra_body.response_format` is `url`.
  79. - For video responses, extract URLs from `video_url`, `url`, or `remixed_from_video_id` when `status` is `completed`.
  80. - For video retrieval, prefer `GET /agnesapi?video_id=...&model_name=agnes-video-v2.0`; legacy `GET /v1/videos/{task_id}` remains a fallback.
  81. - 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)

  1. # Agnes AI Generation Skill
  2. [English](README_EN.md)
  3. 用于 Agent Skills 的 Agnes AI 生成技能,封装 Agnes 官方文本、图片、视频 API。它采用标准 `SKILL.md` 结构,可安装到 Codex、Claude Code、OpenClaw、Cursor、Windsurf 等支持 Agent Skills 的客户端。安装后,你可以让 AI 直接调用 Agnes 模型完成文生图、图生图、文生视频、图生视频、多图视频、关键帧动画等操作。
  4. 官网与 API 平台:[https://platform.agnes-ai.com/](https://platform.agnes-ai.com/)
  5. 最新版本:[v0.1.0 - Agnes Generation Skill](https://github.com/Yacey/agnes-ai-generation-skill/releases/tag/v0.1.0)
  6. 本版本重点修复:Agnes Video V2.0 优先使用新版 `video_id` 查询接口;生成图片/视频后默认只返回 `urls`,不主动下载媒体;明确 Agnes Responses API 多轮函数调用暂不适合作为 agent 自动工具循环。完整说明见 [Releases](https://github.com/Yacey/agnes-ai-generation-skill/releases)。
  7. ## 功能
  8. - 文本生成:`agnes-2.0-flash`
  9. - 流式文本响应
  10. - OpenAI 兼容的工具调用请求结构
  11. - 文生图:`agnes-image-2.1-flash`
  12. - 图生图 / 图片编辑:`agnes-image-2.1-flash`
  13. - 高信息密度图片生成
  14. - 文本转视频:`agnes-video-v2.0`
  15. - 图像转视频:`agnes-video-v2.0`
  16. - 多图像视频生成
  17. - 关键帧动画
  18. - 基于提示词的运动与场景控制
  19. - 电影感视觉输出
  20. - 异步视频任务创建
  21. - 轮询式视频结果检索
  22. - 基于 seed 的可重复生成
  23. - 自动将非英文图片/视频提示词翻译为英文提示词,提高 Agnes 视频生成稳定性
  24. ## 快速开始
  25. ### 1. 申请 Agnes API Key
  26. 1. 打开 Agnes API 平台:[https://platform.agnes-ai.com/](https://platform.agnes-ai.com/)
  27. 2. 注册或登录账号。
  28. 3. 在平台中申请 / 创建 API Key。
  29. 4. 拿到 API Key 后,可以在可信任的当前 AI 会话里发送给 AI,或配置为本机环境变量。
  30. 安全提醒:不要把 API Key 写入 Git 仓库、README、截图或公开聊天记录。
  31. ### 2. 安装本 Skill
  32. 安装到当前 Agent:
  33. ```powershell
  34. npx skills add Yacey/agnes-ai-generation-skill
  35. ```
  36. 安装到所有支持的 Agent:
  37. ```powershell
  38. npx skills add Yacey/agnes-ai-generation-skill --all
  39. ```
  40. 安装后,当你要求已安装的 AI Agent 使用 Agnes 生成图片或视频时,AI 会自动触发本 skill。
  41. ### 3. 配置 API Key
  42. 临时配置当前 PowerShell 会话:
  43. ```powershell
  44. $env:AGNES_API_KEY="YOUR_API_KEY"
  45. ```
  46. Windows 用户级持久配置:
  47. ```powershell
  48. [Environment]::SetEnvironmentVariable("AGNES_API_KEY", "YOUR_API_KEY", "User")
  49. ```
  50. 脚本也会识别以下变量名:
  51. - `AGNES_API_KEY`
  52. - `AGNES_API_TOKEN`
  53. - `APIHUB_AGNES_API_KEY`
  54. ### 4. 开始使用
  55. 你可以直接对 AI 说:
  56. ```text
  57. 使用 Agnes 帮我生成一张高信息密度的未来城市图片。
  58. ```
  59. 或:
  60. ```text
  61. 使用 Agnes 把这张图片生成一段电影感视频。
  62. ```
  63. 如果你已经把 API Key 发送给当前 AI,AI 可以配置环境变量并调用本 skill。之后即可解锁生图、生视频等相关操作。
  64. ## 命令示例
  65. 文本生成:
  66. ```powershell
  67. python scripts/agnes_api.py text --prompt "Write a concise product tagline for an AI assistant."
  68. ```
  69. 文生图:
  70. ```powershell
  71. python scripts/agnes_api.py image --prompt "A luminous floating city above a misty canyon at sunrise, cinematic realism" --size 1024x768
  72. ```
  73. 中文提示词文生图,脚本会先自动翻译成英文:
  74. ```powershell
  75. python scripts/agnes_api.py image --prompt "一座高信息密度的未来城市集市,拥挤人群,飞行汽车,全息招牌,电影感写实风格"
  76. ```
  77. 图生图:
  78. ```powershell
  79. python scripts/agnes_api.py image --prompt "Turn the scene into a rainy cyberpunk night while preserving composition" --image https://example.com/input.png
  80. ```
  81. 文生视频:
  82. ```powershell
  83. python scripts/agnes_api.py video --prompt "A cinematic shot of a cat walking on the beach at sunset" --poll
  84. ```
  85. 视频命令默认使用 `--num-frames 121 --frame-rate 24`,以减少缺少关键视频参数导致的不稳定。脚本会在请求前检查 `num_frames` 是否满足 `8n + 1` 且不超过 `441`,并检查帧率、尺寸等基础参数。
  86. 图生视频:
  87. ```powershell
  88. python scripts/agnes_api.py video --prompt "Animate subtle camera movement and natural lighting" --image https://example.com/image.png --poll
  89. ```
  90. 多图 / 关键帧视频:
  91. ```powershell
  92. 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
  93. ```
  94. 查询视频任务:
  95. ```powershell
  96. python scripts/agnes_api.py video-get video_123456
  97. ```
  98. 默认输出会整理出常用字段,例如 `content`、`urls`、`translated_prompt`、`next_steps`,同时保留 `raw` 原始响应,方便 AI 和人工继续处理。
  99. 默认情况下,生成图片或视频后直接返回 `urls` 即可;除非用户明确要求下载、保存或检查本地文件,否则不需要把媒体下载到本地。
  100. 流式文本也会聚合输出 `content`,同时保留事件数量、是否完成和原始响应前缀,便于快速判断流式接口是否正常。
  101. 视频创建接口如果返回 `video_id`,脚本会优先使用新版 `video_id` 查询接口:`/agnesapi?video_id=...`。如果旧响应没有 `video_id`,脚本才回退到兼容的 `task_id` 查询接口。视频完成后,脚本会从 `video_url`、`url` 或 Agnes 实测返回中的 `remixed_from_video_id` 提取可直接访问的 mp4 链接,并放入 `urls`。
  102. 注意:Agnes Responses API 的多轮函数调用目前不适合作为 Codex / Claude Code 这类 agent 的自动工具循环模型。本 skill 的脚本使用 chat completions 路径;工具调用只应视为请求结构兼容能力,而不是稳定的多轮工具执行能力。
  103. 若只想看 Agnes 原始响应,可以加:
  104. ```powershell
  105. --raw
  106. ```
  107. 运行测试:
  108. ```powershell
  109. python scripts/agnes_api.py smoke-test
  110. ```
  111. 默认测试覆盖文本、流式文本、工具调用请求结构和文生图,不会创建视频任务。工具调用请求有时会被 Agnes 接收但不返回 `tool_calls`,默认只输出 warning;如果你想把这种情况视为失败,可以使用:
  112. ```powershell
  113. python scripts/agnes_api.py smoke-test --strict-tools
  114. ```
  115. 测试图生图:
  116. ```powershell
  117. python scripts/agnes_api.py smoke-test --include-image-edit
  118. ```
  119. 单独测试某个视频能力,避免一次创建太多视频任务:
  120. ```powershell
  121. python scripts/agnes_api.py smoke-test --video-case text-to-video
  122. ```
  123. 可选的视频测试项:
  124. - `text-to-video`
  125. - `image-to-video`
  126. - `multi-image`
  127. - `keyframes`
  128. ## 提示词语言策略
  129. Agnes 视频生成使用英文提示词更稳定。因此本 skill 的脚本默认会检测图片/视频提示词中的非英文字符,并先调用 `agnes-2.0-flash` 翻译成英文生成提示词,再调用图片或视频 API。
  130. 翻译时会保留:
  131. - 主体
  132. - 场景
  133. - 风格
  134. - 光照
  135. - 构图
  136. - 镜头运动
  137. - 动作描述
  138. - 负面提示词或约束
  139. 如果你确实想跳过自动翻译,可以加:
  140. ```powershell
  141. --no-translate-prompt
  142. ```
  143. 示例:
  144. ```powershell
  145. python scripts/agnes_api.py video --prompt "中文提示词" --no-translate-prompt
  146. ```
  147. ## 测试状态
  148. 已通过真实 API 测试:
  149. - 基础文本生成
  150. - 流式文本
  151. - 工具调用请求结构
  152. - 文生图
  153. - 图生图
  154. - 高信息密度文生图
  155. - 中文提示词自动翻译后文生图
  156. - 中文提示词自动翻译后文生视频任务创建
  157. - 文生视频完成并返回 mp4 URL
  158. - 图生视频完成并返回 mp4 URL
  159. 已支持但本轮未完整端到端重测:
  160. - 多图视频
  161. - 关键帧视频
  162. 尚未完整端到端验证:
  163. - 每一种多图视频 / 关键帧视频任务都成功返回最终视频 URL
  164. 说明:曾有一次真实文生视频任务在查询时返回 Agnes 服务端 `division by zero` 错误;后续短文生视频任务已成功完成并返回 mp4 URL。因此视频能力在 skill 中已支持,但仍建议逐个模式测试并保留 provider 错误信息。
  165. ## 仓库结构
  166. ```text
  167. .
  168. ├── SKILL.md
  169. ├── README.md
  170. ├── README_EN.md
  171. ├── LICENSE
  172. ├── agents/
  173. │ └── openai.yaml
  174. ├── references/
  175. │ └── api.md
  176. └── scripts/
  177. └── agnes_api.py
  178. ```
  179. ## 许可证
  180. MIT License. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.