> ## 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.

# Comprensión de vídeo

> Utilice Qwen3.7 Plus mediante las API Chat Completions y Responses de AIHubMix con vídeos MP4 públicos o locales para obtener descripciones de escenas, marcas de tiempo y resultados JSON.

<h2 id="overview">
  Descripción general
</h2>

La comprensión de vídeo permite al modelo analizar los fotogramas de un vídeo junto con instrucciones de texto y devolver descripciones, marcas de tiempo o resultados estructurados. Sus usos habituales incluyen:

* Describir escenas y acciones de personas
* Resumir vídeos y responder preguntas sobre su contenido
* Localizar el inicio y el final de eventos
* Extraer información en formato JSON

Esta guía utiliza `qwen3.7-plus` para mostrar cómo enviar MP4 con Chat Completions y la API Responses.

<h2 id="protocols">
  API y formatos de entrada
</h2>

| Modelo y endpoint | Campo de contenido de vídeo | Parámetro de salida JSON |
| - | - | - |
| `qwen3.7-plus`, `/v1/chat/completions` | `video_url` en `messages[].content[]` | `response_format.type = "json_object"` |
| `qwen3.7-plus`, `/v1/responses` | `video_url` en `input[].content[]` | `text.format.type = "json_object"` |

En Responses, `video_url` es un campo de extensión de AIHubMix. Los ejemplos siguientes lo envían mediante solicitudes HTTP.

Para la entrada multimedia de los modelos Gemini, consulte la [guía de Gemini](/es/api/Gemini-Guides).

<h2 id="chat-url">
  Inicio rápido
</h2>

El siguiente ejemplo utiliza `fetch`, integrado en Node.js 22, sin necesidad de instalar un SDK. Configure `AIHUBMIX_API_KEY` en su entorno antes de ejecutarlo. La URL de ejemplo es un MP4 público de la documentación oficial de Alibaba. Para su aplicación, sustituya `url` por una dirección de vídeo accesible al proveedor de modelos.

<CodeGroup>
  ```javascript Chat: MP4 público 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>

Guarde el código como un archivo `.mjs` y ejecútelo con Node.js. El resultado correcto se encuentra en `choices[0].message.content` y requiere un segundo análisis JSON. El ejemplo también imprime el ID de solicitud y el uso para comprobarlos en la consola.

<h2 id="chat-base64">
  Entrada de vídeo local
</h2>

Codifique el archivo local en Base64 y envíelo como una URL de datos `data:video/mp4;base64,`. El ejemplo lee la ruta del archivo desde el primer argumento de la línea de comandos o, si no se proporciona, lee `video.mp4` del directorio actual. La URL de vídeo de una solicitud HTTP no puede ser una ruta de archivo local.

<CodeGroup>
  ```javascript Chat: MP4 local 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">
  API Responses
</h2>

Las solicitudes Responses también utilizan el objeto `video_url`, con `input_text` para los bloques de texto. Configure la salida JSON en `text.format`. Este ejemplo también lee el vídeo desde el primer argumento de la línea de comandos o desde `video.mp4` en el directorio actual.

<CodeGroup>
  ```javascript Responses: MP4 local 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>

El campo `output` de Responses puede contener elementos de razonamiento y mensajes. Para leer el resultado, seleccione `output_text` de los elementos `message`. El uso de salida puede incluir tokens de razonamiento, por lo que la longitud del JSON final no basta para estimar el coste.

<h2 id="structured-output">
  Salida estructurada
</h2>

Los ejemplos utilizan el modo JSON para devolver un array `scenes`. Cada escena contiene:

| Campo | Tipo | Descripción |
| - | - | - |
| `start_seconds` | Número | Tiempo de inicio de la escena, en segundos |
| `end_seconds` | Número | Tiempo de finalización de la escena, en segundos |
| `description` | Cadena | Descripción del contenido de la escena |

Adapte el prompt y los campos a las necesidades de su aplicación. El modo JSON garantiza una salida JSON; la aplicación debe validar los tipos de campo, los campos obligatorios y los intervalos de tiempo.

<h2 id="limits">
  Límites de archivo y duración
</h2>

La [documentación oficial de visión de Alibaba](https://help.aliyun.com/zh/model-studio/vision) indica los siguientes límites de vídeo para la serie Qwen3.7:

* Los formatos de vídeo incluyen MP4, AVI, MKV, MOV, FLV y WMV.
* La duración del vídeo va de 2 segundos a 2 horas.
* La cadena codificada en Base64 debe ser inferior a 10MB; se recomienda un archivo original inferior a 7MB.
* Para las URL públicas, el límite de archivo del proveedor es de 2GB.

Base64 aumenta el tamaño de la solicitud. Para archivos grandes, dé prioridad a las URL de vídeo públicas y asegúrese de que el enlace siga siendo válido durante toda la solicitud.

<h2 id="billing">
  Facturación y tokens
</h2>

Qwen convierte los fotogramas del vídeo en tokens de entrada, que se contabilizan junto con el prompt en el uso de entrada. El contenido generado se contabiliza como salida. La duración, la resolución y el muestreo de fotogramas influyen en el uso; el tamaño del MP4 o su duración por sí solos no permiten calcular el coste.

La entrada de vídeo de Qwen3.7 Plus se factura a la tarifa de tokens de entrada del modelo y el contenido generado a la tarifa de tokens de salida. Consulte los precios en la [página del modelo Qwen3.7 Plus](https://aihubmix.com/model/qwen3.7-plus).

* Chat Completions informa de `usage.prompt_tokens` y `usage.completion_tokens`.
* Responses informa de `usage.input_tokens` y `usage.output_tokens`.
* Los tokens de razonamiento ya están incluidos en los tokens de salida y no deben sumarse de nuevo.
* La parte servida desde la caché se factura a la tarifa de caché aplicable.

Consulte el uso de tokens y los cargos de cada solicitud en la consola. Conserve el encabezado de respuesta `x-aihubmix-request-id` para investigar una solicitud concreta.

<h2 id="usage-tips">
  Recomendaciones
</h2>

* Envíe el vídeo y las instrucciones de texto juntos, indicando qué información extraer y el formato de salida.
* Los enlaces de vídeo públicos deben seguir siendo válidos durante la solicitud y ser accesibles al proveedor de modelos.
* Utilice Base64 para archivos locales pequeños y dé prioridad a las URL públicas para archivos grandes.
* Valide los campos JSON, el orden de las escenas y los intervalos de tiempo en su aplicación.
* Las marcas de tiempo sirven para localizar eventos y recuperar contenido. Para una edición precisa, ajuste los límites con herramientas de procesamiento de vídeo.

***

Actualizado: 2026-10-13


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