Comprensión de vídeo

Descripción general

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.

API y formatos de entrada

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.

Inicio rápido

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.

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));

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.

Entrada de vídeo local

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.

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));

API Responses

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.

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));

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.

Salida estructurada

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.

Límites de archivo y duración

La documentación oficial de visión de Alibaba 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.

Facturación y tokens

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.

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.

Recomendaciones

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

Empezar

Guías de la consola

Empresa y equipos

Funciones de gateway

Capacidades del modelo

Referencia de protocolo

Gestión de plataforma

Comprensión de vídeo

Descripción general

API y formatos de entrada

Inicio rápido

Entrada de vídeo local

API Responses

Salida estructurada

Límites de archivo y duración

Facturación y tokens

Recomendaciones

​Descripción general

​API y formatos de entrada

​Inicio rápido

​Entrada de vídeo local

​API Responses

​Salida estructurada

​Límites de archivo y duración

​Facturación y tokens

​Recomendaciones

Descripción general

API y formatos de entrada

Inicio rápido

Entrada de vídeo local

API Responses

Salida estructurada

Límites de archivo y duración

Facturación y tokens

Recomendaciones