> ## 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">
  API と入力形式
</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 ガイド](/jp/api/Gemini-Guides)を参照してください。

<h2 id="chat-url">
  クイックスタート
</h2>

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

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

<h2 id="structured-output">
  構造化出力
</h2>

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

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

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

<h2 id="limits">
  ファイルと長さの制限
</h2>

[Alibaba の公式視覚理解ドキュメント](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">
  料金とトークン
</h2>

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

Qwen3.7 Plus の動画入力にはモデルの入力トークン単価、生成内容には出力トークン単価が適用されます。料金は [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` です。
* 推論トークンは出力トークンに含まれているため、重複して加算しないでください。
* キャッシュにヒットした部分には適用対象のキャッシュ料金が適用されます。

コンソールで各リクエストのトークン使用量と料金を確認できます。個別のリクエストを調査する際は、レスポンスヘッダーの `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.