AI agents: Getting started - ApsaraVideo VOD: Central de Documentação do Alibaba Cloud

O que você pode alcançar

Um agente de IA pode usar este documento para:

Compreender as capacidades principais do VOD: Explore rapidamente os recursos essenciais do VOD, como upload de mídia, transcodificação, reprodução e gerenciamento de ativos de mídia, por meio da visão geral estruturada dos módulos.
Aprender a chamar APIs: Encontre documentações específicas de módulos com operações de API, descrições de parâmetros e exemplos de uso no índice llms.txt.
Entender autenticação e autorização: Configure credenciais para chamadas à API do VOD usando métodos de autenticação compatíveis, como AccessKey e credenciais temporárias STS.
Lidar com erros comuns: Resolva problemas independentemente usando os códigos de erro comuns e os métodos de solução de problemas fornecidos.

Pré-requisitos

Antes de usar a API do VOD, conclua as etapas a seguir:

Ativar o VOD: Ative o Alibaba Cloud Video on Demand (VOD) no console do Alibaba Cloud.
Criar um AccessKey: Crie um AccessKey ID e um AccessKey Secret no console do RAM. Por motivos de segurança, recomendamos criar um usuário RAM dedicado para chamadas à API do VOD e conceder a permissão AliyunVODFullAccess.
Instalar um SDK: Use um SDK do Alibaba Cloud para chamar a API do VOD. O código de product POP para o VOD é vod e a versão da API é 2017-03-21.

Parâmetros padrão e convenções

Antes de chamar a API do VOD, observe os seguintes valores padrão e convenções:

ID de aplicativo padrão: app-1000000. Se o sistema de múltiplos aplicativos não estiver ativado, todas as chamadas de API serão associadas ao aplicativo padrão.
Armazenamento padrão: Caso não seja especificado um StorageLocation, os arquivos serão enviados para o endereço de armazenamento padrão.
Grupo de modelos de transcodificação padrão: Se nenhum TemplateGroupId for especificado e não houver workflow associado, o modelo de transcodificação padrão (um grupo de modelos sem transcodificação) será usado.
Protocolo de chamada de API: Use HTTPS em todas as chamadas de API para garantir a transferência segura de dados.
Assinatura de solicitação: Todas as solicitações de API exigem verificação de assinatura. O método de assinatura usa HMAC-SHA1. Os SDKs lidam automaticamente com a assinatura.

llms.txt

O arquivo llms.txt é um índice da documentação do VOD otimizado para LLMs, hospedado no Alibaba Cloud OSS. Ele reorganiza a documentação oficial por cenário, API e caminho de subdocumento, incluindo uma lista de Common mistakes to avoid para orientar a geração de código. Um agente de codificação pode carregar o arquivo integralmente e expandir seções sob demanda.

A url base para acessar o arquivo de índice é:

https://ice-document-materials.oss-cn-shanghai.aliyuncs.com/vod/llms/llms.txt

Relação com a documentação oficial: o llms.txt é um índice. Subdocumentos como Media Upload/Upload from URL.md são versões condensadas das informações principais da documentação oficial. A equipe de documentação do VOD mantém o conteúdo consistente e sincronizado com o site oficial.

Módulos do VOD

Os recursos do VOD são organizados em módulos, cada um correspondendo a um conjunto de operações de API. A tabela a seguir lista esses módulos com links para suas documentações, também indexados em llms.txt. Estes links foram projetados para consumo direto por agentes de IA.

