Skip to content

agnes-video-2.5 首尾帧 API 使用文档 ​

基于 Agnes Video 2.5 的首尾帧接口,通过 DMXAPI 网关以异步任务调用。mode 固定为 keyframe,用首帧、尾帧或两者共同约束成片的起止构图。first_frame 与 last_frame 至少填一个,图片支持公网 URL 或 Base64(Base64 需要带前缀,如 data:image/png;base64,iVBOR...)。该模式会尽量把输入图保持为成片的真实首帧或尾帧,适合控制过渡;时长为 "4"~"12"(默认 "5");分辨率支持 720P、1080P、1K、2K;画幅支持 21:9、16:9、4:3、1:1、3:4、9:16(默认 16:9)。

接口地址 ​

接口请求方式URL
提交任务POSThttps://www.dmxapi.cn/v1/videos
获取结果GEThttps://www.dmxapi.cn/v1/videos/{task_id}

WARNING

请妥善保管您的 API Key!严禁将密钥泄露给他人、硬编码到代码中或提交到公开的代码仓库。如果怀疑密钥已泄露,请立即前往 DMXAPI 官网重新生成。

模型名称 ​

  • agnes-video-2.5

输出视频尺寸 ​

以下为各画幅比例的输出像素映射,实际宽高以 API 响应为准。1K 固定输出 1024x1024,未列入下表。

aspect_ratio720P1080P2K(720P 的 2 倍)推荐场景
21:91470x6302206x9462940x1260超宽银幕、电影感场景。
16:91280x7201920x10802560x1440横版视频、产品展示,默认比例。
4:31112x8341664x12482224x1668通用横版和传统画幅内容。
1:1960x9601440x14401920x1920社交媒体信息流和方形内容。
3:4834x11121248x16641668x2224竖版展示和人物内容。
9:16720x12801080x19201440x2560移动端短视频和竖屏内容。

首尾帧示例代码 ​

python
import json

import requests

# ===============================================================
# 步骤1:配置 API 连接信息
# ===============================================================

url = "https://www.dmxapi.cn/v1/videos"

# DMXAPI API Key(请替换为您自己的密钥;这里只放占位值)
api_key = "sk-请替换为您自己的密钥"


# ===============================================================
# 步骤2:配置请求头
# ===============================================================

headers = {
    "Content-Type": "application/json",  # JSON 请求体
    "Authorization": f"Bearer {api_key}",  # DMXAPI 网关鉴权
    "Accept": "application/json",  # 返回 JSON
}

# ===============================================================
# 步骤3:配置请求参数
# ===============================================================

payload = {
    # 【model】(string, 必填) 固定为 agnes-video-2.5
    "model": "agnes-video-2.5",

    # 【prompt】(string, 必填) 视频提示词
    # 长度没有具体限制,但超长 prompt 会拖慢生成,并影响视频生成效果
    "prompt": "首帧是黑猫仰头的近景,金色眼睛看向上方。镜头慢慢拉远,黑猫低下头看向镜头,平滑过渡到尾帧:黑猫坐在浅色地面上,全身入画,黄绿色眼睛正对镜头。",

    # 【mode】(string, 必填) 首尾帧固定为 keyframe
    "mode": "keyframe",

    # 【seconds】(string, 可选) 输出视频时长,"4" 到 "12",不填默认 "5"
    "seconds": "5",

    # 【size】(string, 可选) 输出尺寸:720P、1080P、1K 或 2K
    "size": "720P",

    # 【aspect_ratio】(string, 可选) 画幅比例:21:9、16:9、4:3、1:1、3:4 或 9:16
    "aspect_ratio": "16:9",

    # 【first_frame】(string, 可选) 首帧图片,公网 URL 或 Base64 均可;与 last_frame 至少填一个。
    # Base64 需要带前缀,如 data:image/png;base64,iVBOR...
    "first_frame": "https://wanx.alicdn.com/material/20250318/first_frame.png",

    # 【last_frame】(string, 可选) 尾帧图片,公网 URL 或 Base64 均可;与 first_frame 至少填一个。
    # Base64 需要带前缀,如 data:image/png;base64,iVBOR...
    "last_frame": "https://wanx.alicdn.com/material/20250318/last_frame.png",

    # 【seed】(integer, 可选) 随机种子;需要时取消注释
    # "seed": 12345,
}


def read_result(response):
    """优先解析 JSON,解析失败时保留原始文本。"""
    try:
        return response.json()
    except ValueError:
        return response.text


def print_result(result):
    """格式化输出 JSON 或纯文本结果。"""
    if isinstance(result, (dict, list)):
        print(json.dumps(result, indent=2, ensure_ascii=False))
    else:
        print(result)


