Agnes Video 2.5

Agnes Video 2.5 is coming soon. This is a pre-release preview. The final model ID, parameter limits, and response fields are subject to the production release. Billing rules have been announced; see “Billing” below for the current promotional terms.

Agnes Video 2.5 uses an asynchronous video generation API. First call POST /v1/videos to create a task, then use the returned id with GET /agnesapi?video_id=<VIDEO_ID> to retrieve progress and results.

Model ID

agnes-video-2.5

Create Task

POST /v1/videos

Retrieve Task

GET /agnesapi?video_id=<VIDEO_ID>

Pricing

720P list price: $0.025 / second. The current promotion charges only for output video duration.

Core Capabilities

Text-to-video

Generate videos with subject motion, scene dynamics, and camera movement from a text prompt.

First and Last Frame Control

Constrain the composition and transition with a first frame, a last frame, or both.

Multimodal References

Use images, audio, and videos as content, style, rhythm, or motion references.

Video-to-video Reference

Continue or reinterpret motion, visual appearance, and timing from a reference video.

Audio-visual Coordination

Use audio or a video soundtrack as a reference to improve rhythm and audio-visual consistency.

Multiple Aspect Ratios

Generate landscape, portrait, square, and ultrawide video outputs.

Quickstart

1. Get an API Key

Create an API key in the Agnes AI platform. Store and use the key only on your server. Never expose it in frontend code or a public repository.

2. Set the Base URL

International Base URL:

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

The examples below use environment variables:

export AGNES_API_KEY="YOUR_API_KEY"
export AGNES_BASE_URL="https://apihub.agnes-ai.com/v1"

3. Create a Video Task

curl -sS -X POST "$AGNES_BASE_URL/videos" \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-2.5",
    "prompt": "A futuristic city street after rain, neon lights reflected on the pavement, a silver sports car passing slowly, cinematic camera movement, natural ambient sound",
    "seconds": "5",
    "mode": "text",
    "size": "720P",
    "aspect_ratio": "16:9"
  }'

The id in the create response is the video task ID used for retrieval.

4. Retrieve the Result

curl -sS "https://apihub.agnes-ai.com/agnesapi?video_id=VIDEO_ID" \
  -H "Authorization: Bearer $AGNES_API_KEY"

Poll every 1–2 seconds until status becomes completed or failed. When the task is complete, use the returned url to play or download the video.

API Reference

Create a Video Task

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

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Common Request Parameters

Parameter	Type	Required	Description
`model`	string	Yes	Model ID. Use `agnes-video-2.5`.
`prompt`	string	Yes	Video description. In reference mode, use `<Picture N>`, `<Audio N>`, and `<Video N>` to refer to input media.
`mode`	string	Yes	Generation mode: `text`, `keyframe`, or `reference`.
`seconds`	string	No	Video duration from `"4"`–`"12"` seconds. The default is `"5"`.
`size`	string	No	Output tier. Currently only `"720P"` is supported.
`aspect_ratio`	string	No	Output aspect ratio. The default is `16:9`. See supported values below.
`seed`	integer	No	Random seed. Reusing a seed can improve reproducibility.
`n`	integer	No	Number of outputs. Currently only `1` is supported and is the default.

Mode-specific Parameters

Parameter	Type	Mode	Description
`first_frame`	string	`keyframe`	First-frame image URL. Provide this, `last_frame`, or both.
`last_frame`	string	`keyframe`	Last-frame image URL. Provide this, `first_frame`, or both.
`images`	string[]	`reference`	Reference image URLs.
`audios`	string[]	`reference`	Reference audio URLs.
`videos`	object[]	`reference`	Reference video objects. See the fields below.

All media URLs must be publicly reachable by the Agnes AI service. Avoid URLs that require authentication, point to a private network, or expire before the task finishes.

Generation Mode Rules

`mode`	Purpose	Required Media	Media Fields Not Allowed
`text`	Generate a video from text only	None	`first_frame`, `last_frame`, `images`, `audios`, `videos`
`keyframe`	Control the first frame, last frame, or both	At least one of `first_frame` or `last_frame`	`images`, `audios`, `videos`
`reference`	Generate from image, audio, or video references	At least one non-empty `images`, `audios`, or `videos` array	`first_frame`, `last_frame`

keyframe attempts to preserve the input image as the actual first or last frame, making it suitable for start/end composition control. reference treats media as a content, style, motion, or rhythm reference and may recompose or retime the result.

