Agnes Videogen

Agnes Video Generation

Generate videos using the Agnes Video V2.0 API.

Prerequisites

• An Agnes AI API key from API Platform
• Base URL: https://apihub.agnes-ai.com/v1

API Architecture

Agnes Video V2.0 uses an asynchronous two-step workflow:

1. Create Video Task — submit the request, get a video_id
2. Retrieve Video Result — poll the video_id to get the final video

API Endpoints

Step 1: Create Video Task

Endpoint: POST https://apihub.agnes-ai.com/v1/videos

Headers:

• Authorization: Bearer YOUR_API_KEY
• Content-Type: application/json

Step 2: Retrieve Video Result

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

Headers:

• Authorization: Bearer YOUR_API_KEY

Optional parameter: model_name — specify model explicitly (e.g., agnes-video-v2.0)

Legacy method (compatibility): GET https://apihub.agnes-ai.com/v1/videos/<TASK_ID>

Model Name

agnes-video-v2.0

Request Parameters (Create Task)

Workflows

1. Text-to-Video

curl -X POST https://apihub.agnes-ai.com/v1/videos \
  -H "Authorization: Bearer YOUR_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
  }'

Response:

{
  "id": "task_YOUR_TASK_ID",
  "task_id": "task_YOUR_TASK_ID",
  "video_id": "video_YOUR_VIDEO_ID",
  "object": "video",
  "model": "agnes-video-v2.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1780457477,
  "seconds": "10.0",
  "size": "1280x768"
}

2. Image-to-Video (single image)

curl -X POST https://apihub.agnes-ai.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "prompt": "The woman slowly turns around and looks back at the camera, natural facial expression, cinematic camera movement",
    "image": "https://example.com/image.png",
    "num_frames": 121,
    "frame_rate": 24
  }'

3. Multi-Image Video

curl -X POST https://apihub.agnes-ai.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "prompt": "Create a smooth transformation scene between the two reference images, cinematic lighting, consistent character identity, natural motion",
    "extra_body": {
      "image": [
        "https://example.com/image1.png",
        "https://example.com/image2.png"
      ]
    },
    "num_frames": 121,
    "frame_rate": 24
  }'

4. Keyframe Interpolation

curl -X POST https://apihub.agnes-ai.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "prompt": "Generate a smooth cinematic transition between the keyframes, maintaining visual consistency and natural camera movement",
    "extra_body": {
      "image": [
        "https://example.com/keyframe1.png",
        "https://example.com/keyframe2.png"
      ],
      "mode": "keyframes"
    },
    "num_frames": 121,
    "frame_rate": 24
  }'

Retrieve Video Result

Poll until status is "completed" and progress is 100:

curl --location --request GET \
  'https://apihub.agnes-ai.com/agnesapi?video_id=video_xxxxxx' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Completed response:

{
  "id": "task_YOUR_TASK_ID",
  "video_id": "video_YOUR_VIDEO_ID",
  "model": "agnes-video-v2.0",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "seconds": "10.0",
  "size": "1280x768",
  "remixed_from_video_id": "https://storage.googleapis.com/agnes-aigc/aigc/videos/2026/06/03/video_xxxxxx.mp4",
  "error": null
}

Final video URL: remixed_from_video_id

Result Fields

Important Notes

• Asynchronous workflow: Submit → get video_id → poll for result
• num_frames must follow 8n + 1 rule and be ≤ 441
• frame_rate range: 1–60
• Default resolution: 1152×768
• Recommended polling interval: 30 seconds (to avoid hitting API rate limits or spamming)
• Timeout recommended: 60s–360s for create request
• Pricing: Currently free during beta
• Image Input: Must be a publicly accessible image URL. Base64 is not recommended for video generation and might fail.

Troubleshooting & Best Practices

1. Proxy Connection Errors (ProxyError)

When uploading large payloads or making requests through local proxies (such as Clash/VPN clients), the proxy might close the connection unexpectedly, causing ProxyError or RemoteDisconnected. Solution: Bypass the proxy for Agnes API calls. In Python requests, pass proxies={"http": None, "https": None}.

2. Request Timeout and Hanging

If the network connection drops or the server has a temporary hiccup, Python requests calls without a timeout can block indefinitely, freezing your agent. Solution: Always specify a reasonable timeout (e.g., timeout=15) in your requests.

3. Log Buffering in Background Tasks

When running Python scripts as background tasks, stdout is buffered by default. This makes the log file appear empty until the process exits. Solution: Use print(..., flush=True) or launch Python with the -u flag (python -u script.py) to force immediate log writes.

Supported Capabilities

• Text-to-Video generation
• Image-to-Video generation (requires public URL)
• Multi-image video composition
• Keyframe interpolation
• Custom resolution, frame rate, and duration
• Reproducible results via seed