影片理解

能力概述

影片理解支援模型根據影片畫面和文字指令進行分析，並回傳描述、時間戳記或結構化結果。典型用途包括：

場景與人物行為描述
影片摘要與內容問答
事件起止時間定位
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 說明

使用建議