Reference Video Objects

Each object in the videos array supports these fields:

Parameter	Type	Required	Description
`url`	string	Yes	Publicly accessible video URL.
`start_seconds`	number	No	Start reading the reference video at this offset. The default is `0`.
`require_audio`	boolean	No	Require the reference video to contain an audio track. The default is `false`.

When require_audio is false, a reference video may omit audio. If it contains an audio track, the audio can also participate as a reference. When set to true, the source must contain an audio track or the request fails.

Request Examples

Text-to-video
First and Last Frames
Image Reference
Image and Audio References
Video Reference

curl -sS -X POST "$AGNES_BASE_URL/videos" \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-2.5",
    "prompt": "At night, three cats march through a forest while playing tiny brass instruments. The camera tracks backward smoothly, moonlight passes through the leaves, with natural footsteps and instrument sounds.",
    "seconds": "5",
    "mode": "text",
    "size": "720P",
    "aspect_ratio": "16:9",
    "seed": 1101
  }'

curl -sS -X POST "$AGNES_BASE_URL/videos" \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-2.5",
    "prompt": "The person turns naturally from the first-frame pose and walks toward the window. Keep clothing and hair motion realistic, slowly push the camera forward, and transition smoothly to the last-frame composition.",
    "seconds": "5",
    "mode": "keyframe",
    "size": "720P",
    "first_frame": "https://example.com/first.png",
    "last_frame": "https://example.com/last.png"
  }'

curl -sS -X POST "$AGNES_BASE_URL/videos" \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-2.5",
    "prompt": "Use the character and art style in <Picture 1> as reference. The character runs naturally through a flower field, maintaining a consistent appearance, filmed from a low tracking angle.",
    "seconds": "5",
    "mode": "reference",
    "size": "720P",
    "aspect_ratio": "16:9",
    "images": ["https://example.com/character.png"]
  }'

curl -sS -X POST "$AGNES_BASE_URL/videos" \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-2.5",
    "prompt": "Use <Picture 1> as the visual subject and design the actions and camera cuts around the rhythm of <Audio 1>, keeping the sequence natural and coherent.",
    "seconds": "5",
    "mode": "reference",
    "size": "720P",
    "images": ["https://example.com/subject.png"],
    "audios": ["https://example.com/music.mp3"]
  }'

curl -sS -X POST "$AGNES_BASE_URL/videos" \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-2.5",
    "prompt": "Follow the subject motion and camera rhythm of <Video 1>, changing the setting to a moonlit bedroom while preserving coherent timing.",
    "seconds": "5",
    "mode": "reference",
    "size": "720P",
    "aspect_ratio": "16:9",
    "videos": [
      {
        "url": "https://example.com/input.mp4",
        "start_seconds": 35,
        "require_audio": false
      }
    ]
  }'

<Picture N>, <Audio N>, and <Video N> are numbered independently, starting from 1 in their respective arrays. For example, refer to the second item in images as <Picture 2>.

Create Response

{
  "id": "video_xxx",
  "object": "video",
  "model": "agnes-video-2.5",
  "status": "queued",
  "progress": 0,
  "created_at": 1786900000,
  "size": "720P",
  "seconds": "5",
  "quality": "standard",
  "url": null,
  "completed_at": null,
  "error": null
}

Field	Type	Description
`id`	string	Video task ID used for retrieval.
`object`	string	Object type. Always `video`.
`model`	string	Model used for the task.
`status`	string	`queued`, `in_progress`, `completed`, or `failed`.
`progress`	integer	Task progress from `0–100`.
`created_at`	integer	Task creation time as a Unix timestamp.
`completed_at`	integer \| null	Task completion time, or `null` before completion.
`size`	string	Output tier. Currently `720P`.
`seconds`	string	Video duration in seconds.
`quality`	string	Quality-tier field in the video response object.
`url`	string \| null	Video URL after the task completes.
`error`	object \| null	Error details when a task fails.

Retrieve a Task

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

curl -sS "https://apihub.agnes-ai.com/agnesapi?video_id=video_xxx" \
  -H "Authorization: Bearer $AGNES_API_KEY"

Completed response example:

{
  "id": "video_xxx",
  "object": "video",
  "model": "agnes-video-2.5",
  "status": "completed",
  "progress": 100,
  "created_at": 1786900000,
  "completed_at": 1786900120,
  "size": "720P",
  "seconds": "5",
  "quality": "standard",
  "url": "https://example.com/generated/video_xxx.mp4",
  "error": null
}

