Agnes AI

Official gateway and model catalog for Agnes AI.

Agnes AI gives developers OpenAI-compatible access to multimodal models for text, image, video, and agent workflows through a unified API gateway.

Documentation Status

Quick Links

Agnes AI provides two official sites: the International site and the China site. Choose the site that matches your region and service needs.

Developer Resources

Models

Python Quick Start

Install the example dependencies:

pip install -r requirements.txt
export AGNES_API_KEY="your_api_key_here"

Run a streaming chat completion:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_AGNES_API_KEY",
    base_url="https://apihub.agnes-ai.com/v1",
)

response = client.chat.completions.create(
    model="agnes-2.5-flash",
    messages=[
        {"role": "user", "content": "Write a short intro to Agnes AI."}
    ],
    stream=True,
)

for chunk in response:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="")

Python examples:

Current Access and Limits

The values below are current public reference values as of 2026-06-28. Base Token Plan quotas were published on 2026-06-22; video RPM limits were updated on 2026-06-28. These are operational limits, not permanent guarantees.

User Plans

Subscription Quotas

For detailed per-model RPM tables, quota rules, and API key pool behavior, see MODEL_CATALOG.md and docs/TOKEN_PLAN_FAQ.md.

Chat Example

curl https://apihub.agnes-ai.com/v1/chat/completions \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-2.0-flash",
    "messages": [
      {
        "role": "user",
        "content": "Explain how to integrate an OpenAI-compatible API gateway."
      }
    ],
    "stream": true
  }'

Image Example

curl https://apihub.agnes-ai.com/v1/images/generations \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "A luminous floating city above a misty canyon at sunrise, cinematic realism",
    "size": "1024x768"
  }'

Video Example

curl -X POST https://apihub.agnes-ai.com/v1/videos \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "prompt": "A cinematic shot of a cat walking on the beach at sunset, soft ocean waves, warm golden lighting, realistic motion",
    "height": 768,
    "width": 1152,
    "num_frames": 121,
    "frame_rate": 24
  }'

Video generation is asynchronous. Create a task first, then query the result with the returned video_id.

GET https://apihub.agnes-ai.com/agnesapi?video_id=<VIDEO_ID>

Use video_id for video result polling. Do not use task_id for current video result queries unless a specific legacy workflow explicitly requires it.

Common Integration Notes

• Use Authorization: Bearer YOUR_API_KEY for every request.
• Keep API keys in server-side environment variables. Never expose keys in client-side code or public repositories.
• agnes-2.5-flash is fully available to users with Agnes API access. It is OpenAI-compatible with agnes-2.0-flash: the base URL, endpoint, request format, streaming, tool calling, and image URL input stay the same. Current public reference: 512K context and 65.5K maximum output. Availability, rate limits, and billing are determined by account and API key permissions.
• agnes-2.0-flash currently supports a 256K context window and 64K max output reference limit after the June 2026 rollback from the temporary 1M context window.
• Thinking mode, streaming, tool calling, and vision inputs are supported on compatible chat workflows. Check the model-specific docs before enabling advanced parameters in production.
• For 400 responses, verify required parameters, request body shape, image URL accessibility, and response format placement.
• For 401 responses, verify the API key, bearer token format, account status, and environment variable loading.
• For 429 responses, reduce concurrency, add retry with backoff, and check the current plan-level RPM limit.
• For 500, 502, 503, or 520 responses, retry with exponential backoff and inspect whether the request payload can be simplified.

Security

Never commit API keys, tokens, .env files, screenshots containing secrets, or private data.

Use environment variables for local development:

export AGNES_API_KEY="your_api_key_here"

Documentation

See the official docs for model-specific parameters, response formats, pricing, limits, and troubleshooting:

• https://agnes-ai.com/doc/overview
• https://agnes-ai.com/doc/agnes-20-flash
• https://agnes-ai.com/zh-Hans/docs/agnes-25-flash
• https://agnes-ai.com/doc/agnes-image-20-flash
• https://agnes-ai.com/doc/agnes-image-21-flash
• https://agnes-ai.com/doc/agnes-video-v20