Agnes Video V2.0 - Agnes-Ai Docs

概述

Agnes-Video-V2.0 是一款面向生产场景的视频生成模型，支持文生视频、图生视频、多图视频生成以及关键帧动画工作流。开发者可以使用文本提示词、图片 URL 或多张参考图片生成高质量视频。该模型适用于故事讲述、营销视频、产品演示、社交媒体内容、应用动态素材以及 AI 创意工作流。

Agnes-Video-V2.0 采用基于异步任务的 API。您需要先创建一个视频生成任务，然后使用返回的 video_id 或 task_id 获取视频结果。

支持能力

文生视频

通过文本提示词直接生成视频

图生视频

将静态图片转化为动态视频

多图视频生成

使用多张参考图片引导视频生成

关键帧动画

在多个关键帧之间生成流畅过渡

场景运动控制

通过提示词控制主体动作、镜头运动和场景动态

视觉一致性

在帧间保持一致的主体、风格和场景

电影级输出

生成高质量电影级视频

异步API

先提交任务，再获取生成结果

使用场景

故事讲述

短片、角色场景、叙事片段

营销视频

产品广告、宣传视频、推广内容

社交媒体内容

Reels、Shorts、TikTok 风格视频

图片动画

为肖像、产品、角色或场景添加动画效果

产品演示

通过文本或图片生成产品展示视频

关键帧过渡

在不同视觉状态之间生成流畅过渡

游戏/应用素材

为数字产品生成动态视觉素材

沉浸式内容

生成电影级 AI 场景和氛围视频

前提条件

在接入之前，请确保您已满足以下条件：

拥有有效的 Agnes AI API Key。
具备访问 Agnes AI API 网关的网络条件。
确认模型名称：agnes-video-v2.0。
准备好用于视频生成的文本提示词。
如果使用图生视频、多图视频或关键帧动画功能，需要提供可公开访问的图片 URL。

API 接口

创建视频任务

项目	说明
接口地址	https://apihub.agnes-ai.com/v1/videos
请求方法	POST
Content-Type	application/json
认证方式	Bearer Token
请求头	Authorization: Bearer YOUR_API_KEY

获取视频结果：推荐方式

视频任务创建成功后，响应中会包含一个 video_id。推荐使用 video_id 来获取视频结果。

项目	说明
接口地址	`https://apihub.agnes-ai.com/agnesapi?video_id=<VIDEO_ID>`
请求方法	GET
认证方式	Bearer Token
请求头	Authorization: Bearer YOUR_API_KEY

获取视频结果：兼容旧版方式

为了兼容现有集成，旧版任务查询接口仍然支持使用。

项目	说明
接口地址	https://apihub.agnes-ai.com/v1/videos/{task_id}
请求方法	GET
认证方式	Bearer Token
请求头	Authorization: Bearer YOUR_API_KEY

请求参数

创建视频任务参数

参数	类型	必填	说明
model	string	是	模型名称。使用 agnes-video-v2.0
prompt	string	是	视频内容的文本描述
image	string / array	否	图片 URL 或图片 URL 数组
mode	string	否	生成模式，例如 ti2vid 或 keyframes
height	integer	否	视频高度。默认值：768
width	integer	否	视频宽度。默认值：1152
num_frames	integer	否	视频帧数。必须 ≤ 441 且遵循 8n + 1 规则
frame_rate	number	否	视频帧率。支持范围：1–60
num_inference_steps	integer	否	推理步数
seed	integer	否	随机种子，用于生成可复现的结果
negative_prompt	string	否	反向提示词，描述需要避免的内容
extra_body.image	array	否	多图视频或关键帧模式下的输入图片 URL 数组
extra_body.mode	string	否	附加模式设置，例如 keyframes

参数标准化

