Agnes Video — Agnes Video v2.0 视频模型

Overview

Agnes Video v2.0 is Sapiens AI's cinematic video generation model. It uses
an asynchronous task workflow: create a generation task, then poll until
complete. Supports four workflows:

1. Text-to-Video — generate video from text description
2. Image-to-Video — animate a static image
3. Multi-Image-to-Video — transition between multiple images
4. Keyframe Animation — frame-by-frame control

• Model ID: agnes-video-v2.0
• Base URL: https://apihub.agnes-ai.com/v1
• Pricing: Free tier ($0/second)
• Auth: Authorization: Bearer YOUR_API_KEY
• Create endpoint: POST /v1/videos
• Query endpoint: GET /v1/videos/{task_id}
• Workflow: Async — submit task → poll → get video URL

Quick Start

Python

import os
import time
import httpx

API_KEY = os.environ["AGNES_API_KEY"]
BASE = "https://apihub.agnes-ai.com"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Step 1: Create video task
resp = httpx.post(
    f"{BASE}/v1/videos",
    headers=HEADERS,
    json={
        "model": "agnes-video-v2.0",
        "prompt": "A cinematic shot of waves crashing on rocky shores at sunset",
        "height": 768,
        "width": 1152,
        "num_frames": 121,
        "frame_rate": 24,
    },
)
task = resp.json()
task_id = task["task_id"]

# Step 2: Poll until complete
while True:
    r = httpx.get(f"{BASE}/v1/videos/{task_id}", headers=HEADERS)
    data = r.json()
    if data["status"] == "completed":
        print("Video URL:", data["remixed_from_video_id"])
        break
    elif data["status"] == "failed":
        print("Failed:", data.get("error"))
        break
    time.sleep(5)

cURL (Create Task)

curl 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 cat walking on the beach at sunset, cinematic",
    "height": 768,
    "width": 1152,
    "num_frames": 121,
    "frame_rate": 24
  }'

cURL (Query Status)

curl https://apihub.agnes-ai.com/v1/videos/TASK_ID \
  -H "Authorization: Bearer $AGNES_API_KEY"

Endpoints

Request Parameters

Critical: num_frames Constraint

num_frames MUST satisfy both conditions:

1. num_frames ≤ 441
2. num_frames = 8n + 1  (n is a positive integer)

Valid Values

81, 121, 161, 201, 241, 281, 321, 361, 401, 441

Video Duration Formula

Duration (seconds) = num_frames / frame_rate

> Tip: Lower frame_rate (e.g. 12) for longer videos; raise it (e.g. 30) for smoother motion.

Task States

Create Response (Task Created)

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

Query Response (Completed)

{
  "id": "task_xxx",
  "model": "agnes-video-v2.0",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "seconds": "10.0",
  "size": "1280x768",
  "error": null,
  "remixed_from_video_id": "https://storage.../video_xxxxxx.mp4"
}

The video file URL is in remixed_from_video_id.

Four Workflows

1. Text-to-Video

Generate video purely from text description:

{
    "model": "agnes-video-v2.0",
    "prompt": "A majestic eagle soaring over snow-capped mountains, cinematic drone shot",
    "num_frames": 121,
    "frame_rate": 24,
}

2. Image-to-Video

Animate a static image — provide image URL:

{
    "model": "agnes-video-v2.0",
    "prompt": "The waves crash and foam, seagulls fly across the sky, clouds drift slowly",
    "image": "https://example.com/beach-photo.png",
    "num_frames": 121,
}

3. Multi-Image-to-Video

Transition between multiple images via extra_body.image:

{
    "model": "agnes-video-v2.0",
    "prompt": "Smooth morphing transition from day to night scene",
    "extra_body": {
        "image": [
            "https://example.com/day.png",
            "https://example.com/night.png"
        ]
    },
    "num_frames": 161,
}

4. Keyframe Animation

Precise keyframe control with extra_body.mode: "keyframes":

{
    "model": "agnes-video-v2.0",
    "prompt": "Smooth interpolation between keyframes with natural motion",
    "extra_body": {
        "image": ["keyframe1.png", "keyframe2.png", "keyframe3.png"],
        "mode": "keyframes"
    },
    "num_frames": 241,
}

Prompt Writing Guide

[主体 Subject] + [动作 Motion] + [场景 Setting] + [镜头 movement] + [光照 Lighting] + [风格 Style]

Example:

A golden retriever puppy running through a field of sunflowers,
camera slowly tracking alongside, warm golden hour sunlight,
cinematic film look with shallow depth of field

For image-to-video, describe what SHOULD move/change while keeping the
static elements stable.

Bundled Scripts

scripts/generate.py

Generate video from the command line:

# Text-to-video
python scripts/generate.py --prompt "A waterfall in a lush forest" --frames 121

# Image-to-video
python scripts/generate.py --prompt "Water flows, trees sway" --input-image beach.png

# Custom duration (~10 sec)
python scripts/generate.py --prompt "City timelapse" --frames 241 --fps 24

# Download result
python scripts/generate.py --prompt "Ocean waves" --output waves.mp4

Reads AGNES_API_KEY from environment. Polls automatically until complete.

Reference

See references/api_reference.md for error codes, parameter details,
and advanced configuration.