Treat status and url as the source of truth. The URL is ready for delivery only when status is completed. In production, set a maximum polling duration and use backoff for network timeouts and 429 responses.

Python SDK Example

Pass mode, aspect_ratio, and media fields through extra_body; the SDK merges them into the top level of the request JSON.

import os
import time
import requests
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AGNES_API_KEY"],
    base_url="https://apihub.agnes-ai.com/v1",
)

video = client.videos.create(
    model="agnes-video-2.5",
    prompt="Follow the motion and timing of <Video 1>, while changing the setting to a moonlit room.",
    seconds="5",
    size="720P",
    extra_body={
        "mode": "reference",
        "aspect_ratio": "16:9",
        "videos": [
            {
                "url": "https://example.com/input.mp4",
                "start_seconds": 0,
                "require_audio": False,
            }
        ],
    },
)

video_id = video.id

while True:
    time.sleep(1.5)
    response = requests.get(
        "https://apihub.agnes-ai.com/agnesapi",
        params={"video_id": video_id},
        headers={"Authorization": f"Bearer {os.environ['AGNES_API_KEY']}"},
        timeout=30,
    )
    response.raise_for_status()
    video = response.json()
    if video.get("status") in ("completed", "failed"):
        break

if video.get("status") == "failed":
    message = video.get("error", {}).get("message", "Video generation failed")
    raise RuntimeError(message)

print(video["url"])

Video Size and Aspect Ratio

size selects the output tier and currently accepts only "720P". Use aspect_ratio to select any supported 720P frame shape. WIDTHxHEIGHT and auto are not supported.

`aspect_ratio`	Output Pixels	Recommended Use
`21:9`	`1680x720`	Ultrawide and cinematic scenes.
`16:9`	`1280x720`	Landscape video and product showcases. This is the default.
`4:3`	`960x720`	General landscape and traditional video formats.
`1:1`	`720x720`	Square social feeds and product or character showcases.
`3:4`	`720x960`	Portrait presentations and character-focused content.
`9:16`	`720x1280`	Mobile short-form and vertical video.

Parameter Restrictions

The following parameters and request patterns are not supported and return 400:

Passing reference videos through video_url, video_path, or video_reference; use videos[].url instead.
Passing media through input_reference or reference_url; use first_frame, last_frame, images, audios, or videos according to the selected mode.
Sending non-configurable fields such as width, height, fps, num_frames, quality, or num_inference_steps.
Passing a resolution such as 1280x720 directly in size, or any value other than "720P"; select the resolution through aspect_ratio.
Setting aspect_ratio to auto or a value outside the supported list.
Setting n to any value other than 1.
Using media fields that conflict with mode, or using reference without any reference media.

Error Handling

HTTP Status	Common Cause	Recommended Action
`400`	Missing fields, invalid mode/media combination, duration, or aspect ratio	Check request fields and mode validation rules.
`401` / `403`	Invalid, expired, or unauthorized API key	Check the authorization header, key status, and model access.
`404`	Video task ID does not exist	Use the `id` from the create response.
`429`	Request rate exceeds the limit	Use exponential backoff and reduce polling frequency.
`500`	Internal service error	Retry later and contact support if the error persists.

Failed task example:

{
  "id": "video_xxx",
  "object": "video",
  "model": "agnes-video-2.5",
  "status": "failed",
  "progress": 100,
  "url": null,
  "error": {
    "message": "Invalid reference media"
  }
}

Prompting Recommendations

For more consistent results, structure the prompt in this order:

Subject and setting: Specify the people, objects, environment, and time.
Action and change: Describe how the subject moves and how the scene evolves.
Camera language: Specify push, pull, pan, tilt, tracking, fixed camera, or shot size.
Visual style: Add lighting, color, material, realism, and atmosphere.
Sound and rhythm: Describe ambient sound or action sounds, or reference an audio input.
Consistency requirements: State which character, product, or composition details must remain unchanged.

In reference mode, explicitly name each media placeholder and its purpose, such as “Use <Picture 1> as the character reference and follow the rhythm of <Audio 1>.” This is more controllable than uploading media without explaining how it should be used.

Pre-launch Checklist

