视频理解

能力概述

视频理解支持模型根据视频画面和文本指令进行分析，并返回描述、时间戳或结构化结果。典型用途包括：

场景与人物行为描述
视频摘要与内容问答
事件起止时间定位
JSON 格式的信息提取

本文以 qwen3.7-plus 为例，提供 Chat Completions 和 Responses API 的 MP4 调用方式。

接口对比与输入格式

模型与接口	视频内容字段	JSON 输出参数
`qwen3.7-plus`，`/v1/chat/completions`	`messages[].content[]` 中的 `video_url`	`response_format.type = "json_object"`
`qwen3.7-plus`，`/v1/responses`	`input[].content[]` 中的 `video_url`	`text.format.type = "json_object"`

Responses 的 video_url 为 AIHubMix 扩展字段，下文通过 HTTP 请求传入。 Gemini 模型的多媒体输入方式请参见 Gemini 指南。

快速开始

下面使用 Node.js 22 的内置 fetch，无需安装 SDK。运行前在环境中配置 AIHUBMIX_API_KEY。示例地址为阿里官方文档中的公开 MP4；用于业务时，将 url 替换为模型推理厂商能够访问的视频地址。

const response = await fetch("https://aihubmix.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AIHUBMIX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "qwen3.7-plus",
    enable_thinking: false,
    max_tokens: 800,
    response_format: { type: "json_object" },
    messages: [{
      role: "user",
      content: [
        {
          type: "video_url",
          video_url: {
            url: "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241115/cqqkru/1.mp4",
          },
        },
        {
          type: "text",
          text: 'Analyze the attached video. Return a JSON object with a scenes array. Each scene must contain start_seconds, end_seconds and description. If no video is available, return {"error":"no_video"}.',
        },
      ],
    }],
  }),
  signal: AbortSignal.timeout(120000),
});
const result = await response.json();
if (!response.ok) throw new Error(JSON.stringify(result));
const scenes = JSON.parse(result.choices[0].message.content);
console.log(JSON.stringify({
  request_id: response.headers.get("x-aihubmix-request-id"),
  result: scenes,
  usage: result.usage,
}, null, 2));

将代码存为 .mjs 文件后用 Node.js 运行。成功结果位于 choices[0].message.content，需再进行一次 JSON 解析。示例同时打印请求 ID 和用量，便于在控制台核对。

本地视频输入

将本地文件编码为 Base64，再通过 data:video/mp4;base64, 数据 URL 传入。下例从命令行第一个参数读取文件路径，未提供时读取当前目录的 video.mp4。HTTP 请求中的视频地址不能直接使用本地文件路径。

import { readFileSync } from "node:fs";

const video = readFileSync(process.argv[2] ?? "video.mp4").toString("base64");
const response = await fetch("https://aihubmix.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AIHUBMIX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "qwen3.7-plus",
    enable_thinking: false,
    max_tokens: 800,
    response_format: { type: "json_object" },
    messages: [{
      role: "user",
      content: [
        {
          type: "video_url",
          video_url: { url: `data:video/mp4;base64,${video}` },
        },
        {
          type: "text",
          text: 'Analyze the attached video. Return a JSON object with a scenes array. Each scene must contain start_seconds, end_seconds and description. If no video is available, return {"error":"no_video"}.',
        },
      ],
    }],
  }),
  signal: AbortSignal.timeout(120000),
});
const result = await response.json();
if (!response.ok) throw new Error(JSON.stringify(result));
const scenes = JSON.parse(result.choices[0].message.content);
console.log(JSON.stringify({
  request_id: response.headers.get("x-aihubmix-request-id"),
  result: scenes,
  usage: result.usage,
}, null, 2));

Responses API

Responses 请求仍使用 video_url 对象，文本块改为 input_text。将 JSON 输出设置放在 text.format 下。下面的示例同样从命令行第一个参数或当前目录的 video.mp4 读取视频。

import { readFileSync } from "node:fs";

