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

O que você pode alcançar

Um agente de IA pode utilizar este documento para:

@id="p-x-01" 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.

@id="p-x-02" Aprender a chamar APIs: Localize documentações específicas de módulos contendo operações de API, descrições de parâmetros e exemplos de uso através do índice llms.txt.

@id="p-x-03" Entender autenticação e autorização: Configure credenciais para chamadas de API do VOD usando métodos de autenticação suportados, como AccessKey e credenciais temporárias STS.

@id="p-x-04" Tratar erros comuns: Resolva problemas de forma independente utilizando 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 de API do VOD e conceder a permissão AliyunVODFullAccess.
Instalar um SDK: Utilize 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.

Diretivas de autenticação para agentes de IA:

Nível	Diretiva
MUST	Crie um usuário RAM dedicado para chamadas de API do VOD. Não utilize as credenciais da conta raiz do Alibaba Cloud.
MUST	Conceda a permissão `AliyunVODFullAccess` ao usuário RAM antes de realizar qualquer chamada de API do VOD.
MUST	Armazene as credenciais em variáveis de ambiente: `ALIBABA_CLOUD_ACCESS_KEY_ID` e `ALIBABA_CLOUD_ACCESS_KEY_SECRET`.
NEVER	Codifique o AccessKey ID ou o AccessKey Secret diretamente no source code, em arquivos de configuração ou em prompts.
PREFER	Utilize credenciais temporárias STS (`SecurityToken` + AccessKey de curta duração) em vez de pares de AccessKey de longa duração para cargas de trabalho em produção.
PREFER	Utilize o SDK do Alibaba Cloud em vez de requisições HTTP diretas. O SDK gerencia assinatura, tentativas de nova execução e credenciais automaticamente.

Parâmetros padrão e convenções

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

@id="p-x-14" ID de aplicativo padrão [MUST know]: @id="code-app-100000-01" 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. NEVER passe AppId a menos que você tenha ativado explicitamente o sistema de múltiplos aplicativos para sua conta.

@id="p-x-15" Armazenamento padrão [PREFER explicit]: Caso você não especifique um @id="code-storageloc-01" StorageLocation, os arquivos serão enviados para o endereço de armazenamento padrão. PREFER especificar StorageLocation explicitamente nas chamadas de API para evitar dependência do padrão.

@id="p-x-16" Grupo de modelos de transcodificação padrão [MUST know]: Se você não especificar um @id="code-templategr-01" TemplateGroupId e nenhum workflow estiver associado, o modelo de transcodificação padrão (um grupo de modelos sem transcodificação) será utilizado. Isso significa que o vídeo enviado é armazenado como está, sem transcodificação. MUST especificar TemplateGroupId ou WorkflowId se precisar que o vídeo seja transcodificado após o upload.

@id="p-x-17" Protocolo de chamada de API [MUST]: MUST usar HTTPS para todas as chamadas de API a fim de garantir a transferência segura de dados. O protocolo HTTP é suportado, mas não recomendado.

@id="p-x-18" Assinatura de requisição [MUST]: Todas as requisições de API MUST incluir uma assinatura válida. O método de assinatura utiliza @id="code-hmac-sha1-01" HMAC-SHA1. Os SDKs gerenciam a assinatura automaticamente. NEVER tente chamar a API sem uma assinatura válida.

Resumo das restrições de parâmetros padrão:

Parâmetro	Padrão	MUST / PREFER / NEVER
`AppId`	`app-1000000`	NEVER passar a menos que o sistema de múltiplos aplicativos esteja ativado
`StorageLocation`	Armazenamento padrão da conta	PREFER especificar explicitamente
`TemplateGroupId`	Sem transcodificação	MUST especificar se a transcodificação for necessária
Protocolo	HTTPS/HTTP	MUST usar HTTPS
Assinatura	`HMAC-SHA1`	MUST incluir; NEVER ignorar

llms.txt

O arquivo llms.txt é um índice otimizado para LLMs da documentação do VOD 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: 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.

Diretivas para agentes de IA que consomem llms.txt:

