Agnes AI Generation Skill is a standard Agent Skills package for calling Agnes AI text, image, and video generation APIs. It can be installed into Codex, Claude Code, OpenClaw, Cursor, Windsurf, and other clients that support Agent Skills. After installation, AI agents can use Agnes models for text generation, text-to-image, image-to-image, text-to-video, image-to-video, multi-image video, and keyframe animation workflows.

Official platform: https://platform.agnes-ai.com/

Latest release: v0.1.0 - Agnes Generation Skill

This release prioritizes the newer Agnes Video V2.0 video_id result lookup, returns generated media urls by default without downloading files, and documents that Agnes Responses API multi-turn function calling is not suitable for agent automatic tool loops yet. See Releases for the full notes.

Features

Text generation with agnes-2.0-flash
Streaming text responses
OpenAI-compatible tool-calling request shape
Text-to-image with agnes-image-2.1-flash
Image-to-image editing with agnes-image-2.1-flash
High-information-density image generation
Text-to-video with agnes-video-v2.0
Image-to-video with agnes-video-v2.0
Multi-image video generation
Keyframe animation
Prompt-based motion and scene control
Cinematic video output
Asynchronous video task creation
Polling-based video result retrieval
Seed-based reproducibility
Automatic English prompt translation for non-English image/video prompts

Quick Start

1. Apply for an Agnes API Key

Open https://platform.agnes-ai.com/.
Register or sign in.
Create an API key from the platform.
Provide the API key to the AI in a trusted current session, or configure it as a local environment variable.

Do not commit API keys to Git, README files, screenshots, or public chat logs.

2. Install This Skill

Install into the current agent:

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

Install into all supported agents:

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

3. Configure the API Key

For the current PowerShell session:

$env:AGNES_API_KEY="YOUR_API_KEY"

For persistent Windows user-level configuration:

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

The script also accepts:

AGNES_API_KEY
AGNES_API_TOKEN
APIHUB_AGNES_API_KEY

4. Use the Skill

Ask your AI agent:

Use Agnes to generate a high-information-density futuristic city image.

Or:

Use Agnes to turn this image into a cinematic video.

Usage Examples

Text:

python scripts/agnes_api.py text --prompt "Write a concise product tagline for an AI assistant."

Text-to-image:

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

Image-to-image:

python scripts/agnes_api.py image --prompt "Turn the scene into a rainy cyberpunk night while preserving composition" --image https://example.com/input.png

Text-to-video:

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

Video commands default to --num-frames 121 --frame-rate 24 to reduce instability from missing core video parameters. The script validates num_frames before sending requests: it must satisfy 8n + 1 and be no more than 441. It also checks frame rate and dimensions.

Image-to-video:

python scripts/agnes_api.py video --prompt "Animate subtle camera movement and natural lighting" --image https://example.com/image.png --poll

Multi-image / keyframe video:

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:

python scripts/agnes_api.py video-get video_123456

By default, command output is normalized with common fields such as content, urls, translated_prompt, and next_steps, while preserving the provider response under raw.

By default, return generated image or video urls directly. Do not download, save, or inspect media locally unless the user explicitly asks for a local file or visual inspection.

Streaming text output also includes aggregated content, event count, completion status, and a short raw prefix so the result is easier to inspect.

When the create response includes video_id, the script prefers the newer result endpoint: /agnesapi?video_id=.... It falls back to the legacy task_id endpoint only when video_id is absent. For completed video tasks, the script extracts direct mp4 URLs from video_url, url, or the live-response field remixed_from_video_id, then places them in urls.

Note: Agnes Responses API multi-turn function calling is currently not suitable as the automatic tool-loop model for agents such as Codex or Claude Code. This skill's script uses the chat completions path; tool calling should be treated as request-shape compatibility rather than stable multi-turn tool execution.

Add --raw to print only the original Agnes response:

--raw

Light smoke test. By default, this checks text, streaming text, tool-calling request shape, and text-to-image only. It does not create video tasks:

python scripts/agnes_api.py smoke-test

The tool-calling request can be accepted by Agnes without returning tool_calls consistently. By default this is reported as a warning. Use strict mode to fail in that case:

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

Image-to-image smoke test:

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

Single video case test:

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

Prompt Language

English prompts are more stable for Agnes video generation. For image and video calls, this skill automatically translates non-English prompts to English before sending them to the Agnes image/video APIs. It preserves subjects, scene details, style, lighting, composition, camera movement, motion, and constraints.

To disable automatic translation:

python scripts/agnes_api.py video --prompt "non-English prompt" --no-translate-prompt

Validation Status

Confirmed by live API:

Basic text
Streaming text
Tool-calling request shape
Text-to-image
Image-to-image
High-information-density text-to-image
Non-English prompt auto-translation for text-to-image
Non-English prompt auto-translation for text-to-video task creation
Completed text-to-video retrieval with a direct mp4 URL
Completed image-to-video retrieval with a direct mp4 URL

Supported but not fully re-tested end-to-end in the latest pass:

Multi-image video
Keyframe video

Not fully confirmed end-to-end yet:

Completed URL retrieval for every multi-image video and keyframe animation task

A previous live text-to-video retrieval returned a provider-side division by zero error; a later short text-to-video task completed successfully and returned an mp4 URL. Keep provider errors visible when retrying video modes.

License

MIT License. See LICENSE.