Agnes-Video-V2.0 会对部分视频生成参数进行标准化处理，以确保生成稳定性和输出质量的一致性。当提交的 width、height 或宽高比与模型支持的标准规格不完全匹配时，系统会自动识别最接近的分辨率档位和宽高比，并将请求映射到对应的标准输出尺寸。模型目前支持三个标准分辨率档位：480p、720p 和 1080p。推荐使用以下宽高比：

宽高比	推荐使用场景
16:9	横版视频、产品演示、网站展示、YouTube 风格内容
9:16	竖版短视频、移动端优先内容、TikTok / Reels / Shorts 风格内容
1:1	方形视频、社交媒体信息流、角色或产品展示
4:3	传统横版格式及通用演示内容
3:4	竖版演示、以肖像为主的视频、以产品为主的内容

不同分辨率与宽高比的组合可能对应不同的实际输出尺寸和最大帧数限制。例如，接近 720p / 16:9 的输入尺寸将被标准化为对应的标准输出尺寸。因此，请求中原始的 width、height、num_frames 等参数可能与生成时使用的标准化参数不完全一致。在展示任务信息、计算视频时长或排查生成结果问题时，开发者应以 API 响应中返回的 size、seconds 等字段为准。

创建视频任务

示例 1：文生视频
示例 2：图生视频
示例 3：多图视频生成
示例 4：关键帧动画

使用此请求通过文本提示词直接生成视频。

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

使用此请求在多个关键帧之间生成流畅动画。

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

创建任务响应

视频任务创建成功后，API 会返回任务信息。响应中同时包含 task_id 和 video_id。 video_id 是获取视频结果的推荐 ID。

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

响应字段

字段	类型	说明
id	string	任务 ID。可与旧版查询接口配合使用
task_id	string	任务 ID。作用与 id 相同
video_id	string	视频 ID。推荐用于获取视频结果
object	string	对象类型，通常为 video
model	string	当前任务使用的模型
status	string	当前任务状态
progress	integer	当前任务进度百分比
created_at	integer	任务创建时间戳
seconds	string	视频时长（秒）
size	string	视频分辨率

获取视频结果

推荐方式：通过 `video_id` 获取

创建视频任务后，使用返回的 video_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_xxxxxx' \
  --header 'Authorization: Bearer <API_KEY>'

可选参数：`model_name`

获取视频结果时，您还可以传入 model_name 来显式指定模型名称。

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

示例：

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

在以下情况下使用 model_name：

您使用的是上游原始视频 ID。
使用的模型不是默认模型 agnes-video-v2.0。
您希望显式指定获取结果所使用的模型。

当提供 model_name 时，该参数将优先生效。

兼容旧版方式：通过 `task_id` 获取

为兼容旧版本，您仍然可以使用 task_id 获取视频结果。

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

示例：

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

此方式仍然支持，但新接入的集成应使用 video_id 获取方式。

获取结果响应

任务完成后，API 返回最终视频结果。

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

结果字段

字段	类型	说明
id	string	任务 ID
video_id	string	视频 ID
model	string	当前任务使用的模型
object	string	对象类型
status	string	任务状态
progress	integer	任务进度百分比
seconds	string	视频时长（秒）
size	string	视频分辨率
remixed_from_video_id	string	最终生成的视频 URL。仅在 status 为 completed 时可用
error	object / null	任务失败时返回的错误信息

任务状态

状态	说明
queued	任务正在队列中等待
in_progress	视频正在生成
completed	视频生成成功
failed	视频生成失败

视频时长控制

Agnes-Video-V2.0 支持通过 num_frames 和 frame_rate 控制视频时长。计算公式：

seconds = num_frames / frame_rate

其中：

num_frames 是生成视频的总帧数；
frame_rate 是视频帧率，即每秒播放的帧数；
num_frames 必须小于或等于 441；
num_frames 必须遵循 8n + 1 规则；
frame_rate 支持 1 到 60 之间的值。

常用时长设置