Nível	Diretiva
MUST	Carregue o arquivo `llms.txt` completo na primeira interação com o VOD. Não o ignore nem faça leitura parcial.
MUST	Trate cada item na seção `Common mistakes to avoid` como uma restrição rígida ao gerar código.
MUST	Codifique caracteres chineses na URL ao construir URLs de subdocumentos. Anexe o caminho relativo do llms.txt à URL base: `https://ice-document-materials.oss-cn-shanghai.aliyuncs.com/vod/llms/{relative_path}`.
PREFER	Carregue subdocumentos específicos do módulo sob demanda, em vez de todos de uma vez. Busque apenas o subdocumento relevante para a tarefa atual.
NEVER	Gere código de API do VOD sem antes ler o subdocumento do módulo relevante no llms.txt.
NEVER	Presuma comportamentos da API não documentados explicitamente no llms.txt ou em seus subdocumentos.

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 de Upload de Mídia
Gerenciamento de ativos de mídia	Gerencie 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 que foi enviado e processado. A reprodução está disponível através do console, de um Player SDK ou de players de terceiros.	Reprodução de Áudio e Vídeo
Segurança de mídia	Uma estrutura de segurança que previne hotlinking, downloads não autorizados e distribuição ilegal de conteúdo de áudio e vídeo através 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 revisão manual. A revisão inteligente identifica automaticamente conteúdo não compatível (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 tag, comparação de DNA e geração de capas.	Visão Geral do Video AI
Edição em cloud	Capacidades de edição de vídeo baseadas em 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 em Cloud)
Distribuição e aceleração via CDN	Configure nomes de domínio acelerados, obtenha URLs de reprodução e credenciais de reprodução, além de distribuir e reproduzir áudio e vídeo. Suporta recursos de reprodução segura, como aceleração de CDN, autenticação de URL e criptografia DRM.	Distribuição e Aceleração via 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	Faturamento pagamento conforme o uso e por assinatura com base 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 para 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 e distribuição e reprodução eficientes.	Solução para Minisséries
Player SDK	Uma ferramenta de reprodução de áudio e vídeo multiplataforma desenvolvida pelo Alibaba Cloud para Web, Android e iOS, que fornece reprodução estável e suave de streaming sob demanda e ao vivo.	Visão Geral do Player SDK
AliPlayerKit	Um 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 cenários.	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:

@id="p-x-19" Upload pelo servidor: Chame a operação @id="code-createuplo-01" 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.

@id="p-x-20" Upload pelo cliente: Envie vídeos diretamente do cliente utilizando um AccessKey ou uma credencial temporária STS.

@id="p-x-21" Upload via URL: Chame a operação @id="code-uploadmedi-01" UploadMediaByURL e forneça a URL do arquivo de origem. O service VOD busca e envia o arquivo automaticamente. Esta opção é ideal 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 origem. MUST incluir 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írgula. Cada tag pode ter no máximo 32 caracteres.
TemplateGroupId	String	Não	—	O ID do grupo de modelos de transcodificação. Se especificado, a transcodificação é acionada automaticamente após o upload. MUST especificar este ou `WorkflowId` se a transcodificação for necessária. Encontre-o no console navegando até Configuration Management > Media Processing > Transcoding Template Groups.
WorkflowId	String	Não	—	O ID do workflow. Se especificado, o workflow é acionado automaticamente após o upload. Se tanto `WorkflowId` quanto `TemplateGroupId` forem especificados, `WorkflowId` tem precedência.
StorageLocation	String	Não	—	O endereço de armazenamento. Se não especificado, o arquivo é enviado para o endereço de armazenamento padrão. Encontre-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. NEVER passe este parâmetro a menos que o sistema de múltiplos aplicativos esteja ativado.

Gerenciamento de ativos de mídia

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

@id="p-x-22" Consultar informações de ativos de mídia: @id="code-getvideoin-01" GetVideoInfo (consulta um único vídeo), @id="code-getvideoin-02" GetVideoInfos (consulta vários vídeos em lote), @id="code-searchmedi-01" SearchMedia (busca ativos de mídia)

@id="p-x-23" Atualizar informações de ativos de mídia: @id="code-updatevide-01" UpdateVideoInfo (atualiza informações do vídeo), @id="code-updateimag-01" UpdateImageInfos (atualiza informações da imagem)

@id="p-x-24" Excluir ativos de mídia: @id="code-deletevide-01" DeleteVideo (exclui vídeos), @id="code-deleteatta-01" DeleteAttachedMedia (exclui ativos de mídia auxiliares)

@id="p-x-25" Operações em lote: @id="code-batchgetme-01" BatchGetMediaInfos (recupera informações de até 20 ativos de mídia por vez)

O ID de mídia (VideoId, MediaId ou ImageId) é o identificador exclusivo para gerenciar 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. MUST persistir o ID retornado imediatamente após o upload — esta é a única maneira de referenciar o ativo em operações subsequentes.

Processamento de mídia

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

