Agnes-Video-V2.0 API Integration Guide

Overview

Agnes-Video-V2.0 is a production-oriented video generation model that supports text-to-video, image-to-video, multi-image video generation, and keyframe animation workflows. Developers can generate high-quality videos using text prompts, image URLs, or multiple reference images. The model is suitable for storytelling, marketing videos, product demos, social media content, app motion assets, and AI creative workflows. Agnes-Video-V2.0 uses an asynchronous task-based API. You need to create a video generation task first, then retrieve the video result using the returned video_id or task_id.

Supported Capabilities

Capability	Description
Text-to-Video	Generate videos directly from text prompts
Image-to-Video	Animate a static image into a dynamic video
Multi-Image Video Generation	Use multiple reference images to guide video generation
Keyframe Animation	Generate smooth transitions between multiple keyframes
Scene Motion Control	Control subject actions, camera movement, and scene dynamics through prompts
Visual Consistency	Maintain consistent subjects, style, and scenes across frames
Cinematic Output	Generate high-quality cinematic videos
Asynchronous API	Submit a task first, then retrieve the generated result

Use Cases

Use Case	Example
Storytelling	Short films, character scenes, narrative clips
Marketing Videos	Product ads, campaign videos, promotional content
Social Media Content	Reels, Shorts, TikTok-style videos
Image Animation	Animate portraits, products, characters, or scenes
Product Demos	Generate product showcase videos from text or images
Keyframe Transitions	Generate smooth transitions between different visual states
Game / App Assets	Generate dynamic visual assets for digital products
Immersive Content	Generate cinematic AI scenes and atmospheric videos

Prerequisites

Before integration, make sure you have:

A valid Agnes AI API Key.
Network access to the Agnes AI API Gateway.
The confirmed model name: agnes-video-v2.0.
A text prompt prepared for video generation.
Publicly accessible image URLs if you use image-to-video, multi-image video, or keyframe animation.

API Endpoints

Create Video Task

Item	Description
Endpoint	https://apihub.agnes-ai.com/v1/videos
Method	POST
Content-Type	application/json
Authentication	Bearer Token
Header	Authorization: Bearer YOUR_API_KEY

Retrieve Video Result: Recommended Method

After a video task is created, the response will include a video_id. It is recommended to use video_id to retrieve the video result.

Item	Description
Endpoint	`https://apihub.agnes-ai.com/agnesapi?video_id=<VIDEO_ID>`
Method	GET
Authentication	Bearer Token
Header	Authorization: Bearer YOUR_API_KEY

Retrieve Video Result: Legacy-Compatible Method

The legacy task query endpoint is still supported for compatibility with existing integrations.

Item	Description
Endpoint	https://apihub.agnes-ai.com/v1/videos/{task_id}
Method	GET
Authentication	Bearer Token
Header	Authorization: Bearer YOUR_API_KEY

Request Parameters

Create Video 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 / array	No	Image URL or image URL array
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 video frames. Must be ≤ 441 and follow the 8n + 1 rule
frame_rate	number	No	Video FPS. 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 URLs for multi-image video or keyframe mode
extra_body.mode	string	No	Additional mode setting, such as keyframes

Parameter Standardization

Agnes-Video-V2.0 standardizes certain video generation parameters to ensure generation stability and consistent output quality. When the submitted width, height, or aspect ratio does not exactly match the model’s supported standard specifications, the system automatically identifies the closest resolution tier and aspect ratio, then maps the request to the corresponding standard output size. The model currently supports three standard resolution tiers: 480p, 720p, and 1080p. The following aspect ratios are recommended:

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

Different resolution and aspect ratio combinations may correspond to different actual output sizes and maximum frame limits. For example, an input size close to 720p / 16:9 will be standardized to the corresponding standard output size. As a result, the original width, height, num_frames, and other parameters in the request may not always be identical to the standardized parameters used during generation. When displaying task information, calculating video duration, or troubleshooting generation results, developers should refer to the size, seconds, and other fields returned by the API response.

Create Video Task

Example 1: Text-to-Video

Use this request to generate a video directly from a text prompt.

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

Example 2: Image-to-Video

Use this request to animate a 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
  }'

Example 3: Multi-Image Video Generation

Use this request to generate a video guided by multiple input images.

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

Example 4: Keyframe Animation

Use this request to generate smooth animation between multiple keyframes.

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

After 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 the video result.