Módulo	Descrição	Link do documento llms
Upload de mídia	Envie áudio, vídeo, imagens e ativos de mídia auxiliares usando o console, sdk do lado do cliente, API do lado do servidor ou uma url.	Visão geral do upload de mídia
Gerenciamento de ativos de mídia	Gerencie os ativos de mídia enviados. Execute operações como consulta de informações, atualização de metadados, exclusão de ativos e definição de status.	Visão geral do gerenciamento de ativos de mídia
Processamento de mídia	Processe arquivos de áudio e vídeo com recursos como transcodificação, captura de snapshot, geração de imagens animadas e composição de marca d'água. Suporta grupos de modelos de transcodificação personalizados, orquestração de workflow e modelos de IA para revisão inteligente e geração de capas inteligentes.	Visão geral do processamento de mídia
Reprodução de áudio e vídeo	Reproduza conteúdo de áudio e vídeo enviado e processado. A reprodução está disponível no console, em um Player sdk ou em players de terceiros.	Reprodução de áudio e vídeo
Segurança de mídia	Framework de segurança que previne hotlinking, downloads não autorizados e distribuição ilegal de conteúdo de áudio e vídeo por meio de restrição de acesso, autenticação de url, criptografia de vídeo e marcas d'água digitais.	Visão geral da segurança de mídia
Revisão de mídia	Capacidades de revisão inteligente e manual. A revisão inteligente identifica automaticamente conteúdo não conforme (como pornografia, violência e conteúdo político) em áudio e vídeo, e suporta modelos de revisão de IA personalizados. A revisão manual fornece APIs para criar tarefas de revisão e enviar resultados.	Revisão inteligente
Video AI	Análise e processamento automatizados de conteúdo de áudio e vídeo, incluindo revisão inteligente, reconhecimento de tags, comparação de DNA e geração de capas.	Visão geral do Video AI
Edição na cloud	Capacidades de edição de vídeo baseadas na cloud. Use APIs para criar projetos de edição, gerenciar materiais e realizar composição de vídeo.	Produção de mídia (Edição na cloud)
Distribuição e aceleração cdn	Configure nomes de domínio acelerados, obtenha URLs e credenciais de reprodução, além de distribuir e reproduzir áudio e vídeo. Suporta recursos de reprodução segura, como aceleração cdn, autenticação de url e criptografia DRM.	Distribuição e aceleração cdn
Notificação de eventos	Receba notificações sobre eventos de processamento de mídia, como conclusão de upload ou transcodificação, via callbacks HTTP ou Message service (MNS).	Notificação de eventos
Estatísticas de dados	Consulte o uso, monitore o consumo de recursos e realize análises estatísticas para entender a utilização dos recursos.	Monitoramento de dados
Sistema de múltiplos aplicativos	Crie vários aplicativos sob uma única conta Alibaba Cloud para isolar logicamente ativos de mídia, configurações e permissões. Suporta controle no nível do aplicativo sobre upload de mídia, reprodução, gerenciamento de ativos de mídia e callbacks de mensagens.	Sistema de múltiplos aplicativos
sdk do lado do servidor	Use SDKs para Java, Python, PHP e C/C++ para chamar APIs de upload, gerenciamento e processamento de mídia.	sdk do lado do servidor
Live-to-VOD	Grave uma transmissão ao vivo em tempo real e armazene-a automaticamente como um ativo de mídia sob demanda para reprodução, gerenciamento e distribuição subsequentes.	Configurar Live-to-VOD
Faturamento	Modelos de pagamento conforme o uso e assinatura baseados em métricas como capacidade de armazenamento, tráfego e largura de banda, duração de transcodificação, gerenciamento de mídia e services de valor agregado.	Visão geral do faturamento
Solução de minisséries	Uma solução completa para produção e operações de minisséries baseada no VOD. Oferece produção de conteúdo, gerenciamento de ativos de mídia, insights de dados, além de distribuição e reprodução eficientes.	Solução de minisséries
Player sdk	Ferramenta de reprodução de áudio e vídeo desenvolvida pelo Alibaba Cloud para todas as plataformas (Web, Android e iOS), oferecendo reprodução estável e fluida para streaming sob demanda e ao vivo.	Visão geral do Player sdk
AliPlayerKit	Framework de UI de player low-code para services de vídeo que oferece componentes extensíveis e soluções baseadas em cenários para integração rápida com streaming sob demanda, ao vivo e outros casos de uso.	Visão geral do PlayerKits
Referência de API	OpenAPI para todo o ciclo de vida de ativos de mídia, suportando operações como upload, gerenciamento, processamento, distribuição e reprodução.	Visão geral da API

Upload de mídia

O VOD oferece diversos métodos para upload de mídia:

