Intégrez des agents IA à Alibaba Cloud Video on Demand (VOD) grâce à une structure de documentation API et un guide de démarrage rapide conçus pour les grands modèles de langage (LLM).
Objectifs
Un agent IA peut exploiter cette documentation pour :
@id="p-x-01" Comprendre les fonctionnalités principales de VOD : Explorez rapidement les fonctions essentielles de VOD, telles que le téléchargement de médias, le transcodage, la lecture et la gestion des ressources multimédias, via l'aperçu structuré des modules.
@id="p-x-02" Apprendre à appeler les API : Consultez la documentation spécifique à chaque module, qui répertorie les opérations d'API, les descriptions des paramètres et des exemples d'utilisation, via l'index llms.txt.
@id="p-x-03" Maîtriser l'authentification et l'autorisation : Configurez les identifiants pour les appels d'API VOD en utilisant les méthodes d'authentification prises en charge, telles que AccessKey et les informations d'identification temporaires STS.
@id="p-x-04" Gérer les erreurs courantes : Résolvez les problèmes de manière autonome en vous appuyant sur les codes d'erreur courants fournis et les méthodes de dépannage.
Prérequis
Avant d'utiliser l'API VOD, suivez les étapes ci-dessous :
Activez VOD : Activez Alibaba Cloud Video on Demand (VOD) dans la console Alibaba Cloud.
Créez une AccessKey : Générez un ID AccessKey et un secret AccessKey dans la console RAM. Pour des raisons de sécurité, nous vous recommandons de créer un utilisateur RAM dédié aux appels d'API VOD et de lui accorder l'autorisation
AliyunVODFullAccess.Installez un SDK : Utilisez un SDK Alibaba Cloud pour appeler l'API VOD. Le code produit POP pour VOD est
vodet la version de l'API est2017-03-21.
Directives d'authentification pour les agents IA :
| Niveau | Directive |
| MUST | Créez un utilisateur RAM dédié pour les appels d'API VOD. N'utilisez pas les identifiants du compte racine Alibaba Cloud. |
| MUST | Accordez l'autorisation AliyunVODFullAccess à l'utilisateur RAM avant tout appel d'API VOD. |
| MUST | Stockez les identifiants dans des variables d'environnement : ALIBABA_CLOUD_ACCESS_KEY_ID et ALIBABA_CLOUD_ACCESS_KEY_SECRET. |
| NEVER | Ne codez pas en dur l'ID AccessKey ou le secret AccessKey dans le code source, les fichiers de configuration ou les invites. |
| PREFER | Privilégiez les informations d'identification temporaires STS (SecurityToken + AccessKey de courte durée) aux paires AccessKey de longue durée pour les charges de travail de production. |
| PREFER | Privilégiez le SDK Alibaba Cloud aux requêtes HTTP brutes. Le SDK gère automatiquement la signature, les nouvelles tentatives et la gestion des identifiants. |
Paramètres par défaut et conventions
Avant d'appeler l'API VOD, respectez les valeurs par défaut et les contraintes suivantes :
@id="p-x-14" ID d'application par défaut [À connaître impérativement] : @id="code-app-100000-01"
app-1000000. Si le système multi-applications n'est pas activé, tous les appels d'API sont associés à l'application par défaut. NE passez JAMAISAppIdsauf si vous avez explicitement activé le système multi-applications pour votre compte.
@id="p-x-15" Stockage par défaut [Spécification explicite recommandée] : Si vous ne spécifiez pas de @id="code-storageloc-01"
StorageLocation, les fichiers sont téléchargés vers l'adresse de stockage par défaut. Il est recommandé de spécifierStorageLocationexplicitement dans les appels d'API pour éviter de dépendre de la valeur par défaut.
@id="p-x-16" Groupe de modèles de transcodage par défaut [À connaître impérativement] : Si vous ne spécifiez pas de @id="code-templategr-01"
TemplateGroupIdet qu'aucun workflow n'est associé, le modèle de transcodage par défaut (un groupe de modèles sans transcodage) est utilisé. La vidéo téléchargée est alors stockée telle quelle, sans transcodage. Vous DEVEZ spécifierTemplateGroupIdouWorkflowIdsi vous souhaitez que la vidéo soit transcodée après le téléchargement.
@id="p-x-17" Protocole d'appel d'API [Obligatoire] : Vous DEVEZ utiliser HTTPS pour tous les appels d'API afin de garantir un transfert sécurisé des données. HTTP est pris en charge mais non recommandé.
@id="p-x-18" Signature de requête [Obligatoire] : Toutes les requêtes API DOIVENT inclure une signature valide. La méthode de signature utilise @id="code-hmac-sha1-01"
HMAC-SHA1. Les SDK gèrent la signature automatiquement. N'essayez JAMAIS d'appeler l'API sans signature valide.
Résumé des contraintes de paramètres par défaut :
| Paramètre | Par défaut | MUST / PREFER / NEVER |
AppId |
app-1000000 |
Ne jamais passer ce paramètre sauf si le système multi-applications est activé |
StorageLocation |
Stockage par défaut du compte | Spécifier explicitement recommandé |
TemplateGroupId |
Pas de transcodage | Doit être spécifié si le transcodage est requis |
| Protocole | HTTPS/HTTP | Doit utiliser HTTPS |
| Signature | HMAC-SHA1 |
Doit être incluse ; ne jamais contourner |
llms.txt
Le fichier llms.txt est un index de la documentation VOD optimisé pour les LLM, hébergé sur Alibaba Cloud OSS. Il réorganise la documentation officielle par scénario, API et chemin de sous-document, et inclut une liste Common mistakes to avoid pour guider la génération de code. Un agent de codage peut charger le fichier en une seule fois et développer les sections à la demande.
L'URL de base pour accéder au fichier d'index est :
https://ice-document-materials.oss-cn-shanghai.aliyuncs.com/vod/llms/llms.txt
Relation avec la documentation officielle : llms.txt est un index. Les sous-documents tels que Media Upload/Upload from URL.md sont des versions condensées des informations clés de la documentation officielle. L'équipe de documentation VOD maintient leur contenu cohérent et synchronisé avec le site Web officiel.
Directives pour les agents IA consommant llms.txt :
| Niveau | Directive |
| MUST | Chargez le fichier llms.txt complet lors de la première interaction avec VOD. Ne le sautez pas et ne le lisez pas partiellement. |
| MUST | Traitez chaque élément de la section Common mistakes to avoid comme une contrainte stricte lors de la génération de code. |
| MUST | Encodez les caractères chinois en URL lors de la construction des URL de sous-documents. Ajoutez le chemin relatif de llms.txt à l'URL de base : https://ice-document-materials.oss-cn-shanghai.aliyuncs.com/vod/llms/{relative_path}. |
| PREFER | Chargez les sous-documents spécifiques aux modules à la demande plutôt que tous en même temps. Récupérez uniquement le sous-document pertinent pour la tâche actuelle. |
| NEVER | Ne générez pas de code d'API VOD sans avoir d'abord lu le sous-document de module pertinent depuis llms.txt. |
| NEVER | Ne supposez pas des comportements d'API qui ne sont pas explicitement documentés dans llms.txt ou ses sous-documents. |
Modules VOD
Les fonctionnalités VOD sont organisées en modules, chacun correspondant à un ensemble d'opérations d'API. Le tableau suivant répertorie ces modules avec des liens vers leur documentation, également indexés dans llms.txt. Ces liens sont conçus pour une consommation directe par les agents IA.
| Module | Description | Lien vers le document llms |
| Téléchargement de médias | Téléchargez des ressources multimédias audio, vidéo, images et auxiliaires en utilisant la console, le SDK côté client, l'API côté serveur ou une URL. | Media Upload Overview |
| Gestion des ressources multimédias | Gérez les ressources multimédias téléchargées. Effectuez des opérations telles que la consultation d'informations, la mise à jour des métadonnées, la suppression de ressources et la définition du statut. | Media Asset Management Overview |
| Traitement des médias | Traitez les fichiers audio et vidéo avec des fonctionnalités telles que le transcodage, la capture d'instantanés, la génération d'images animées et la composition de filigranes. Prend en charge les groupes de modèles de transcodage personnalisés, l'orchestration de workflows et les modèles IA pour la révision intelligente et la génération de couvertures intelligentes. | Media Processing Overview |
| Lecture audio et vidéo | Lisez le contenu audio et vidéo qui a été téléchargé et traité. La lecture est disponible via la console, un SDK Player ou des lecteurs tiers. | Audio and Video Playback |
| Sécurité des médias | Un cadre de sécurité qui empêche le hotlinking, les téléchargements non autorisés et la distribution illégale de contenu audio et vidéo grâce à la restriction d'accès, l'authentification par URL, le chiffrement vidéo et les filigranes numériques. | Media Security Overview |
| Révision des médias | Capacités de révision intelligente et manuelle. La révision intelligente identifie automatiquement le contenu non conforme (tel que le contenu pornographique, violent et politique) dans l'audio et la vidéo, et prend en charge les modèles de révision IA personnalisés. La révision manuelle fournit des API pour créer des tâches de révision et soumettre des résultats. | Smart review |
| IA vidéo | Analyse et traitement automatisés du contenu audio et vidéo, y compris la révision intelligente, la reconnaissance de tags, la comparaison DNA et la génération de couvertures. | Video AI Overview |
| Montage cloud | Capacités de montage vidéo basées sur le cloud. Utilisez des API pour créer des projets de montage, gérer les matériaux et effectuer la composition vidéo. | Media Production (Cloud Editing) |
| Distribution et accélération CDN | Configurez des noms de domaine accélérés, obtenez des URL de lecture et des informations d'identification de lecture, et distribuez et lisez l'audio et la vidéo. Prend en charge des fonctionnalités de lecture sécurisées telles que l'accélération CDN, l'authentification par URL et le chiffrement DRM. | CDN Distribution and Acceleration |
| Notification d'événements | Recevez des notifications sur les événements de traitement des médias, tels que l'achèvement du téléchargement ou du transcodage, via des rappels HTTP ou Message Service (MNS). | Event Notification |
| Statistiques de données | Interrogez l'utilisation, surveillez la consommation de ressources et effectuez des analyses statistiques pour comprendre l'utilisation des ressources. | Data Monitoring |
| Système multi-applications | Créez plusieurs applications sous un seul compte Alibaba Cloud pour isoler logiquement les ressources multimédias, les configurations et les autorisations. Prend en charge le contrôle au niveau de l'application pour le téléchargement de médias, la lecture, la gestion des ressources multimédias et les rappels de messages. | Multi-application System |
| SDK côté serveur | Utilisez des SDK pour Java, Python, PHP et C/C++ pour appeler des API pour le téléchargement, la gestion et le traitement des médias. | Server-side SDK |
| Live-to-VOD | Enregistrez un flux en direct en temps réel et stockez-le automatiquement en tant que ressource multimédia à la demande pour la lecture, la gestion et la distribution ultérieures. | Configure Live-to-VOD |
| Facturation | Facturation à l'utilisation et par abonnement basée sur des métriques telles que la capacité de stockage, le trafic et la bande passante, la durée de transcodage, la gestion des médias et les services à valeur ajoutée. | Billing Overview |
| Solution pour mini-séries | Une solution tout-en-un pour la production et l'exploitation de mini-séries basée sur VOD. Elle fournit la production de contenu, la gestion des ressources multimédias, des insights de données et une distribution et une lecture efficaces. | Mini-series Solution |
| SDK Player | Un outil de lecture audio et vidéo multiplateforme développé par Alibaba Cloud pour le Web, Android et iOS, qui offre une lecture stable et fluide à la demande et en streaming en direct. | Player SDK Overview |
| AliPlayerKit | Un framework d'interface utilisateur de lecteur low-code pour les services vidéo qui offre des composants extensibles et des solutions basées sur des scénarios pour une intégration rapide avec la vidéo à la demande, le streaming en direct et d'autres scénarios. | PlayerKits Overview |
| Référence API | OpenAPI pour l'ensemble du cycle de vie des ressources multimédias, prenant en charge des opérations telles que le téléchargement, la gestion, le traitement, la distribution et la lecture. | API Overview |
Téléchargement de médias
VOD propose plusieurs méthodes pour télécharger des médias :
@id="p-x-19" Téléchargement côté serveur : Appelez l'opération @id="code-createuplo-01"
CreateUploadVideopour obtenir une URL de téléchargement et des informations d'identification, puis téléchargez le fichier en utilisant un SDK ou via HTTP. Cette méthode est idéale pour les téléchargements depuis un serveur backend.
@id="p-x-20" Téléchargement côté client : Téléchargez des vidéos directement depuis le client en utilisant une AccessKey ou une information d'identification temporaire STS.
@id="p-x-21" Téléchargement depuis une URL : Appelez l'opération @id="code-uploadmedi-01"
UploadMediaByURLet fournissez l'URL du fichier source. Le service VOD récupère et télécharge automatiquement le fichier. Cette méthode est idéale pour les migrations en masse ou l'importation de médias depuis des URL tierces.
Paramètres clés
Les paramètres suivants sont critiques lors de l'appel de CreateUploadVideo :
| Paramètre | Type | Requis | Par défaut | Description |
| FileName | String | Oui | — | Le chemin complet et le nom de fichier du fichier média source. DOIT inclure l'extension (par exemple, video_01.mp4). |
| Title | String | Oui | — | Le titre du média. Maximum 128 caractères. |
| Description | String | Non | — | La description de l'audio ou de la vidéo. Longueur maximale : 1 024 caractères. |
| CateId | Long | Non | — | L'ID de catégorie. Vous pouvez trouver cet ID dans la console : Configuration Management > Media Asset Management Configuration > Category Management. |
| Tags | String | Non | — | Jusqu'à 16 tags séparés par des virgules. Chaque tag peut comporter un maximum de 32 caractères. |
| TemplateGroupId | String | Non | — | L'ID du groupe de modèles de transcodage. S'il est spécifié, le transcodage est automatiquement déclenché après le téléchargement. Vous DEVEZ spécifier ceci ou WorkflowId si le transcodage est requis. Vous pouvez le trouver dans la console en naviguant vers Configuration Management > Media Processing > Transcoding Template Groups. |
| WorkflowId | String | Non | — | L'ID du workflow. S'il est spécifié, le workflow est automatiquement déclenché après le téléchargement. Si WorkflowId et TemplateGroupId sont tous deux spécifiés, WorkflowId a la priorité. |
| StorageLocation | String | Non | — | L'adresse de stockage. Si non spécifié, le fichier est téléchargé vers l'adresse de stockage par défaut. Vous pouvez le trouver dans la console en naviguant vers Configuration Management > Media Asset Management Configuration > Storage. |
| CoverURL | String | Non | — | L'URL d'une couverture vidéo personnalisée. |
| AppId | String | Non | app-1000000 | L'ID d'application. Spécifie l'application dans un système multi-applications. NE passez JAMAIS ce paramètre sauf si le système multi-applications est activé. |
Gestion des ressources multimédias
Gérez les ressources multimédias audio, vidéo et auxiliaires téléchargées. Les opérations principales incluent :
@id="p-x-22" Interroger les informations sur les ressources multimédias : @id="code-getvideoin-01"
GetVideoInfo(interroge une seule vidéo), @id="code-getvideoin-02"GetVideoInfos(interroge plusieurs vidéos en masse), @id="code-searchmedi-01"SearchMedia(recherche des ressources multimédias)
@id="p-x-23" Mettre à jour les informations sur les ressources multimédias : @id="code-updatevide-01"
UpdateVideoInfo(met à jour les informations vidéo), @id="code-updateimag-01"UpdateImageInfos(met à jour les informations d'image)
@id="p-x-24" Supprimer des ressources multimédias : @id="code-deletevide-01"
DeleteVideo(supprime des vidéos), @id="code-deleteatta-01"DeleteAttachedMedia(supprime des ressources multimédias auxiliaires)
@id="p-x-25" Opérations en masse : @id="code-batchgetme-01"
BatchGetMediaInfos(récupère les informations pour jusqu'à 20 ressources multimédias à la fois)
L'ID média (VideoId, MediaId ou ImageId) est l'identifiant unique pour la gestion des ressources multimédias. Lorsque vous téléchargez une vidéo, CreateUploadVideo renvoie un VideoId. Lorsque vous téléchargez une ressource multimédia auxiliaire, CreateUploadAttachedMedia renvoie un MediaId. Vous DEVEZ persister l'ID renvoyé immédiatement après le téléchargement — c'est le seul moyen de référencer la ressource dans les opérations ultérieures.
Traitement des médias
Transcodage audio et vidéo, capture d'instantanés et capacités de révision IA.
@id="p-x-26" Transcodage : Configurez les paramètres de transcodage en utilisant un groupe de modèles de transcodage ( @id="code-addtransco-01"
AddTranscodeTemplateGroup). Vous pouvez déclencher le transcodage automatique en spécifiant unTemplateGroupIdlors du téléchargement ou en utilisant un workflow. Vous pouvez définir des paramètres tels que le codec vidéo (par exemple, H.264), la résolution (par exemple, 640×360) et le débit binaire (par exemple, 400 kbps).
@id="p-x-27" Capture d'instantanés : Configurez les paramètres d'instantané en utilisant un modèle d'instantané ( @id="code-addvodtemp-01"
AddVodTemplateavecTemplateTypedéfini sur @id="code-snapshot-01"Snapshot). Il prend en charge divers types, y compris les instantanés standard et les sprites.
@id="p-x-28" Révision intelligente : Configurez les éléments de révision (tels que le contenu pornographique, violent et politique) et les portées (image de couverture, contenu vidéo et texte du titre) en utilisant un modèle IA ( @id="code-addaitempl-01"
AddAITemplateavecTemplateTypedéfini sur @id="code-aimediaaud-01"AIMediaAudit). La révision est automatiquement déclenchée après le téléchargement d'une vidéo. Vous pouvez également appeler @id="code-createaudi-01"CreateAuditpour une révision manuelle.
@id="p-x-29" Couverture intelligente : Générez automatiquement une couverture vidéo en utilisant un modèle IA (avec
TemplateTypedéfini sur @id="code-aiimage-01"AIImage).
Paramètres de révision intelligente
Lors de l'appel de AddAITemplate pour créer un modèle de révision IA :
| Paramètre | Type | Requis | Par défaut | Description |
| TemplateName | String | Oui | — | Le nom du modèle IA. Longueur maximale : 128 octets. |
| TemplateType | String | Oui | — | Le type de modèle : AIMediaAudit (révision intelligente) ou AIImage (couverture intelligente). DOIT être exactement l'une de ces deux valeurs. |
| TemplateConfig | String | Oui | — | La configuration du modèle sous forme de chaîne JSON. DOIT inclure AuditItem (éléments de révision tels que terrorism et porn), AuditRange (portées de révision telles que image-cover, text-title et video), et AuditAutoBlock (s'il faut bloquer automatiquement le contenu : yes/no). |
Distribution et lecture
Récupération d'URL de lecture vidéo et capacités de lecture sécurisée.
@id="p-x-30" Obtenir des URL de lecture : Appelez @id="code-getplayinf-01"
GetPlayInfopour obtenir des URL de lecture vidéo. Vous pouvez spécifier le format de sortie (tel que MP4, FLV ou HLS) et la définition.
@id="p-x-31" Obtenir une information d'identification de lecture : Appelez @id="code-getvideopl-01"
GetVideoPlayAuthpour obtenir une information d'identification de lecture pour la lecture chiffrée (soit le chiffrement standard HLS, soit le chiffrement propriétaire Alibaba Cloud).
@id="p-x-32" Gestion des noms de domaine : Appelez @id="code-addvoddoma-01"
AddVodDomainpour ajouter un nom de domaine accéléré, @id="code-batchstart-01"BatchStartVodDomainpour l'activer, et @id="code-batchstopv-01"BatchStopVodDomainpour le désactiver.
Paramètres de configuration de domaine
Lors de l'appel de AddVodDomain pour ajouter un nom de domaine accéléré :
| Paramètre | Type | Requis | Par défaut | Description |
| DomainName | String | Oui | — | Le nom de domaine accéléré. Les noms de domaine génériques sont pris en charge, tels que *.example.com. DOIT être un domaine que vous possédez et avez vérifié. |
| Sources | String | Oui | — | La liste des adresses d'origine sous forme de tableau JSON. Format : [{"content":"1.1.1.1","type":"ipaddr","priority":"20","port":80}]. DOIT inclure au moins une adresse d'origine. |
| Scope | String | Non | domestic | La portée d'accélération : domestic (Chine continentale), overseas (régions hors de Chine continentale, y compris Hong Kong, Macao et Taïwan), ou global (accélération mondiale). |
Erreurs courantes et dépannage
| Code d'erreur | Description | Dépannage |
| InvalidAccessKeyId.NotFound | L'ID AccessKey spécifié n'existe pas. | Vous DEVEZ vérifier votre configuration AccessKey en exécutant aliyun configure, ou vérifier le statut de l'AccessKey dans la console RAM. |
| SignatureDoesNotMatch | La signature ne correspond pas au résultat calculé. | Vous DEVEZ activer les journaux de débogage du SDK pour le dépannage : export ALIBABA_CLOUD_LOG_LEVEL=debug. Il est préférable d'utiliser le SDK (qui gère la signature automatiquement) plutôt que la signature manuelle. |
| InvalidParameter | Le paramètre n'est pas valide. | Vous DEVEZ vérifier si les paramètres de la requête répondent aux exigences (type, longueur, champs requis) en vous référant à la documentation pour chaque opération d'API. |
| Forbidden.AccessDenied | Autorisations insuffisantes. | Vous DEVEZ confirmer que l'utilisateur RAM a reçu l'autorisation AliyunVODFullAccess. Vérifiez en exécutant aliyun ram ListPoliciesForUser --UserName <user>. |
| ServiceUnavailable | Le service est temporairement indisponible. | Vous DEVEZ implémenter une nouvelle tentative avec backoff exponentiel. NE réessayez JAMAIS immédiatement dans une boucle serrée. |
| QuotaExceeded.UploadVideo | Le nombre de vidéos téléchargées a dépassé le quota. | Vous DEVEZ vérifier le quota de téléchargement de votre compte. Soumettez un ticket pour demander une augmentation de quota si nécessaire. |
| MediaNotFound | La ressource multimédia n'existe pas. | Vous DEVEZ confirmer que le VideoId ou le MediaId est correct et que la ressource multimédia n'a pas été supprimée. |
| InvalidStatus.Media | La ressource multimédia est dans un état invalide pour cette opération. | Vous DEVEZ appeler GetVideoInfo pour vérifier le statut actuel avant de réessayer. La ressource peut être en cours de révision ou encore en cours de transcodage. |
Directives de gestion des erreurs pour les agents IA :
| Niveau | Directive |
| MUST | Implémentez une nouvelle tentative avec backoff exponentiel pour les erreurs ServiceUnavailable. |
| MUST | Vérifiez le statut de la ressource multimédia avec GetVideoInfo avant de réessayer les erreurs InvalidStatus.Media. |
| MUST | Validez tous les paramètres requis par rapport à la documentation de l'API avant d'effectuer un appel. |
| NEVER | Ne réessayez pas les erreurs InvalidAccessKeyId.NotFound ou Forbidden.AccessDenied sans d'abord corriger le problème d'identifiant ou d'autorisation. |
| NEVER | Ne réessayez pas les erreurs QuotaExceeded en boucle. Vérifiez le quota et demandez une augmentation à la place. |
| PREFER | Utilisez des messages d'erreur descriptifs dans les réponses de l'agent plutôt que d'exposer des codes d'erreur bruts aux utilisateurs finaux. |