> ## 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 指南](/zh-Hant/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.