{
  "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 by the current 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

Retrieve Video Result

Recommended Method: Retrieve by `video_id`

After creating a video task, use the returned video_id to retrieve the video result.

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

Example:

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

Optional Parameter: `model_name`

When retrieving a video result, you can also pass model_name to explicitly specify the model name.

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

Example:

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

Use model_name in the following cases:

You are using an upstream raw video ID.
The model is not the default model agnes-video-v2.0.
You want to explicitly specify the model used for result retrieval.

When model_name is provided, this parameter takes priority.

Legacy-Compatible Method: Retrieve by `task_id`

For compatibility with older versions, you can still retrieve video results using task_id.

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

Example:

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

This method is still supported, but new integrations should use the video_id retrieval method.

Retrieve Result Response

When the task is completed, the API returns the final video result.

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

Result Fields

Field	Type	Description
id	string	Task ID
video_id	string	Video ID
model	string	Model used by the current task
object	string	Object type
status	string	Task status
progress	integer	Task progress percentage
seconds	string	Video duration in seconds
size	string	Video resolution
remixed_from_video_id	string	Final generated video URL. Available only when status is completed
error	object / null	Error information returned when the task fails

Task Status

Status	Description
queued	The task is waiting in the queue
in_progress	The video is being generated
completed	The video has been generated successfully
failed	Video generation failed

Video Duration Control

Agnes-Video-V2.0 supports controlling video duration through num_frames and frame_rate. Formula:

text

seconds = num_frames / frame_rate

Where:

num_frames is the total number of generated video frames;
frame_rate is the video frame rate, meaning how many frames are played 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 a longer video, increase num_frames or lower frame_rate. To make the motion smoother, use a higher frame_rate, such as 24 or 30. However, with the same num_frames, a higher frame_rate will result in a shorter video duration.

Recommended Parameters

Scenario	Recommended Settings
Standard video generation	width: 1152, height: 768, num_frames: 121, frame_rate: 24
Short social video	num_frames: 81 or 121, frame_rate: 24
Longer video	Increase num_frames or lower frame_rate
Smoother motion	Use frame_rate: 24 or 30
Reproducible result	Set a fixed seed
Keyframe transition	Use extra_body.mode: “keyframes”
Avoid unwanted content	Use negative_prompt

Prompt Best Practices

Text-to-Video Prompt

For text-to-video tasks, it is recommended to describe the subject, action, scene, camera movement, lighting, and visual style. Recommended structure:

text

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

Example:

text

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 Prompt

For image-to-video tasks, describe what should move and which key subject elements should remain stable. Example:

text

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

Multi-Image Video Prompt

For multi-image video tasks, describe the relationship between the input images and how the scene should transition. Example:

text

Use the first image as the starting scene and the second image as the target scene. Create a smooth transformation with consistent lighting, natural motion, and cinematic pacing

Keyframe Animation Prompt

For keyframe animation tasks, clearly describe the transition relationship between keyframes. Example:

text

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 busy. Please try again later

Pricing

Type	Standard Price	Current Price
Video Duration	$0.005 / second	$0 / second

Notes

Use agnes-video-v2.0 as the model name.
Video generation is asynchronous.
You need to create a video task first, then retrieve the video result.
The create task response returns both task_id and video_id.
New integrations should use video_id to retrieve video results.
The legacy task_id query endpoint is still supported.
video_url is only available when status is completed.
num_frames must be less than or equal to 441.
num_frames must follow the 8n + 1 rule, such as 81, 121, 161, 241, or 441.
Text-to-video tasks only require model and prompt.
Image-to-video tasks require an image URL through image.
Multi-image video tasks require multiple image URLs in extra_body.image.
Keyframe animation requires extra_body.mode to be set to keyframes.

​Agnes-Video-V2.0 API Integration Guide

​Overview

​Supported Capabilities

​Use Cases

​Prerequisites

​API Endpoints

​Create Video Task

​Retrieve Video Result: Recommended Method

​Retrieve Video Result: Legacy-Compatible Method

​Request Parameters

​Create Video Task Parameters

​Parameter Standardization

​Create Video Task

​Example 1: Text-to-Video

​Example 2: Image-to-Video

​Example 3: Multi-Image Video Generation

​Example 4: Keyframe Animation

​Create Task Response

​Response Fields

​Retrieve Video Result

​Recommended Method: Retrieve by video_id

​Optional Parameter: model_name

​Legacy-Compatible Method: Retrieve by task_id

​Retrieve Result Response

​Result Fields

​Task Status

​Video Duration Control

​Common Duration Settings

​Recommended Parameters

​Prompt Best Practices

​Text-to-Video Prompt

​Image-to-Video Prompt

​Multi-Image Video Prompt

​Keyframe Animation Prompt

​Error Codes

​Pricing

​Notes

Agnes-Video-V2.0 API Integration Guide

Overview

Supported Capabilities

Use Cases

Prerequisites

API Endpoints

Create Video Task

Retrieve Video Result: Recommended Method

Retrieve Video Result: Legacy-Compatible Method

Request Parameters

Create Video Task Parameters

Parameter Standardization

Create Video Task

Example 1: Text-to-Video

Example 2: Image-to-Video

Example 3: Multi-Image Video Generation

Example 4: Keyframe Animation

Create Task Response

Response Fields

Retrieve Video Result

Recommended Method: Retrieve by `video_id`

Optional Parameter: `model_name`

Legacy-Compatible Method: Retrieve by `task_id`

Retrieve Result Response

Result Fields

Task Status

Video Duration Control

Common Duration Settings

Recommended Parameters

Prompt Best Practices

Text-to-Video Prompt

Image-to-Video Prompt

Multi-Image Video Prompt

Keyframe Animation Prompt

Error Codes

Pricing

Notes