目标时长	推荐参数
约 3 秒	num_frames: 81, frame_rate: 24
约 5 秒	num_frames: 121, frame_rate: 24
约 10 秒	num_frames: 241, frame_rate: 24
约 18 秒	num_frames: 441, frame_rate: 24

要生成更长的视频，可以增大 num_frames 或降低 frame_rate。要使运动更加流畅，请使用更高的 frame_rate，例如 24 或 30。但在相同的 num_frames 下，更高的 frame_rate 会导致视频时长更短。

场景	推荐设置
标准视频生成	width: 1152, height: 768, num_frames: 121, frame_rate: 24
社交短视频	num_frames: 81 或 121, frame_rate: 24
较长视频	增大 num_frames 或降低 frame_rate
更流畅的运动	使用 frame_rate: 24 或 30
可复现结果	设置固定的 seed
关键帧过渡	使用 extra_body.mode: “keyframes”
避免不需要的内容	使用 negative_prompt

提示词最佳实践

文生视频提示词

对于文生视频任务，建议描述主体、动作、场景、镜头运动、光线和视觉风格。推荐结构：

[主体] + [动作] + [场景] + [镜头运动] + [光线] + [风格]

示例：

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

图生视频提示词

对于图生视频任务，描述哪些内容应该运动，以及哪些关键主体元素应该保持稳定。示例：

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

多图视频提示词

对于多图视频任务，描述输入图片之间的关系以及场景应该如何过渡。示例：

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

关键帧动画提示词

对于关键帧动画任务，清晰描述关键帧之间的过渡关系。示例：

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

错误码

状态码	说明
400	请求无效。请检查请求参数
401	未授权。请检查您的 API Key
404	任务或视频未找到
500	服务器错误
503	服务繁忙。请稍后重试

定价

类型	标准价格	当前价格
视频时长	$0.005 / 秒	$0 / 秒

注意事项

使用 agnes-video-v2.0 作为模型名称。
视频生成是异步的。
您需要先创建视频任务，然后获取视频结果。
创建任务响应会同时返回 task_id 和 video_id。
新接入的集成应使用 video_id 获取视频结果。
旧版 task_id 查询接口仍然支持。
video_url 仅在 status 为 completed 时可用。
num_frames 必须小于或等于 441。
num_frames 必须遵循 8n + 1 规则，例如 81、121、161、241 或 441。
文生视频任务仅需要 model 和 prompt。
图生视频任务需要通过 image 传入图片 URL。
多图视频任务需要在 extra_body.image 中传入多个图片 URL。
关键帧动画需要将 extra_body.mode 设置为 keyframes。

​概述

​支持能力

文生视频

图生视频

多图视频生成

关键帧动画

场景运动控制

视觉一致性

电影级输出

异步API

​使用场景

故事讲述

营销视频

社交媒体内容

图片动画

产品演示

关键帧过渡

游戏/应用素材

沉浸式内容

​前提条件

​API 接口

​创建视频任务

​获取视频结果：推荐方式

​获取视频结果：兼容旧版方式

​请求参数

​创建视频任务参数

​参数标准化

​创建视频任务

​创建任务响应

​响应字段

​获取视频结果

​推荐方式：通过 video_id 获取

​可选参数：model_name

​兼容旧版方式：通过 task_id 获取

​获取结果响应

​结果字段

​任务状态

​视频时长控制

​常用时长设置

​推荐参数

​提示词最佳实践

​错误码

​定价

​注意事项

概述

支持能力

使用场景

前提条件

API 接口

创建视频任务

获取视频结果：推荐方式

获取视频结果：兼容旧版方式

请求参数

创建视频任务参数

参数标准化

创建视频任务

创建任务响应

响应字段

获取视频结果

推荐方式：通过 `video_id` 获取

可选参数：`model_name`

兼容旧版方式：通过 `task_id` 获取

获取结果响应

结果字段

任务状态

视频时长控制

常用时长设置

推荐参数

提示词最佳实践

错误码

定价

注意事项