@id="p-x-26" Transcodificação: Configure parâmetros de transcodificação usando um grupo de modelos de transcodificação (@id="code-addtransco-01" AddTranscodeTemplateGroup). É possível acionar a transcodificação automática especificando um TemplateGroupId durante o upload ou utilizando 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).

@id="p-x-27" Captura de snapshot: Configure parâmetros de snapshot usando um modelo de snapshot (@id="code-addvodtemp-01" AddVodTemplate com TemplateType definido como @id="code-snapshot-01" Snapshot). Suporta vários tipos, incluindo snapshots padrão e sprites.

@id="p-x-28" Revisão inteligente: Configure itens de revisão (como pornografia, violência e conteúdo político) e escopos (imagem da capa, conteúdo do vídeo e texto do título) usando um modelo de IA (@id="code-addaitempl-01" AddAITemplate com TemplateType definido como @id="code-aimediaaud-01" AIMediaAudit). A revisão é acionada automaticamente após o upload do vídeo. Também é possível chamar @id="code-createaudi-01" CreateAudit para revisão manual.

@id="p-x-29" Capa inteligente: Gere automaticamente uma capa de vídeo usando um modelo de IA (com TemplateType definido como @id="code-aiimage-01" 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). MUST ser exatamente um destes dois valores.
TemplateConfig	String	Sim	—	A configuração do modelo como uma string JSON. MUST incluir `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.

@id="p-x-30" Obter URLs de reprodução: Chame @id="code-getplayinf-01" 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.

@id="p-x-31" Obter credencial de reprodução: Chame @id="code-getvideopl-01" GetVideoPlayAuth para obter uma credencial de reprodução para reprodução criptografada (criptografia padrão HLS ou criptografia proprietária do Alibaba Cloud).

@id="p-x-32" Gerenciamento de nome de domínio: Chame @id="code-addvoddoma-01" AddVodDomain para adicionar um nome de domínio acelerado, @id="code-batchstart-01" BatchStartVodDomain para ativá-lo e @id="code-batchstopv-01" 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`. MUST ser um domínio que você possui e verificou.
Sources	String	Sim	—	A lista de endereços de origem como um array JSON. Formato: `[{"content":"1.1.1.1","type":"ipaddr","priority":"20","port":80}]`. MUST incluir pelo menos um endereço de origem.
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.	MUST verificar sua configuração de AccessKey executando `aliyun configure` ou verifique o status do AccessKey no console do RAM.
SignatureDoesNotMatch	A assinatura não corresponde ao resultado calculado.	MUST ativar logs de depuração do SDK para solucionar: `export ALIBABA_CLOUD_LOG_LEVEL=debug`. PREFER usar o SDK (que gerencia a assinatura automaticamente) em vez de assinatura manual.
InvalidParameter	O parâmetro é inválido.	MUST verificar se os parâmetros da requisição atendem aos requisitos (tipo, comprimento, campos obrigatórios) consultando a documentação de cada operação de API.
Forbidden.AccessDenied	Permissões insuficientes.	MUST confirmar se o usuário RAM recebeu a permissão `AliyunVODFullAccess`. Verifique executando `aliyun ram ListPoliciesForUser --UserName <user>`.
ServiceUnavailable	O service está temporariamente indisponível.	MUST implementar nova tentativa com backoff exponencial. NEVER tente novamente imediatamente em um loop fechado.
QuotaExceeded.UploadVideo	O número de vídeos enviados excedeu a cota.	MUST verificar a cota de upload da sua conta. Abra um ticket para solicitar aumento de cota, se necessário.
MediaNotFound	O ativo de mídia não existe.	MUST confirmar 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.	MUST chamar `GetVideoInfo` para verificar o status atual antes de tentar novamente. O ativo pode estar em revisão ou ainda sendo transcodificado.

Diretivas de tratamento de erros para agentes de IA:

Nível	Diretiva
MUST	Implemente nova tentativa com backoff exponencial para erros `ServiceUnavailable`.
MUST	Verifique o status do ativo de mídia com `GetVideoInfo` antes de tentar novamente após erros `InvalidStatus.Media`.
MUST	Valide todos os parâmetros obrigatórios na documentação da API antes de fazer uma chamada.
NEVER	Tente novamente erros `InvalidAccessKeyId.NotFound` ou `Forbidden.AccessDenied` sem corrigir primeiro o problema de credencial ou permissão.
NEVER	Tente novamente erros `QuotaExceeded` em um loop. Verifique a cota e solicite um aumento.
PREFER	Use mensagens de erro descritivas nas respostas do agente em vez de expor códigos de erro brutos aos usuários finais.