Agnes AI Full-Modal Generation Skill

Overview

This Skill encapsulates all generation capabilities of Agnes AI (Sapiens AI), unified through a single CLI script:

Text Generation: agnes-2.5-flash (supports Thinking reasoning mode, $0)
Image Understanding/Vision: agnes-2.5-flash (OpenAI Vision API compatible, can analyze image content)
Text-to-Image / Image-to-Image: agnes-image-2.5-flash (latest generation, optimized for high information density; use --model agnes-image-2.1-flash to fallback to previous generation)
Video Engine One (V2.0): agnes-video-v2.0 — text-to-video / image-to-video / keyframe animation, free frame rate and resolution, $0/second
Video Engine Two (Video 2.5 Flash): agnes-video-2.5-flash — next-generation model, three modes (text/keyframe/reference), multimodal reference, limited-time free at 720P; paid upgrade --model agnes-video-2.5 unlocks 960P/2K and video reference
Automatic Translation: Chinese prompts are automatically translated to English before API call
Asynchronous Polling: Video tasks automatically poll until completion

Prerequisites

Ensure your API Key is configured:
- Priority reads the hardcoded API_KEY in scripts/agnes_client.py
- If it is a placeholder YOUR_AGNES_API_KEY_HERE, fall back to reading the environment variable AGNES_API_KEY
- If neither is configured, remind the user to set the API Key in code or environment variable
Python 3.8+, standard libraries urllib + json required, no extra dependencies.

CLI Command Quick Reference

Script location: scripts/agnes_client.py

# Text generation
python scripts/agnes_client.py text "your prompt"
python scripts/agnes_client.py text "Hello" --stream
python scripts/agnes_client.py text "Write a quick sort for me" --thinking  # 2.5 reasoning mode

# Text-to-Image (agnes-image-2.5-flash, default 1K; recommended format size + ratio)
python scripts/agnes_client.py image "A futuristic city at sunset, cinematic realism" --size 2K --ratio 16:9
python scripts/agnes_client.py image "A cat walking under moonlight"
python scripts/agnes_client.py image "..." --model agnes-image-2.1-flash   # Fallback to previous generation

# Image-to-Image (automatic ratio detection — outputs at main reference image ratio by default)
python scripts/agnes_client.py image "Transform to cyberpunk night" --image-url "https://...input.png" --image-url "https://...ref.png"

# Image-to-Image + manual ratio (no auto-detection)
python scripts/agnes_client.py image "Transform to cyberpunk night" --image-url "https://...input.png" --ratio 16:9

# ── Video Engine One: V2.0 (free frame rate/resolution, $0) ──
python scripts/agnes_client.py video "A drone flying over mountains at sunrise" --poll          # Text-to-video
python scripts/agnes_client.py video "Add motion to this scene" --image-url "https://...frame.png" --poll  # Image-to-video
python scripts/agnes_client.py video --keyframes "https://a.com/1.png,https://a.com/2.png,https://a.com/3.png" --poll  # Keyframe animation

# ── Video Engine Two: Video 2.5 Flash (next generation, free 720P) ──
python scripts/agnes_client.py video25 "Rainy futuristic city street, neon reflections, cinematic camera movement" --poll          # Text text-to-video
python scripts/agnes_client.py video25 "Character naturally turns and walks towards the window" --first-frame "https://.../f.png" --last-frame "https://.../l.png" --poll  # Keyframe first/last frames
python scripts/agnes_client.py video25 "Using <Picture 1> as character reference running through a flower field" --image-url "https://.../char.png" --poll  # Reference image reference
python scripts/agnes_client.py video25 "Following the rhythm of <Audio 1> to generate a night scene" --audio-url "https://.../music.mp3" --poll  # Reference audio reference
python scripts/agnes_client.py video25 "..." --model agnes-video-2.5 --size 960P               # Paid upgrade (960P/2K)

# Submit video task without waiting
python scripts/agnes_client.py video "..." --no-poll
python scripts/agnes_client.py video25 "..." --no-poll

# Query video task status (use --model for V2.5 tasks)
python scripts/agnes_client.py video-status TASK_ID
python scripts/agnes_client.py video-status TASK_ID --model agnes-video-2.5-flash

# Translate Chinese prompts
python scripts/agnes_client.py translate "A cat"

# Image Understanding / Vision (use agnes-2.5-flash to analyze image content)
python scripts/agnes_client.py vision --image-url "https://example.com/photo.png"
python scripts/agnes_client.py vision --image-url "https://example.com/photo.png" --prompt "What brand is this watch?"

# Smoke test (verify API connectivity)
python scripts/agnes_client.py smoke-test

Complete Workflows

Text-to-Image Flow

Receive user's Chinese/English prompt
If it contains Chinese and --no-translate is not specified, automatically call agnes-2.5-flash to translate to English
Call POST /v1/images/generations (model default: agnes-image-2.5-flash)
Extract the image URL from data[0].url in the response
Return the result to the user (display the URL, or attempt to open it with curl/browser)

Size recommendation: for text-to-image, use the format --size 2K --ratio 16:9 to get predictable sizes; unsupported exact sizes (e.g., 1920x1080) will be normalized by the server, requiring manual cropping.

Image-to-Image Flow

Confirm the user has provided an input image URL or local path
If prompt translation is needed, perform translation
Call the same endpoint, passing an array of input image URLs in extra_body.image
Return the generated result

Video Generation Flow (Engine Selection)

The Skill includes two video engines; choose according to your needs:

