動画理解

概要

動画理解では、モデルが動画のフレームとテキストの指示を分析し、説明、タイムスタンプ、構造化された結果を返します。主な用途は次のとおりです。

シーンや人物の行動の説明
動画の要約と内容に関する質問への回答
イベントの開始時刻と終了時刻の特定
JSON 形式での情報抽出

このガイドでは qwen3.7-plus を例に、Chat Completions と Responses API で MP4 を入力する方法を紹介します。

API と入力形式

モデルとエンドポイント	動画コンテンツのフィールド	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 を設定してください。サンプル URL は Alibaba の公式ドキュメントに掲載されている公開 MP4 です。アプリケーションで使用する際は、url をモデルプロバイダーがアクセスできる動画 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 として渡します。以下の例はコマンドラインの第 1 引数からファイルパスを読み取り、指定がなければ現在のディレクトリの video.mp4 を読み取ります。HTTP リクエストの動画 URL にローカルファイルのパスを直接指定することはできません。

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 で設定します。以下の例もコマンドラインの第 1 引数、または現在のディレクトリの 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 を抽出してください。出力使用量には推論トークンが含まれる場合があるため、最終的な JSON の長さだけで料金を見積もることはできません。

構造化出力

サンプルでは JSON モードで scenes 配列を返します。各シーンには次のフィールドが含まれます。

フィールド	型	説明
`start_seconds`	数値	シーンの開始時刻、単位は秒
`end_seconds`	数値	シーンの終了時刻、単位は秒
`description`	文字列	シーンの内容の説明

アプリケーションの要件に応じてプロンプトやフィールドを調整できます。JSON モードは JSON 出力を保証します。フィールドの型、必須項目、時間範囲はアプリケーション側で検証してください。

ファイルと長さの制限

Alibaba の公式視覚理解ドキュメントには、Qwen3.7 シリーズの動画制限が記載されています。

動画形式には MP4、AVI、MKV、MOV、FLV、WMV が含まれます。
動画の長さは 2 秒から 2 時間です。
Base64 エンコード後の文字列は 10MB 未満にする必要があります。元のファイルは 7MB 未満を推奨します。
公開 URL を使用する場合、プロバイダーのファイルサイズ上限は 2GB です。

Base64 はリクエストサイズを増加させます。大きなファイルには公開動画 URL を優先し、リクエスト全体を通してリンクが有効であることを確認してください。

料金とトークン

Qwen は動画のフレームを入力トークンに変換し、プロンプトと合わせて入力使用量に計上します。モデルの生成内容は出力使用量に計上されます。動画の長さ、解像度、フレームの抽出方法が使用量に影響するため、MP4 のファイルサイズや秒数だけでは料金を算出できません。 Qwen3.7 Plus の動画入力にはモデルの入力トークン単価、生成内容には出力トークン単価が適用されます。料金は Qwen3.7 Plus モデルページを参照してください。

Chat Completions の使用量フィールドは usage.prompt_tokens と usage.completion_tokens です。
Responses の使用量フィールドは usage.input_tokens と usage.output_tokens です。
推論トークンは出力トークンに含まれているため、重複して加算しないでください。
キャッシュにヒットした部分には適用対象のキャッシュ料金が適用されます。

コンソールで各リクエストのトークン使用量と料金を確認できます。個別のリクエストを調査する際は、レスポンスヘッダーの x-aihubmix-request-id を保持してください。

利用上の推奨事項

動画とテキストの指示を一緒に送信し、抽出する情報と出力形式を明示してください。
公開動画リンクはリクエスト中に有効で、モデルプロバイダーからアクセスできる必要があります。
小さなローカルファイルには Base64、大きなファイルには公開 URL を優先してください。
アプリケーションで JSON フィールド、シーンの順序、時間範囲を検証してください。
タイムスタンプはイベントの特定や内容の検索に適しています。精密な編集には動画処理ツールで境界を調整してください。

更新日：2026-10-13

はじめに

コンソールガイド

エンタープライズとチーム

ゲートウェイ機能

モデル機能

プロトコルリファレンス

プラットフォーム管理

概要

API と入力形式

クイックスタート

ローカル動画の入力

Responses API

構造化出力

ファイルと長さの制限

料金とトークン

利用上の推奨事項

​概要

​API と入力形式

​クイックスタート

​ローカル動画の入力

​Responses API

​構造化出力

​ファイルと長さの制限

​料金とトークン

​利用上の推奨事項

概要

API と入力形式

クイックスタート

ローカル動画の入力

Responses API

構造化出力

ファイルと長さの制限

料金とトークン

利用上の推奨事項