Use the model ID agnes-video-2.5.
Use https://apihub.agnes-ai.com/v1 as the Base URL.
Save the id returned by the create response.
Poll GET /agnesapi?video_id=<VIDEO_ID> until the status is completed or failed.
Keep all media URLs publicly accessible until the task completes.
Pass seconds as a string from "4"–"12" and set n to 1.
Set size to "720P" and use a supported aspect_ratio.
Never expose your API key in logs, client-side code, or public repositories.

Billing

Agnes Video 2.5 currently supports 720P output. This section lists only the 720P list price.

Output resolution	List price
720P	`$0.025 / second`

Standard billing formula

Total cost = (output video seconds + input video seconds) × output resolution unit price
           + max(0, reference image count - 5) × $0.005

Billing item	Standard rule
Output video	Charged by actual output video duration × the output resolution unit price.
Input video	Charged by total input video duration × the output resolution unit price. Durations are added when multiple input videos are used.
Reference images	The first 5 images are free. Each image beyond the first 5 costs `$0.005`.

The currently supported output resolution is 720P, so the formula uses the 720P list price of $0.025 / second.

Current promotional billing

During the promotion, only output video duration is charged. Input video duration and reference images are temporarily free:

Current cost = output video seconds × 720P list price

Billing item	During the promotion
Output video seconds	Charged at the 720P list price of `$0.025 / second`.
Input video seconds	`$0`; temporarily free.
Reference image count	`$0`, including images beyond the first 5; temporarily free.

This promotion is temporary. Its end date and the start of standard billing are subject to Agnes AI platform announcements.

Points billing

Points use the same metering structure as currency billing, but each points unit price differs from the corresponding currency amount:

Standard points = (output video seconds + input video seconds) × output resolution points rate
                + max(0, reference image count - 5) × excess image points rate

During the promotion, points are also calculated only from output video duration. Input video duration and reference image count are temporarily excluded. Refer to the Agnes AI platform for the exact 720P points-per-second rate and excess-image points rate.

Billing example

Suppose you generate an 8-second 720P video using 3 seconds of input video and 7 reference images, calculated at the 720P list price of $0.025 / second:

Standard cost = (8 + 3) × $0.025 + max(0, 7 - 5) × $0.005
              = $0.275 + $0.01
              = $0.285

Current promotional cost = 8 × $0.025
                         = $0.20

All USD amounts in this example use the 720P list price.

Get Started

Use Guides

Model ID

Create Task

Retrieve Task

Pricing

Core Capabilities

Text-to-video

First and Last Frame Control

Multimodal References

Video-to-video Reference

Audio-visual Coordination

Multiple Aspect Ratios

Quickstart

1. Get an API Key

2. Set the Base URL

3. Create a Video Task

4. Retrieve the Result

API Reference

Create a Video Task

Common Request Parameters

Mode-specific Parameters

Generation Mode Rules

Reference Video Objects

Request Examples

Create Response

Retrieve a Task

Python SDK Example

Video Size and Aspect Ratio

Parameter Restrictions

Error Handling

Prompting Recommendations

Pre-launch Checklist

Billing

Standard billing formula

Current promotional billing

Points billing

Billing example

Model ID

Create Task

Retrieve Task

Pricing

​Core Capabilities

Text-to-video

First and Last Frame Control

Multimodal References

Video-to-video Reference

Audio-visual Coordination

Multiple Aspect Ratios

​Quickstart

​1. Get an API Key

​2. Set the Base URL

​3. Create a Video Task

​4. Retrieve the Result

​API Reference

​Create a Video Task

​Common Request Parameters

​Mode-specific Parameters

​Generation Mode Rules

​Reference Video Objects

​Request Examples

​Create Response

​Retrieve a Task

​Python SDK Example

​Video Size and Aspect Ratio

​Parameter Restrictions

​Error Handling

​Prompting Recommendations

​Pre-launch Checklist

​Billing

​720P output video list price

​Standard billing formula

​Current promotional billing

​Points billing

​Billing example

Core Capabilities

Quickstart

1. Get an API Key

2. Set the Base URL

3. Create a Video Task

4. Retrieve the Result

API Reference

Create a Video Task

Common Request Parameters

Mode-specific Parameters

Generation Mode Rules

Reference Video Objects

Request Examples

Create Response

Retrieve a Task

Python SDK Example

Video Size and Aspect Ratio

Parameter Restrictions

Error Handling

Prompting Recommendations

Pre-launch Checklist

Billing

720P output video list price

Standard billing formula

Current promotional billing

Points billing

Billing example