Agnes AI Documentation

Agnes AI provides an OpenAI-compatible API gateway for accessing multimodal models, including text, image, video, and Agent workflows. Developers can choose between the International site and the China site based on their region and service requirements.

API Base URL: https://apihub.agnes-ai.com/v1

Quick Links:

• International: https://agnes-ai.com/
• China: https://agnes-ai.cn/
• Developer Docs: https://agnes-ai.com/doc/overview
• API Platform: https://platform.agnes-ai.com/

Agnes AI access is governed by User Plans and Subscription Quotas.

User Plan RPM Limits

Subscription Quotas

Agnes AI uses three distinct access types. Each type operates within its own independent limit pool. A single user can hold multiple access types simultaneously (e.g., a free key, an enterprise key, and a Token Plan key), and they will not interfere with each other's limits.

• Free / default user: Standard access for users without a subscription or enterprise verification.
• Enterprise-verified user: Users with enterprise verification providing higher baseline RPM limits.
• Token Plan user: Subscribers with high RPM and specific subscription quotas.

Important: Creating multiple API keys of the same type does not increase your RPM or quota; all keys of the same type share the same limit pool.

If your Agnes AI API integration fails or behaves unexpectedly, follow this checklist to identify the cause:

1. Base URL: Ensure you are using https://apihub.agnes-ai.com/v1.
2. Authentication: Verify the header Authorization: Bearer YOUR_API_KEY is used.
3. Model Names: Ensure model names are spelled exactly as documented.
4. Endpoint Matching: Verify the endpoint matches the model family (e.g., use /v1/chat/completions for chat/reasoning).
5. Request Minimization: Reduce the request to a minimal reproducible example without private data.
6. Quota/Limits: Check current RPM and quota values in MODEL_CATALOG.md and TOKEN_PLAN_FAQ.md.
7. Retries: Implement retry logic with exponential backoff for transient 5xx errors.

Video generation is an asynchronous process. You must first create the task, and then poll the endpoint using the returned video_id to check for completion and retrieve the result.

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

Agnes AI provides OpenAI-compatible endpoints. To integrate agent clients, coding tools, or standard OpenAI SDKs, use the following configuration:

• Base URL: https://apihub.agnes-ai.com/v1
• API Key: Your unique Agnes AI API key
• Chat Endpoint: /v1/chat/completions
• Authentication Header: Authorization: Bearer YOUR_API_KEY

Base URL: https://apihub.agnes-ai.com/v1
API Key: YOUR_API_KEY
Chat endpoint: /v1/chat/completions

When troubleshooting issues, maintain sanitized request logs. A useful debug log should include the following fields (with all secrets and sensitive credentials removed):

• model
• endpoint
• timestamp
• request ID (if provided by the API)
• status code
• response body

When reporting an issue, provide the following details to ensure a fast resolution:

• Model
• Endpoint
• SDK or client used
• Minimal request body (with all secrets/API keys removed)
• Error code and error message
• Expected behavior
• Actual behavior
• Confirmation of whether the issue is reproducible

CRITICAL: Do not include API keys, private account data, or customer content in your issue.

When encountering transient errors, implement an exponential backoff strategy to avoid overwhelming the API and to increase the likelihood of successful subsequent requests.

Apply exponential backoff for the following status codes:

• 408 (Request Timeout)
• 429 (Too Many Requests)
• 500 (Internal Server Error)
• 502 (Bad Gateway)
• 503 (Service Unavailable)
• 504 (Gateway Timeout)
• 520 (Unknown Error)
• 522 (Connection Timed Out)
• 524 (A Timeout Occurred)

Video generation is an asynchronous process. First, create a task using the /v1/videos endpoint. Then, use the returned video_id to poll for the result.

Note: Use video_id for polling, not task_id (unless using a specific legacy workflow).

# 1. Create the video task
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
  }'

# 2. Poll for the result using the video_id
# GET https://apihub.agnes-ai.com/agnesapi?video_id=<VIDEO_ID>

When configuring your client or SDK to connect to Agnes AI, use the following base URL:

https://apihub.agnes-ai.com/v1