Agnes AI Generation Skill: text, image and video generation inside Codex, Claude Code and Cursor

What the Agnes AI Generation Skill actually solves

Agnes exposes text, image and video models through an HTTP API at platform.agnes-ai.com. Calling that API from inside an editor means writing request code, handling polling, and remembering which parameters the video endpoint rejects. This project removes that step by packaging the calls as an Agent Skill: a directory with a SKILL.md file that clients such as Codex, Claude Code, OpenClaw, Cursor and Windsurf read, plus a Python script the agent invokes. The audience is narrow and specific. You need an Agnes API key, a client that supports the Agent Skills format, and a task where you would rather type a sentence than write a script. If you only need text, the wrapper adds little over a direct HTTP call. The value concentrates in the video path, where the script handles asynchronous job creation, polling, parameter validation and prompt translation.

How the skill routes a request from prompt to mp4 URL

The skill is a single Python entry point, scripts/agnes_api.py, with subcommands for text, image, video and video-get. The agent picks the subcommand, passes the prompt, and the script decides what happens next. For image and video prompts containing non-English characters, the script first calls agnes-2.0-flash to translate the prompt into English, preserving subject, scene, style, lighting, composition, camera movement, action description and any negative constraints, then sends the translated prompt to the generation model. The README states that Agnes video generation is more stable with English prompts, which is why this translation step exists by default. For video, the script creates an asynchronous task, polls for the result, and extracts an mp4 link from video_url, url, or the remixed_from_video_id field that Agnes returns in practice. Output is normalised into fields such as content, urls, translated_prompt and next_steps, with the untouched provider response kept under raw. The default branch uses the newer /agnesapi?video_id=... lookup when the create call returns a video_id, and falls back to the older task_id query only when it does not.

Installing the skill and generating your first image

The README gives the install as an npx command, run from PowerShell in the examples. Without --all it installs into the current agent; with --all it installs into every supported client.

npx skills add Yacey/agnes-ai-generation-skill

To install everywhere at once:

npx skills add Yacey/agnes-ai-generation-skill --all

Next, set the API key. The script recognises AGNES_API_KEY, AGNES_API_TOKEN and APIHUB_AGNES_API_KEY. The README shows a session-scoped variable and a Windows user-level persistent one.

$env:AGNES_API_KEY="YOUR_API_KEY"

[Environment]::SetEnvironmentVariable("AGNES_API_KEY", "YOUR_API_KEY", "User")

Then call the script directly. This text-to-image example passes a prompt and a size:

python scripts/agnes_api.py image --prompt "A luminous floating city above a misty canyon at sunrise, cinematic realism" --size 1024x768

Expect a JSON object with a urls field holding the generated image link. The README states the script does not download media by default; you get URLs unless you explicitly ask for a local file. A Chinese prompt works too, because the script translates it first:

python scripts/agnes_api.py image --prompt "一座高信息密度的未来城市集市，拥挤人群，飞行汽车，全息招牌，电影感写实风格"

For video, add --poll to wait for completion:

python scripts/agnes_api.py video --prompt "A cinematic shot of a cat walking on the beach at sunset" --poll

The README states the video command defaults to --num-frames 121 --frame-rate 24 to avoid instability from missing parameters.

The num_frames constraint and the division by zero error

The video endpoint has a hard arithmetic rule, and the script enforces it before sending anything. num_frames must satisfy 8n + 1 and must not exceed 441. The default of 121 fits both conditions. If you pass a value that breaks the rule, the script fails locally rather than spending an API call. That is the right place for this check, but it also means the wrapper will reject values the provider might have accepted, and the README does not explain where the 8n + 1 requirement comes from or whether it applies to every video model.

The more serious limitation is documented in the testing status. One real text-to-video task returned a server-side division by zero error during lookup; a later short task completed and returned an mp4 URL. The README therefore states that video capability is supported but recommends testing each mode individually and keeping provider error information. Multi-image video and keyframes video are listed as supported but not fully re-tested end to end, and the README says not every multi-image or keyframes task has been confirmed to return a final video URL. Treat those two modes as unproven. The skill also inherits a provider-side constraint: the README states that multi-turn function calling on the Agnes Responses API is not suitable as an automatic tool loop for agents like Codex or Claude Code, so tool calling here is request-shape compatibility, not a dependable execution loop.

Agnes skill versus calling the Agnes API yourself

The obvious alternative is a short Python script that posts to the Agnes endpoints directly. That gives you full control over retries, logging and parameter values, and it does not depend on a client supporting the Agent Skills format. What you lose is everything the wrapper does around the call: the 8n + 1 validation before the request, the automatic English translation of non-English prompts, the video_id to task_id fallback, and the normalised output with urls and next_steps separated from raw. If your prompts are already English and your frame counts are already valid, the wrapper's advantage shrinks to convenience. If they are not, you are reimplementing the same logic. A second alternative is to use the Agnes platform directly through its web interface, which avoids code entirely but cannot be triggered from inside an agent conversation. The README does not compare the skill to any other tool, so the trade-off above is drawn from what the script does, not from a benchmark.

Testing, maintenance and the MIT licence

The repository has one release, v0.1.0, published on 2026-06-21, and the last push to master was on the same day. That is the entire maintenance record. There is no changelog beyond the release notes, no CI configuration visible in the repository layout, and no issue tracker activity described. The README lists what has been tested against the real API: basic text generation, streaming text, tool-call request structure, text-to-image, image-to-image, high-information-density text-to-image, translated-prompt image generation, translated-prompt video task creation, and completed text-to-video and image-to-video jobs returning mp4 URLs. That list is useful because it tells you which paths someone actually exercised. It is also a snapshot from one release, and the README does not say when it was taken.

The licence is MIT, stated in the README and present as a LICENSE file at the repository root. MIT permits commercial use, modification and redistribution with the licence text retained. It says nothing about the Agnes API itself, which is a separate service governed by the platform's own terms, and nothing about the cost of the API calls the skill makes. If you fork the script, you keep the copyright notice; if you ship it inside a product, the API key handling is your problem, not the licence's.

Running the smoke test before you trust the skill

The script ships with its own test command, and it is the fastest way to find out whether your key and network path work. By default it covers text, streaming text, the tool-call request structure and text-to-image, and it does not create video tasks.

python scripts/agnes_api.py smoke-test

Tool-call requests are sometimes accepted by Agnes without returning tool_calls; the default smoke test only emits a warning for that. If you want it treated as a failure, add the strict flag:

python scripts/agnes_api.py smoke-test --strict-tools

Image editing is excluded by default and needs an explicit flag:

python scripts/agnes_api.py smoke-test --include-image-edit

Video is deliberately not part of the default run, because each test creates a real job. Test one mode at a time. The valid values are text-to-video, image-to-video, multi-image and keyframes:

python scripts/agnes_api.py smoke-test --video-case text-to-video

If you want to see the provider's untouched response for any command, add --raw. That flag is the right tool when a video job fails and you need the provider error text rather than the normalised output.

Editorial conclusion

Adopt it if you already have an Agnes API key and you want an agent to create images or video without leaving the chat, and if you accept that multi-image and keyframes video have not been fully verified end to end. Do not adopt it if you need a stable multi-turn tool-calling loop: the README states that the Agnes Responses API is not suitable as an automatic tool loop for agents, and this skill uses the chat completions path instead. Before relying on it, run python scripts/agnes_api.py smoke-test, then test each video mode you intend to use one at a time with --video-case, and check references/api.md for the request fields the README does not list.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. Yacey/agnes-ai-generation-skill on GitHub