Upload pelo servidor: Chame a operação CreateUploadVideo para obter uma url e credencial de upload e, em seguida, envie o arquivo usando um sdk ou via HTTP. Este método é ideal para uploads a partir de servidores backend.
Upload pelo cliente: Envie vídeos diretamente do cliente usando um AccessKey ou uma credencial temporária STS.
Upload via url: Chame a operação UploadMediaByURL e forneça a url do arquivo de source. O service VOD busca e envia o arquivo automaticamente. Esta opção é recomendada para migrações em massa ou importação de mídia de URLs de terceiros.

Parâmetros principais

Os seguintes parâmetros são críticos ao chamar CreateUploadVideo:

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
FileName	String	Sim	—	O caminho completo e nome do arquivo de mídia de source, incluindo a extensão (ex.: `video_01.mp4`).
Title	String	Sim	—	O título da mídia. Máximo de 128 caracteres.
Description	String	Não	—	A descrição do áudio ou vídeo. Comprimento máximo: 1.024 caracteres.
CateId	Long	Não	—	O id da categoria. Você encontra este id no console: Configuration Management > Media Asset Management Configuration > Category Management.
Tags	String	Não	—	Até 16 tags separadas por vírgulas. Cada tag pode ter no máximo 32 caracteres.
TemplateGroupId	String	Não	—	O id do grupo de modelos de transcodificação. Se você especificar este parâmetro, a transcodificação será acionada automaticamente após a conclusão do upload. Encontre-o no console navegando até Configuration Management > Media Processing > Transcoding Template Groups.
WorkflowId	String	Não	—	O id do workflow. Ao especificar este parâmetro, o workflow é acionado automaticamente após a conclusão do upload. Se tanto `WorkflowId` quanto `TemplateGroupId` forem especificados, `WorkflowId` terá precedência.
StorageLocation	String	Não	—	O endereço de armazenamento. Se não for especificado, o arquivo será enviado para o endereço de armazenamento padrão. Localize-o no console navegando até Configuration Management > Media Asset Management Configuration > Storage.
CoverURL	String	Não	—	A url de uma capa de vídeo personalizada.
AppId	String	Não	`app-1000000`	O id do aplicativo. Especifica o aplicativo em um sistema de múltiplos aplicativos.

Gerenciamento de ativos de mídia

Gerencie ativos de áudio, vídeo e mídia auxiliar enviados. As operações principais incluem:

Consultar informações de ativos de mídia: GetVideoInfo (consulta um único vídeo), GetVideoInfos (consulta vários vídeos em lote), SearchMedia (busca ativos de mídia).
Atualizar informações de ativos de mídia: UpdateVideoInfo (atualiza informações de vídeo), UpdateImageInfos (atualiza informações de imagem).
Excluir ativos de mídia: DeleteVideo (exclui vídeos), DeleteAttachedMedia (exclui ativos de mídia auxiliares).
Operações em lote: BatchGetMediaInfos (recupera informações de até 20 ativos de mídia por vez).

Nota

O id de mídia (VideoId, MediaId ou ImageId) é o identificador exclusivo para o gerenciamento de ativos de mídia. Ao enviar um vídeo, CreateUploadVideo retorna um VideoId. Ao enviar um ativo de mídia auxiliar, CreateUploadAttachedMedia retorna um MediaId.

Processamento de mídia

Recursos de transcodificação de áudio e vídeo, captura de snapshot e revisão por IA.

Transcodificação: Configure parâmetros de transcodificação usando um grupo de modelos de transcodificação (AddTranscodeTemplateGroup). É possível acionar a transcodificação automática especificando um TemplateGroupId durante o upload ou usando um workflow. Defina parâmetros como codec de vídeo (por exemplo, H.264), resolução (por exemplo, 640×360) e bitrate (por exemplo, 400 kbps).
Captura de snapshot: Configure parâmetros de snapshot usando um modelo de snapshot (AddVodTemplate com TemplateType definido como Snapshot). Suporta vários tipos, incluindo snapshots padrão e sprites.
Revisão inteligente: Configure itens de revisão (como pornografia, violência e conteúdo político) e escopos (imagem de capa, conteúdo de vídeo e texto do título) usando um modelo de IA (AddAITemplate com TemplateType definido como AIMediaAudit). A revisão é acionada automaticamente após o upload do vídeo. Também é possível chamar CreateAudit para revisão manual.
Capa inteligente: Gere automaticamente uma capa de vídeo usando um modelo de IA (com TemplateType definido como AIImage).

