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

# Compreensão de vídeo

> Use o Qwen3.7 Plus pelas APIs Chat Completions e Responses da AIHubMix com vídeos MP4 públicos ou locais para obter descrições de cenas, marcações de tempo e resultados JSON.

<h2 id="overview">
  Visão geral
</h2>

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.

<h2 id="protocols">
  APIs e formatos de entrada
</h2>

| 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](/pt/api/Gemini-Guides).

<h2 id="chat-url">
  Início rápido
</h2>

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.

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

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.

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

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.

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

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.

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

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.

<h2 id="structured-output">
  Saída estruturada
</h2>

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.

<h2 id="limits">
  Limites de arquivo e duração
</h2>

A [documentação oficial de visão da Alibaba](https://help.aliyun.com/zh/model-studio/vision) 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.

<h2 id="billing">
  Cobrança e tokens
</h2>

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](https://aihubmix.com/model/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.

<h2 id="usage-tips">
  Recomendações
</h2>

* 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


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