Agnes Video V2.0 - Agnes-Ai Docs

Agnes Video V2.0 is a production-oriented video generation model that supports text-to-video, image-to-video, and keyframe animation. Video generation uses an asynchronous task API: create a task first, then retrieve the result through video_id or task_id.

Model

agnes-video-v2.0

Create Task

POST /v1/videos

Get Result

GET /agnesapi?video_id=<VIDEO_ID>

Current Price

Video duration is currently $0 / second.

Overview

Developers can generate high-quality videos from text prompts or image URLs. The model is suitable for storytelling, marketing videos, product demos, social media content, app motion assets, and AI creative workflows.

Core Capabilities

Text-to-video

Generate videos directly from text prompts.

Image-to-video

Turn static images into dynamic videos.

Keyframe Animation

Generate smooth transitions between multiple keyframes.

Motion Control

Control subject actions, camera movement, and scene dynamics through prompts.

Visual Consistency

Maintain subject, style, and scene consistency across frames.

Cinematic Output

Generate high-quality cinematic video content.

Asynchronous API

Create a task first, then poll or query the generated result.

Use Cases

Storytelling

Short films, character scenes, and narrative clips.

Marketing Videos

Product ads, promotional videos, and campaign content.

Social Media Content

Reels, Shorts, and TikTok-style videos.

Image Animation

Add motion to portraits, products, characters, or scenes.

Product Demos

Generate product showcase videos from text or images.

Keyframe Transitions

Generate smooth transitions between different visual states.

Prerequisites

Before integration, make sure you have a valid Agnes AI API key, network access to the Agnes AI API gateway, and a text prompt for video generation. Image-to-video and keyframe animation workflows also require publicly accessible image URLs.

API Reference

Create Video Task

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

Get Video Result: Recommended Method

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

Get Video Result: Legacy-compatible Method

GET https://apihub.agnes-ai.com/v1/videos/<TASK_ID>

Headers

-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"

Create Task Parameters

Parameter	Type	Required	Description
`model`	string	Yes	Model name. Use `agnes-video-v2.0`.
`prompt`	string	Yes	Text description of the video content.
`image`	string	No	Image URL for image-to-video workflows.
`mode`	string	No	Generation mode, such as `ti2vid` or `keyframes`.
`height`	integer	No	Video height. Default value: `768`.
`width`	integer	No	Video width. Default value: `1152`.
`num_frames`	integer	No	Number of frames. Must be `<= 441` and follow the `8n + 1` rule.
`frame_rate`	number	No	Frame rate. Supported range: `1-60`.
`num_inference_steps`	integer	No	Number of inference steps.
`seed`	integer	No	Random seed for reproducible results.
`negative_prompt`	string	No	Negative prompt describing content to avoid.
`extra_body.image`	array	No	Input image URL array for keyframe workflows.
`extra_body.mode`	string	No	Additional mode setting, such as `keyframes`.

Parameter Normalization

Agnes Video V2.0 normalizes some video generation parameters to ensure stable output quality. When the submitted width, height, or aspect ratio does not exactly match supported model specifications, the system maps the request to the closest standard output configuration.

The model currently supports three standard resolution tiers: 480p, 720p, and 1080p.

Aspect Ratio	Recommended Use Case
`16:9`	Landscape videos, product demos, website showcases, YouTube-style content.
`9:16`	Vertical short videos, mobile-first content, TikTok / Reels / Shorts.
`1:1`	Square videos, social media feeds, character or product showcases.
`4:3`	Traditional landscape format and general presentation content.
`3:4`	Vertical presentation videos, portrait-focused content, product-focused content.

The original width, height, and num_frames values in the request may not exactly match the normalized generation settings. When displaying task information, calculating video duration, or debugging generation results, use the size, seconds, and metadata.size_mapping fields returned by the API response as the source of truth.

Create Task Examples