def check_config():
    """提交前检查用户配置,避免把明显错误的参数发给网关。"""
    if not api_key.strip() or api_key.startswith("{{") or "请替换" in api_key:
        raise RuntimeError("请先在步骤1配置区填写真实的 api_key。")
    if payload.get("model") != "agnes-video-2.5":
        raise ValueError("payload['model'] 必须是 agnes-video-2.5。")
    prompt = payload.get("prompt")
    if not isinstance(prompt, str) or not prompt.strip():
        raise ValueError("payload['prompt'] 不能为空。")
    if payload.get("mode") not in {"text", "keyframe", "reference"}:
        raise ValueError("payload['mode'] 必须是 text、keyframe 或 reference。")
    seconds = payload.get("seconds")
    if seconds is not None and seconds not in {str(value) for value in range(4, 13)}:
        raise ValueError("payload['seconds'] 必须是 \"4\" 到 \"12\" 的字符串。")
    size = payload.get("size")
    if size is not None and size not in {"720P", "1080P", "1K", "2K"}:
        raise ValueError("payload['size'] 不是该模型支持的尺寸。")
    aspect_ratio = payload.get("aspect_ratio")
    if aspect_ratio is not None and aspect_ratio not in {"21:9", "16:9", "4:3", "1:1", "3:4", "9:16"}:
        raise ValueError("payload['aspect_ratio'] 不是支持的画幅比例。")
    if payload.get("mode") != "keyframe":
        raise ValueError("首尾帧的 mode 必须是 keyframe。")
    if not payload.get("first_frame") and not payload.get("last_frame"):
        raise ValueError("首尾帧至少要填写 first_frame 或 last_frame。")


# ===============================================================
# 步骤4:发送请求并输出结果
# ===============================================================

def main():
    check_config()

    response = requests.post(
        url,
        headers=headers,
        json=payload,
    )

    header_request_id = response.headers.get("x-request-id", "")
    print("status_code:", response.status_code)
    if header_request_id:
        print("header_request_id:", header_request_id)

    content_type = response.headers.get("Content-Type", "")
    if "text/html" in content_type.lower():
        raise RuntimeError(
            f"网关返回了 HTML 页面而不是接口结果(HTTP {response.status_code}),"
            "请检查 url 是否正确、该站点是否已上传 agnes-video 插件。"
        )

    result = read_result(response)
    print_result(result)

    if not response.ok:
        request_id_detail = f",request_id={header_request_id}" if header_request_id else ""
        raise RuntimeError(f"创建首尾帧任务失败:HTTP {response.status_code}{request_id_detail}")
    if not isinstance(result, dict):
        raise RuntimeError("网关返回的不是 JSON 对象。")

    task_id = result.get("id")
    if not isinstance(task_id, str) or not task_id.startswith("task_") or not task_id[5:]:
        raise RuntimeError("创建响应缺少有效的任务 id(task_...)。")
    if result.get("status") == "failed":
        raise RuntimeError("创建任务失败:" + json.dumps(result.get("error"), ensure_ascii=False))
    if result.get("status") not in {"queued", "in_progress", "completed"}:
        raise RuntimeError(f"创建响应的 status 无法识别:{result.get('status')!r}")


if __name__ == "__main__":
    main()

返回示例 ​

json
status_code: 200
{
  "id": "task_RngLfXNol8Zvii9Scxa44pGYxem4DC2z",
  "object": "video",
  "model": "agnes-video-2.5",
  "status": "queued",
  "progress": 0,
  "created_at": 1794548861
}

查询视频 示例代码 ​

python
import json
import time
from urllib.parse import quote

import requests

# ===============================================================
# 步骤1:配置 API 连接信息
# ===============================================================

# 查询视频的网关地址。创建时走官方 POST /v1/videos,查询时走网关 GET /v1/videos/{id}
# 不要改成厂商的 /agnesapi,网关会自己向上游查询
url = "https://www.dmxapi.cn/v1/videos"

# DMXAPI API Key(请替换为您自己的密钥;这里只放占位值)
api_key = "sk-请替换为您自己的密钥"

# 轮询间隔,单位:秒。官方建议 1-2 秒,这里放宽到 5 秒
poll_interval_seconds = 5

# 最长等待时间,单位:秒
max_wait_seconds = 1800


# ===============================================================
# 步骤2:配置请求头
# ===============================================================

headers = {
    "Authorization": f"Bearer {api_key}",  # DMXAPI 网关鉴权
    "Accept": "application/json",  # 返回 JSON
}

# ===============================================================
# 步骤3:配置请求参数
# ===============================================================

params = {
    # 【task_id】(string, 必填) 创建接口返回的 id,形如 task_...
    "task_id": "task_RngLfXNol8Zvii9Scxa44pGYxem4DC2z",
}


