> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 视频理解

> 通过 AIHubMix 的 Chat Completions 和 Responses API 调用 Qwen3.7 Plus，传入公网或本地 MP4 视频，获取场景描述、事件时间戳和 JSON 结果。

## 能力概述

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

* 场景与人物行为描述
* 视频摘要与内容问答
* 事件起止时间定位
* 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 指南](https://docs.aihubmix.com/cn/api/Gemini-Guides.md)。

## 快速开始

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

```javascript Chat 公网 MP4 theme={null}
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 请求中的视频地址不能直接使用本地文件路径。

```javascript Chat 本地 MP4 theme={null}
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` 读取视频。

```javascript Responses 本地 MP4 theme={null}
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，字段类型、必填项及时间范围应由应用校验。

## 文件与时长限制

[阿里官方视觉理解文档](https://help.aliyun.com/zh/model-studio/vision)列出 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 模型页](https://aihubmix.com/model/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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.