Text-to-video
Image-to-video
Keyframe Animation

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
  }'

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
  }'

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
  }'

Create Task Response

When the video task is created successfully, the API returns task information. The response includes both task_id and video_id. video_id is the recommended ID for retrieving video results.

{
  "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"
}

Response Fields

Field	Type	Description
`id`	string	Task ID. Can be used with the legacy query endpoint.
`task_id`	string	Task ID. Same purpose as `id`.
`video_id`	string	Video ID. Recommended for retrieving the video result.
`object`	string	Object type, usually `video`.
`model`	string	Model used for the task.
`status`	string	Current task status.
`progress`	integer	Current task progress percentage.
`created_at`	integer	Task creation timestamp.
`seconds`	string	Video duration in seconds.
`size`	string	Video resolution.

Get Video Result

By video_id
By video_id + model_name
Legacy: By task_id

curl --location --request GET 'https://apihub.agnes-ai.com/agnesapi?video_id=<VIDEO_ID>' \
  --header 'Authorization: Bearer <API_KEY>'

curl --location --request GET 'https://apihub.agnes-ai.com/agnesapi?video_id=<VIDEO_ID>&model_name=agnes-video-v2.0' \
  --header 'Authorization: Bearer <API_KEY>'

Use model_name when you are using an upstream original video ID, the model is not the default agnes-video-v2.0, or you want to explicitly specify the model used to retrieve the result.

curl --location --request GET 'https://apihub.agnes-ai.com/v1/videos/<TASK_ID>' \
  --header 'Authorization: Bearer <API_KEY>'

Final Result Response

When the task is completed, the API returns the final video result. The generated video URL is available in metadata.url.

{
  "id": "task_YOUR_TASK_ID",
  "video_id": "task_YOUR_TASK_ID",
  "task_id": "task_YOUR_TASK_ID",
  "object": "video",
  "model": "agnes-video-v2.0",
  "status": "completed",
  "progress": 100,
  "created_at": 1784530473,
  "completed_at": 1784530510,
  "seconds": "1.0",
  "size": "832x448",
  "metadata": {
    "size_mapping": {
      "adjusted": true,
      "height": 448,
      "message": "Input size 1024x576 was mapped to nearest preset 480p/16:9 (832x448)",
      "ratio": "16:9",
      "requested_height": 576,
      "requested_width": 1024,
      "resolution": "480p",
      "width": 832
    },
    "url": "https://platform-outputs.agnes-ai.space/videos/agnes-video-v2.0/task_YOUR_TASK_ID.mp4"
  }
}

Result Fields

Field	Type	Description
`id`	string	Task ID.
`video_id`	string	Video ID returned by the API. Treat it as an opaque identifier; it may use the same value as `task_id`.
`task_id`	string	Task ID. Same purpose as `id`.
`model`	string	Model used for the task.
`object`	string	Object type.
`status`	string	Task status.
`progress`	integer	Task progress percentage.
`created_at`	integer	Task creation timestamp.
`completed_at`	integer	Task completion timestamp.
`seconds`	string	Video duration in seconds.
`size`	string	Actual output video resolution after normalization.
`metadata`	object	Additional result metadata.
`metadata.url`	string	Final generated video URL. Available when `status` is `completed`.
`metadata.size_mapping`	object	Size normalization details, including the requested dimensions, actual output dimensions, aspect ratio, and resolution tier.
`error`	object / null	Error information if the task fails. This field may be omitted on successful responses.

Task Status

Status	Description
`queued`	The task is waiting in the queue.
`in_progress`	The video is being generated.
`completed`	The video was generated successfully.
`failed`	The video generation task failed.

Video Duration Control

Agnes Video V2.0 supports controlling video duration with num_frames and frame_rate.

seconds = num_frames / frame_rate

num_frames is the total number of generated frames.
frame_rate is the playback frame rate in frames per second.
num_frames must be less than or equal to 441.
num_frames must follow the 8n + 1 rule.
frame_rate supports values from 1 to 60.

