> ## 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 结果。

<h2 id="overview">
  能力概述
</h2>

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

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

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

<h2 id="protocols">
  接口对比与输入格式
</h2>

| 模型与接口 | 视频内容字段 | 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 指南](/cn/api/Gemini-Guides)。

<h2 id="chat-url">
  快速开始
</h2>

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

<CodeGroup>
  ```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));
  ```
</CodeGroup>

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

<h2 id="chat-base64">
  本地视频输入
</h2>

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

<CodeGroup>
  ```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));
  ```
</CodeGroup>

<h2 id="responses">
  Responses API
</h2>

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

<CodeGroup>
  ```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));
  ```
</CodeGroup>

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

<h2 id="structured-output">
  结构化输出
</h2>

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

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

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

<h2 id="limits">
  文件与时长限制
</h2>

[阿里官方视觉理解文档](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，并确保链接有效期覆盖完整请求过程。

<h2 id="billing">
  计费与 Token 说明
</h2>

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`。

<h2 id="usage-tips">
  使用建议
</h2>

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

***

更新时间：2026-10-13


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