Engine	Subcommand	Model	Features	Price
V2.0	`video`	`agnes-video-v2.0`	t2v/ti2vid/keyframes, free frame rate (num_frames 8n+1) and resolution	$0/second
Video 2.5	`video25`	`agnes-video-2.5-flash` (default) / `agnes-video-2.5` (paid)	Next generation: text/keyframe/reference, reference images/audio, more controllable shots	Flash limited-time free

Video 2.5 Flash (video25) Workflow:

Automatically infer mode from materials (--mode auto), or specify explicitly:
- text: plain text → no media parameters
- keyframe: --first-frame / --last-frame (at least one) constrains start/end composition
- reference: --image-url (≤5 images) / --audio-url (≤3 clips); use <Picture N> / <Audio N> placeholders in the prompt to refer to materials
Submit POST /v1/videos, parameters: mode + seconds("4"~"12") + size(flash only 720P) + aspect_ratio + seed
Poll GET /agnesapi?video_id=<ID>&model_name=agnes-video-2.5-flash (keyframe/reference must include model_name)
After status completed, extract video URL from the response

⚠️ video25 and video have completely different parameter systems: video25 does not accept num_frames/width/height/fps/negative_prompt (will return 400).

Video Parameter Constraints (Engine One V2.0)

num_frames must satisfy 8n + 1, max 441
Default: num_frames=121, frame_rate=24 (approximately 5 seconds)
For quick testing, use --num-frames 81 (approximately 3.4 seconds)

Video Parameter Constraints (Engine Two Video 2.5)

seconds is a string "4"~"12", default "5"
size: flash fixed at 720P; paid model agnes-video-2.5 supports 720P/960P/2K
aspect_ratio: 21:9 / 16:9(default) / 4:3 / 1:1 / 3:4 / 9:16
Flash limitations: reference images ≤5, audio clips ≤3, video reference not supported (paid version supports videos)
Actual output for 720P 16:9 is approximately 1280x704

Image Understanding (Vision) Flow

agnes-2.5-flash supports OpenAI Vision API format multimodal input, can analyze image content and return text descriptions. This is a bridging solution to "give eyes to models without visual capabilities." Version 2.5's image understanding is stronger than 2.0, with more accurate detail recognition.

Ensure the image has been uploaded to a publicly accessible HTTP(S) URL
Call the vision command, passing the image URL + optional analysis prompt
Returns a text description, which can be directly passed as context to other models (e.g., "Please give improvement suggestions for the watch design in this image" — first use vision to get the description, then pass it to any text model for analysis)

Vision command parameters:

--image-url (required, can be specified multiple times): Image URL to analyze
--prompt (optional): Analysis prompt, defaults to "Describe this image in detail."
--system (optional): System prompt
--max-tokens (optional): Maximum output tokens, default 1000
--no-translate (optional): Skip automatic translation (recommended for English prompts)

Prompt Best Practices

Image Prompt Structure

[Subject] + [Scene] + [Style] + [Lighting] + [Composition] + [Quality]

Example:

A luxury watch with a black leather strap on a marble surface, soft studio lighting, macro photography, 8K detail, high visual density

Image-to-Image Prompt

Clearly describe what to change + what to keep:

Transform the background to a dark luxury setting while preserving the watch design and angle.

Video Prompt

Include camera movement and temporal elements:

A slow 360-degree rotation around the watch, revealing every detail, cinematic lighting, smooth movement

Pricing

Model	Pricing
`agnes-2.5-flash` (Text/Vision/Reasoning)	Free ($0/1M tokens)
`agnes-image-2.5-flash` (Image, latest gen)	Free ($0/image, all 1K~4K sizes)
`agnes-image-2.1-flash` (Image, previous gen)	Free ($0/image)
`agnes-video-v2.0` (Video Engine One)	Free ($0/second)
`agnes-video-2.5-flash` (Video Engine Two)	Limited-time free ($0/second, 720P)
`agnes-video-2.5` (Video, paid upgrade)	$0.025/second(720P) / $0.040/second(960P) / $0.055/second(2K)

Pricing is subject to the official website https://www.agnes-ai.com/zh-Hans/docs/pricing; free policies may be adjusted per platform announcements.

Known Limitations

2.5 Thinking mode returns the reasoning_content field (thought process), which adds a small amount of output tokens
Video generation occasionally experiences division by zero server-side errors
V2.0 multi-image video/keyframe animation has not been fully end-to-end validated
Image API only accepts HTTP(S) URLs as input, does not support base64 (input); output can be URL or Base64
agnes-video-2.5-flash only supports 720P, no video reference; use paid --model agnes-video-2.5 for 960P/2K or video reference
video25 keyframe/reference task queries must include --model agnes-video-2.5-flash

Automatic Ratio Detection (i2i)

For i2i, if --ratio is not specified, the script automatically detects the aspect ratio of the main reference image (the first --image-url) and maps it to one of the 8 official ratios supported by agnes-image-2.5-flash (1:1 / 3:4 / 4:3 / 16:9 / 9:16 / 2:3 / 3:2 / 21:9), avoiding canvas ratio mismatch with the input subject that could cause deformation.

# Auto-detection: will print [INFO] Main reference image: ... → auto ratio: ...
python scripts/agnes_client.py image "prompt" --image-url MODEL_URL --image-url REF_URL --size 2K

# Manual specification (skips auto-detection)
python scripts/agnes_client.py image "prompt" --image-url MODEL_URL --ratio 16:9

Main Reference Image Convention: The first --image-url is considered the subject that determines composition/ratio (usually the model/product image); the second and subsequent images are considered style/detail references. To switch the main reference image, swap the order of --image-url.

References

API detailed documentation: references/api_reference.md
Official website: https://agnes-ai.com/
API platform: https://platform.agnes-ai.com/

Agnes Multimodal

What is Agnes Multimodal?

Ask in your favorite AI

Documentation