Feature: Support Agnes AI Image & Video Model Forwarding / 支持转发 Agnes AI 图像与视频模型

[ivysrono]

Problem / 问题

CLIProxyAPI currently cannot forward requests to Agnes AI's image and video models (by Sapiens AI, Singapore — top-10 global AI lab). Agnes provides free, unlimited multimodal API:

Modality	Model	Endpoint
Text	agnes-2.0-flash	/v1/chat/completions ✅ (works via openai-compatibility)
Image	agnes-image-2.1-flash	/v1/images/generations ❌
Video	agnes-video-v2.0	/v1/videos (async) + polling ❌

When you try model: agnes-image-2.1-flash on /v1/images/generations, it either 404s or routes to Codex. /v1/videos doesn't exist at all.

Root Causes / 根因

1. CLI-first architecture — CLIProxyAPI wraps CLI tools via executors. Agnes is a pure REST API with no CLI → no AgnesExecutor.
2. Image gen hardwired to Codex — openai_images_handlers.go injects image_generation tool into Codex requests, not a generic passthrough.
3. No /v1/videos endpoint — video support only exists for Google Veo via Gemini-specific paths.
4. Async mismatch — Agnes video is async (create → poll), while handlers are primarily sync/stream.
5. openai-compatibility only routes chat — image/video requests are silently dropped.

Proposed Solution / 方案建议

Option A (Recommended): Dedicated agnes provider

Add an agnes provider section in config.yaml (similar to xAI/Grok pattern):

agnes:
  api-key-entries:
    - api-key: "sk-agnes-xxx"
  models:
    - name: "agnes-image-2.1-flash"
    - name: "agnes-video-v2.0"

Changes needed:

• New internal/provider/agnes/ — executor implementing auth.ProviderExecutor
• Modify openai_images_handlers.go — add generic image routing (not just Codex)
• New openai_videos_handlers.go — async video create + poll endpoints
• Modify internal/config/ — add Agnes config schema
• Modify cmd/server/main.go — register routes

Image forwarding is nearly zero-translation (Agnes uses OpenAI-compatible /v1/images/generations). Video requires async handling with remixed_from_video_id → video_url normalization.

Option B (Lighter): Extend openai-compatibility

openai-compatibility:
  - name: "agnes"
    base-url: "https://apihub.agnes-ai.com/v1"
    api-key-entries:
      - api-key: "sk-agnes-xxx"
    forward-images: true
    forward-videos: true

Harder to implement cleanly — image/video fundamentally differ from chat completions in endpoint/response patterns.

Why This Matters / 为什么重要

• Cost: Agnes models are free, unlimited, indefinitely — zero API cost for image/video gen
• Convenience: Use any OpenAI-compatible client (Cursor, Cline) with a single proxy endpoint
• Multi-modal pipeline: Text → Image → Video through one unified config
• Community demand: Agnes recently announced indefinite free API, gaining rapid adoption

Reference / 参考

• Agnes API docs: https://agnes-ai.com/doc/overview
• Video params: POST /v1/videos with width, height, num_frames (8n+1), frame_rate, image, mode, seed
• CLIProxyAPI SDK: docs/sdk-advanced.md (custom providers), examples/custom-provider/

---

Written 2026-06-15, info verified against CLIProxyAPI v7.2.5 and Agnes AI public docs.