Compreensão de vídeo

Visão geral

A compreensão de vídeo permite que o modelo analise os quadros de um vídeo com instruções de texto e retorne descrições, marcações de tempo ou resultados estruturados. Os usos comuns incluem:

Descrição de cenas e ações de pessoas
Resumos de vídeos e perguntas sobre seu conteúdo
Localização do início e do fim de eventos
Extração de informações em formato JSON

Este guia usa qwen3.7-plus para demonstrar a entrada de MP4 com Chat Completions e a API Responses.

APIs e formatos de entrada

Modelo e endpoint	Campo de conteúdo de vídeo	Parâmetro de saída JSON
`qwen3.7-plus`, `/v1/chat/completions`	`video_url` em `messages[].content[]`	`response_format.type = "json_object"`
`qwen3.7-plus`, `/v1/responses`	`video_url` em `input[].content[]`	`text.format.type = "json_object"`

Em Responses, video_url é um campo de extensão da AIHubMix. Os exemplos abaixo o enviam por solicitações HTTP. Para entradas multimídia nos modelos Gemini, consulte o guia do Gemini.

Início rápido

O exemplo a seguir usa o fetch integrado ao Node.js 22, sem necessidade de instalar um SDK. Configure AIHUBMIX_API_KEY no ambiente antes de executá-lo. A URL de exemplo é um MP4 público da documentação oficial da Alibaba. Para sua aplicação, substitua url por um endereço de vídeo acessível ao provedor 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));

Salve o código em um arquivo .mjs e execute-o com Node.js. O resultado bem-sucedido está em choices[0].message.content e exige uma segunda análise JSON. O exemplo também imprime o ID da solicitação e o uso para conferência no console.

Entrada de vídeo local

Codifique o arquivo local em Base64 e envie-o como uma URL de dados data:video/mp4;base64,. O exemplo lê o caminho do arquivo no primeiro argumento da linha de comando ou, se nenhum for fornecido, lê video.mp4 no diretório atual. A URL de vídeo de uma solicitação HTTP não pode ser um caminho de arquivo 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

As solicitações Responses também usam o objeto video_url, com input_text para blocos de texto. Configure a saída JSON em text.format. Este exemplo também lê o vídeo do primeiro argumento da linha de comando ou de video.mp4 no diretório atual.

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

O campo output de Responses pode conter itens de raciocínio e de mensagem. Para ler o resultado, selecione output_text nos itens message. O uso de saída pode incluir tokens de raciocínio, portanto o tamanho do JSON final, por si só, não determina o custo.

Saída estruturada

Os exemplos usam o modo JSON para retornar um array scenes. Cada cena contém:

Campo	Tipo	Descrição
`start_seconds`	Número	Tempo de início da cena, em segundos
`end_seconds`	Número	Tempo de término da cena, em segundos
`description`	String	Descrição do conteúdo da cena

Adapte o prompt e os campos às necessidades da aplicação. O modo JSON garante uma saída JSON; a aplicação deve validar os tipos de campo, os campos obrigatórios e os intervalos de tempo.

Limites de arquivo e duração

A documentação oficial de visão da Alibaba informa os seguintes limites de vídeo para a série Qwen3.7:

Os formatos de vídeo incluem MP4, AVI, MKV, MOV, FLV e WMV.
A duração do vídeo varia de 2 segundos a 2 horas.
A string codificada em Base64 deve ser menor que 10MB; recomenda-se um arquivo original menor que 7MB.
Para URLs públicas, o limite de arquivo do provedor é de 2GB.

Base64 aumenta o tamanho da solicitação. Para arquivos maiores, prefira URLs públicas de vídeo e garanta que o link permaneça válido durante toda a solicitação.

Cobrança e tokens

O Qwen converte os quadros do vídeo em tokens de entrada, contabilizados junto com o prompt no uso de entrada. O conteúdo gerado é contabilizado no uso de saída. A duração, a resolução e a amostragem de quadros afetam o uso; o tamanho do MP4 ou sua duração, isoladamente, não permitem calcular o custo. A entrada de vídeo do Qwen3.7 Plus é cobrada pela tarifa de tokens de entrada do modelo, e o conteúdo gerado pela tarifa de tokens de saída. Consulte os preços na página do modelo Qwen3.7 Plus.

Chat Completions informa usage.prompt_tokens e usage.completion_tokens.
Responses informa usage.input_tokens e usage.output_tokens.
Os tokens de raciocínio já estão incluídos nos tokens de saída e não devem ser somados novamente.
A parte atendida pelo cache é cobrada pela tarifa de cache aplicável.

Consulte o uso de tokens e o valor de cada solicitação no console. Preserve o cabeçalho de resposta x-aihubmix-request-id para investigar uma solicitação específica.

Recomendações

Envie o vídeo e as instruções de texto juntos, especificando as informações a extrair e o formato de saída.
Os links públicos de vídeo devem permanecer válidos durante a solicitação e ser acessíveis ao provedor de modelos.
Use Base64 para arquivos locais pequenos e prefira URLs públicas para arquivos maiores.
Valide os campos JSON, a ordem das cenas e os intervalos de tempo na aplicação.
As marcações de tempo são adequadas para localizar eventos e buscar conteúdo. Para edição precisa, ajuste os limites com ferramentas de processamento de vídeo.

Atualizado: 2026-10-13

Começar

Guias do console

Empresa e equipes

Recursos de gateway

Capacidades do modelo

Referência de protocolo

Gestão de plataforma

Compreensão de vídeo

Visão geral

APIs e formatos de entrada

Início rápido

Entrada de vídeo local

API Responses

Saída estruturada

Limites de arquivo e duração

Cobrança e tokens

Recomendações

​Visão geral

​APIs e formatos de entrada

​Início rápido

​Entrada de vídeo local

​API Responses

​Saída estruturada

​Limites de arquivo e duração

​Cobrança e tokens

​Recomendações

Visão geral

APIs e formatos de entrada

Início rápido

Entrada de vídeo local

API Responses

Saída estruturada

Limites de arquivo e duração

Cobrança e tokens

Recomendações