const video = readFileSync(process.argv[2] ?? "video.mp4").toString("base64");
const response = await fetch("https://aihubmix.com/v1/responses", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AIHUBMIX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "qwen3.7-plus",
    max_output_tokens: 800,
    text: { format: { type: "json_object" } },
    input: [{
      role: "user",
      content: [
        {
          type: "video_url",
          video_url: { url: `data:video/mp4;base64,${video}` },
        },
        {
          type: "input_text",
          text: 'Analyze the attached video. Return a JSON object with a scenes array. Each scene must contain start_seconds, end_seconds and description. If no video is available, return {"error":"no_video"}.',
        },
      ],
    }],
  }),
  signal: AbortSignal.timeout(120000),
});
const result = await response.json();
if (!response.ok || result.status !== "completed") {
  throw new Error(JSON.stringify(result));
}
const text = result.output
  .filter((item) => item.type === "message")
  .flatMap((item) => item.content)
  .filter((part) => part.type === "output_text")
  .map((part) => part.text)
  .join("");
console.log(JSON.stringify({
  request_id: response.headers.get("x-aihubmix-request-id"),
  result: JSON.parse(text),
  usage: result.usage,
}, null, 2));

Responses 的 output 可能同时包含推理项和消息项，读取结果时应筛选 message 中的 output_text。输出用量可能包含推理 Token，不能只按最终 JSON 的长度估算费用。

结构化输出

示例通过 JSON 模式返回 scenes 数组，每个场景包含：

字段	类型	含义
`start_seconds`	数值	场景开始时间，单位为秒
`end_seconds`	数值	场景结束时间，单位为秒
`description`	字符串	场景内容描述

应用中可根据业务需求调整提示词和字段。JSON 模式确保输出为 JSON，字段类型、必填项及时间范围应由应用校验。

文件与时长限制

阿里官方视觉理解文档列出 Qwen3.7 系列的视频限制：

视频格式包括 MP4、AVI、MKV、MOV、FLV、WMV。
视频时长为 2 秒至 2 小时。
Base64 编码后的字符串需小于 10MB，原始文件建议小于 7MB。
公网 URL 方式的厂商文件上限为 2GB。

Base64 会增大请求体积。较大文件可优先考虑公网视频 URL，并确保链接有效期覆盖完整请求过程。

计费与 Token 说明

Qwen 的视频画面会转换为输入 Token，与提示词一起计入输入用量，模型生成内容计入输出用量。视频时长、分辨率和抽帧方式都会影响用量，不能仅按 MP4 文件大小或秒数推算费用。 Qwen3.7 Plus 的视频输入按模型输入 Token 单价计费，生成内容按输出 Token 单价计费。模型价格请参见 Qwen3.7 Plus 模型页。

Chat Completions 的用量字段为 usage.prompt_tokens 和 usage.completion_tokens。
Responses 的用量字段为 usage.input_tokens 和 usage.output_tokens。
推理 Token 已包含在输出 Token 中，无需重复相加。
缓存命中部分按适用的缓存价格计费。

可在控制台查看每次请求的 Token 用量与消费金额。需要排查具体请求时，保留响应头中的 x-aihubmix-request-id。

使用建议

视频与文本指令一起发送，明确需要提取的内容和输出格式。
公网视频链接应在请求期间保持有效，并允许模型推理厂商访问。
本地小文件使用 Base64，较大文件优先使用公网 URL。
在应用中校验 JSON 字段、场景顺序和时间范围。
时间戳适合事件定位与内容检索；需要精确剪辑时，结合视频处理工具校准边界。

更新时间：2026-10-13

开始使用

控制台使用

企业与团队

网关能力

模型能力

协议参考

平台管理

能力概述

接口对比与输入格式

快速开始

本地视频输入

Responses API

结构化输出

文件与时长限制

计费与 Token 说明

使用建议

​能力概述

​接口对比与输入格式

​快速开始

​本地视频输入

​Responses API

​结构化输出

​文件与时长限制

​计费与 Token 说明

​使用建议

能力概述

接口对比与输入格式

快速开始

本地视频输入

Responses API

结构化输出

文件与时长限制

计费与 Token 说明

使用建议