def read_result(response):
    """优先解析 JSON,解析失败时保留原始文本。"""
    try:
        return response.json()
    except ValueError:
        return response.text


def print_result(result):
    """格式化输出 JSON 或纯文本结果。"""
    if isinstance(result, (dict, list)):
        print(json.dumps(result, indent=2, ensure_ascii=False))
    else:
        print(result)


def check_config():
    """查询前检查用户配置。"""
    if not api_key.strip() or api_key.startswith("{{") or "请替换" in api_key:
        raise RuntimeError("请先在步骤1配置区填写真实的 api_key。")
    task_id = params.get("task_id")
    if not isinstance(task_id, str) or not task_id.startswith("task_") or not task_id[5:]:
        raise ValueError("params['task_id'] 必须是创建接口返回的 task_...。")
    if "请替换" in task_id:
        raise ValueError("请先把 params['task_id'] 换成创建接口返回的 id。")
    if poll_interval_seconds <= 0 or max_wait_seconds <= 0:
        raise ValueError("poll_interval_seconds 和 max_wait_seconds 必须大于 0。")


def retry_after_seconds(response):
    """读取 Retry-After 秒数,读取失败时使用轮询间隔。"""
    try:
        return max(0.0, float(response.headers.get("Retry-After", "")))
    except ValueError:
        return float(poll_interval_seconds)


def error_message(result):
    """提取错误信息。"""
    error = result.get("error") if isinstance(result, dict) else None
    if isinstance(error, dict) and (error.get("code") or error.get("message")):
        return f"{error.get('code')}: {error.get('message')}"
    return json.dumps(result, ensure_ascii=False) if isinstance(result, dict) else str(result)


# ===============================================================
# 步骤4:发送请求并输出结果
# ===============================================================

def main():
    check_config()

    task_id = params["task_id"]
    query_url = f"{url}/{quote(task_id, safe='')}"
    deadline = time.monotonic() + max_wait_seconds
    transient_errors = 0

    while True:
        try:
            response = requests.get(query_url, headers=headers)
        except requests.RequestException as exc:
            transient_errors += 1
            if transient_errors >= 3:
                raise RuntimeError(f"查询连续网络失败:{exc}") from exc
            time.sleep(poll_interval_seconds)
            continue

        content_type = response.headers.get("Content-Type", "")
        if "text/html" in content_type.lower():
            raise RuntimeError(
                f"网关返回了 HTML 页面而不是接口结果(HTTP {response.status_code}),"
                "请检查 url 是否正确、该站点是否已上传 agnes-video 插件。"
            )

        result = read_result(response)

        if response.status_code in {429, 500, 502, 503, 504}:
            transient_errors += 1
            if transient_errors >= 3:
                print_result(result)
                raise RuntimeError(f"查询连续返回 HTTP {response.status_code},已停止。")
            time.sleep(retry_after_seconds(response))
            continue

        if not response.ok:
            print_result(result)
            raise RuntimeError(f"查询失败:HTTP {response.status_code}")
        if not isinstance(result, dict):
            raise RuntimeError("网关返回的不是 JSON 对象。")
        transient_errors = 0

        if result.get("id") != task_id:
            raise RuntimeError(f"查询响应的 id 与请求不一致:{result.get('id')!r}")

        status = result.get("status")
        if status == "completed":
            print_result(result)
            return
        if status in {"queued", "in_progress"}:
            if time.monotonic() >= deadline:
                raise TimeoutError(f"任务轮询超时({max_wait_seconds} 秒)。")
            time.sleep(poll_interval_seconds)
            continue
        if status in {"failed", "incomplete"}:
            print_result(result)
            raise RuntimeError(f"任务未成功(status={status}):{error_message(result)}")
        raise RuntimeError(f"无法识别的 status:{status!r}")


if __name__ == "__main__":
    main()

返回示例 ​

json
{
  "completed_at": 1794549111,
  "created_at": 1794548861,
  "error": null,
  "expires_at": null,
  "id": "task_RngLfXNol8Zvii9Scxa44pGYxem4DC2z",
  "model": "agnes-video-2.5",
  "object": "video",
  "progress": 100,
  "quality": "standard",
  "seconds": "5",
  "size": "720P",
  "started_at": 1794548991,
  "status": "completed",
  "url": "https://cos-platform-outputs.agnes-ai.cn/videos/agnes-video-2.5/task_sAtxTJ2zB5c4AVc2uyCwDyJZHCZpMHAO.mp4",
  "usage": {
    "input_audio_seconds": 0,
    "input_image_count": 2,
    "input_seconds": 0
  }
}

© 2026 DMXAPI agnes-video-2.5 首尾帧

一个 Key 用全球大模型