Parâmetros de revisão inteligente

Ao chamar AddAITemplate para criar um modelo de revisão de IA:

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
TemplateName	String	Sim	—	O nome do modelo de IA. Comprimento máximo: 128 bytes.
TemplateType	String	Sim	—	O tipo de modelo: `AIMediaAudit` (revisão inteligente) ou `AIImage` (capa inteligente).
TemplateConfig	String	Sim	—	A configuração do modelo como uma string JSON. Inclui `AuditItem` (itens de revisão como `terrorism` e `porn`), `AuditRange` (escopos de revisão como `image-cover`, `text-title` e `video`) e `AuditAutoBlock` (se deve bloquear conteúdo automaticamente: `yes`/`no`).

Distribuição e reprodução

Recuperação de url de reprodução de vídeo e capacidades de reprodução segura.

Obter URLs de reprodução: Chame GetPlayInfo para obter URLs de reprodução de vídeo. Especifique o formato de saída (como MP4, FLV ou HLS) e a definição.
Obter credencial de reprodução: Chame GetVideoPlayAuth para obter uma credencial de reprodução para reprodução criptografada (seja criptografia padrão HLS ou criptografia proprietária do Alibaba Cloud).
Gerenciamento de nomes de domínio: Chame AddVodDomain para adicionar um nome de domínio acelerado, BatchStartVodDomain para ativá-lo e BatchStopVodDomain para desativá-lo.

Parâmetros de configuração de domínio

Ao chamar AddVodDomain para adicionar um nome de domínio acelerado:

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
DomainName	String	Sim	—	O nome de domínio acelerado. Nomes de domínio curinga são suportados, como `*.example.com`.
Sources	String	Sim	—	A lista de endereços de source como um array JSON. Formato: `[{"content":"1.1.1.1","type":"ipaddr","priority":"20","port":80}]`.
Scope	String	Não	`domestic`	O escopo de aceleração: `domestic` (China continental), `overseas` (regiões fora da China continental, incluindo Hong Kong, Macau e Taiwan) ou `global` (aceleração global).

Erros comuns e solução de problemas

Código de erro	Descrição	Solução de problemas
InvalidAccessKeyId.NotFound	O AccessKey id especificado não existe.	Use `aliyun configure` para verificar sua configuração de AccessKey ou verifique o status do AccessKey no console do RAM.
SignatureDoesNotMatch	A assinatura não corresponde ao resultado calculado.	Ative os logs de depuração do sdk para solucionar o problema de assinatura: `export ALIBABA_CLOUD_LOG_LEVEL=debug`.
InvalidParameter	O parâmetro é inválido.	Verifique se os parâmetros da solicitação atendem aos requisitos (como tipo, comprimento e obrigatoriedade) consultando a documentação de cada API.
Forbidden.AccessDenied	Permissões insuficientes.	Confirme se o usuário RAM recebeu as permissões necessárias do VOD, como `AliyunVODFullAccess`. Verifique as políticas concedidas executando `aliyun ram ListPoliciesForUser --UserName <user>`.
ServiceUnavailable	O service está temporariamente indisponível.	Problema temporário no service. Tente novamente a solicitação com backoff exponencial.
QuotaExceeded.UploadVideo	O número de vídeos enviados excedeu a cota.	Verifique a cota de upload da sua conta. Envie um ticket para solicitar um aumento de cota.
MediaNotFound	O ativo de mídia não existe.	Confirme se o `VideoId` ou `MediaId` está correto e se o ativo de mídia não foi excluído.
InvalidStatus.Media	O ativo de mídia está em um estado inválido para esta operação.	O ativo está em um estado que impede esta operação (ex.: 'em revisão'). Chame `GetVideoInfo` para verificar o status atual antes de tentar novamente.