Common Duration Settings

Target Duration	Recommended Parameters
About 3 seconds	`num_frames: 81`, `frame_rate: 24`
About 5 seconds	`num_frames: 121`, `frame_rate: 24`
About 10 seconds	`num_frames: 241`, `frame_rate: 24`
About 18 seconds	`num_frames: 441`, `frame_rate: 24`

To generate longer videos, increase num_frames or reduce frame_rate. To make motion smoother, use a higher frame_rate, such as 24 or 30. At the same num_frames, a higher frame_rate results in a shorter video.

Recommended Parameters

Scenario	Recommended Settings
Standard video generation	`width: 1152`, `height: 768`, `num_frames: 121`, `frame_rate: 24`
Social short videos	`num_frames: 81` or `121`, `frame_rate: 24`
Longer videos	Increase `num_frames` or reduce `frame_rate`.
Smoother motion	Use `frame_rate: 24` or `30`.
Reproducible results	Set a fixed `seed`.
Keyframe transition	Use `extra_body.mode: "keyframes"`.
Avoid unwanted content	Use `negative_prompt`.

Prompt Best Practices

Text-to-video Prompts

Describe the subject, action, scene, camera movement, lighting, and visual style.

[Subject] + [Action] + [Scene] + [Camera Movement] + [Lighting] + [Style]

A young astronaut walking across a red desert planet, dust blowing in the wind, slow cinematic tracking shot, dramatic sunset lighting, realistic sci-fi style

Image-to-video Prompts

Describe what should move and which key subject elements should remain stable.

Animate the character with subtle breathing motion, hair moving gently in the wind, background lights flickering softly, while keeping the face and outfit consistent

Keyframe Animation Prompts

Clearly describe the transition relationship between keyframes.

Create a smooth transition from the first keyframe to the second keyframe, maintaining character identity, consistent camera angle, and natural motion between scenes

Error Codes

Status Code	Description
`400`	Invalid request. Check the request parameters.
`401`	Unauthorized. Check your API key.
`404`	Task or video not found.
`500`	Server error.
`503`	Service is busy. Try again later.

Pricing

Type	Standard Price	Current Price
Video duration	`$0.005 / second`	`$0 / second`

Integration Checklist

Use agnes-video-v2.0 as the model name.

Video generation is asynchronous. Create a task first, then retrieve the result.

New integrations should use video_id to retrieve video results.

Use publicly accessible image URLs for image-to-video and keyframe workflows.

Use the response fields seconds and size as the source of truth after parameter normalization.

Model

Create Task

Get Result

Current Price

​Overview

​Core Capabilities

Text-to-video

Image-to-video

Keyframe Animation

Motion Control

Visual Consistency

Cinematic Output

Asynchronous API

​Use Cases

Storytelling

Marketing Videos

Social Media Content

Image Animation

Product Demos

Keyframe Transitions

​Prerequisites

​API Reference

​Create Video Task

​Get Video Result: Recommended Method

​Get Video Result: Legacy-compatible Method

​Headers

​Create Task Parameters

​Parameter Normalization

​Create Task Examples

​Create Task Response

​Response Fields

​Get Video Result

​Final Result Response

​Result Fields

​Task Status

​Video Duration Control

​Common Duration Settings

​Recommended Parameters

​Prompt Best Practices

​Error Codes

​Pricing

​Integration Checklist

Overview

Core Capabilities

Use Cases

Prerequisites

API Reference

Create Video Task

Get Video Result: Recommended Method

Get Video Result: Legacy-compatible Method

Headers

Create Task Parameters

Parameter Normalization

Create Task Examples

Create Task Response

Response Fields

Get Video Result

Final Result Response

Result Fields

Task Status

Video Duration Control

Common Duration Settings

Recommended Parameters

Prompt Best Practices

Error Codes

Pricing

Integration Checklist