Connectez-vous avec OAuth 2.1 ou avec une clé API. Découvrez des modèles, créez avec des médias de référence, assemblez des montages multicouches et intégrez la vidéo, les images et l’audio finalisés à votre conversation.
V4V MCP permet à un assistant IA de découvrir des modèles de génération, de travailler avec des médias de référence, de créer des images, des vidéos, de l’audio et des réponses de chat, puis de récupérer les résultats. Il utilise le même compte, les mêmes crédits et le même historique de génération que l’API V4V.
URL du serveur :https://v4v.ai/api/mcp
Transport : HTTP diffusable en flux
Authentification : connexion OAuth 2.1 sur les déploiements activés, ou clé API dans les clients qui prennent en charge les en-têtes de requête personnalisés. Les deux utilisent votre compte V4V existant et vos crédits.
Utilisez le domaine de votre déploiement à la place de v4v.ai lorsque vous testez un autre environnement. Le serveur est déjà hébergé ; vous n’avez pas besoin d’exécuter un processus local.
Se connecter avec OAuth
Choose this option in ChatGPT, Claude, or a supported editor or CLI. You do not need to create an API key. Add the remote server URL, select OAuth / Sign in, and complete the V4V permission screen. See OAuth authorization and the client-specific steps below.
Se connecter avec une clé API
Ouvrez votre profil V4V et créez une clé dans API Keys.
Enregistrez le secret API dans les paramètres sécurisés de votre client MCP.
Ajoutez le serveur avec x-api-key: YOUR_V4V_API_KEY ou Authorization: Bearer YOUR_V4V_API_KEY.
Connectez-vous et commencez avec get_balance ou list_models.
Envoyez un seul en-tête d'authentification. Si les deux sont envoyés, ils doivent contenir la même clé ; des identifiants contradictoires ou mal formés renvoient HTTP 401. La valeur de x-api-key est la clé elle-même, sans préfixe Bearer . Les deux formats d'en-tête de clé API utilisent les mêmes autorisations, crédits, limites de débit et révocation de clé.
Les clients avec clé API continuent d'utiliser les mêmes en-têtes et autorisations. Les clients OAuth se connectent à leur compte V4V existant via le navigateur. Ne collez jamais une clé ou un token dans une conversation avec un assistant et ne le validez jamais dans un dépôt.
Add https://v4v.ai/api/mcp as a remote Streamable HTTP server in your assistant.
Choose OAuth / Sign in. If asked for an OAuth client, select Register automatically (dynamic client registration, or DCR). Leave Client ID and Client Secret empty.
Your assistant opens V4V in your browser. Sign in to the V4V account whose credits and library you want to use.
Review the assistant and all three required permissions: view your account and media; upload, estimate costs, edit and share; generate media and transcribe using credits. All three are selected and locked. Choose Accept all permissions, or Cancel to decline.
Return to your assistant, finish connecting if prompted, and ask it to check your balance. Tool permissions and confirmations inside the assistant are managed separately by that client.
L'assistant découvre les points de terminaison OAuth à partir du serveur et utilise PKCE pour finaliser la connexion. Ne créez pas de clé API et ne collez pas de jeton bearer pour ce flux. L'exemple OAuth en haut de cette page contient uniquement le transport HTTP et l'URL du serveur ; chaque client a son propre format de configuration.
La connexion ne consomme pas de crédits. Les générations utilisent votre solde V4V existant. Les tokens d'accès durent au maximum une heure et se renouvellent automatiquement lorsque le client le prend en charge. La connexion expire après 30 jours ; reconnectez-vous à ce moment-là ou après avoir révoqué l'accès. Gérez et déconnectez les sessions dans Profil V4V → Connexions d'assistant. Les tâches déjà soumises continuent de s'exécuter après la déconnexion.
Si OAuth n'est pas disponible sur votre déploiement, demandez à son opérateur d'activer les connexions d'assistant, ou utilisez une clé API dans un client compatible.
OAuth doit d'abord être activé sur le déploiement V4V. Les autorisations de compte et d'espace de travail dans ChatGPT déterminent si une connexion MCP personnalisée est disponible.
Ouvrez ChatGPT Plugins → Personal, choisissez Add (ou +), puis Add custom MCP server (le libellé peut varier selon le compte).
Saisissez V4V et l'URL du serveur https://v4v.ai/api/mcp.
Choisissez OAuth et l'enregistrement dynamique du client (DCR). Laissez Client ID et Client Secret vides ; V4V enregistre automatiquement un client PKCE public. Cette version prend en charge DCR, pas CIMD.
Connectez-vous avec vos identifiants V4V existants.
Sur l'écran d'autorisations de V4V, vérifiez le compte et l'hôte de rappel. Les trois autorisations sont obligatoires : lecture du compte, modification/téléversement et génération avec crédits. Les trois cases à cocher sont sélectionnées et verrouillées. Choisissez Accept all permissions pour vous connecter, ou Cancel pour refuser ; le consentement partiel n'est pas pris en charge.
Revenez dans ChatGPT et installez le plugin si cela vous est demandé. Dans les plugins Personal, ouvrez le menu à trois points de V4V et choisissez Manage.
Ouvrez la ligne Permission. Pour des appels d'outil sans approbation, choisissez Allow all tools. Les générations utilisent toujours vos crédits V4V, alors demandez une estimation avant de commencer.
Démarrez une nouvelle conversation, choisissez + → Plugins → V4V (ou mentionnez-le avec @), puis demandez Check my V4V balance.
Le guide de captures d'écran ChatGPT vous accompagne à travers les huit écrans. Son étape de détails de connexion comporte des boutons de copie pour le nom du plugin, la description et l'URL du serveur du déploiement actuel, ainsi qu'un téléchargement facultatif de l'icône V4V.
Exemple :
Créez trois concepts de vidéos produit verticales 9:16 à partir de ce lien produit. Affichez d'abord les concepts et les crédits estimés. Attendez mon approbation avant de lancer la génération.
L'assistant utilise les outils existants de découverte, estimate_generation et generate_studio_variants. Les estimations n'effectuent pas de rendu et ne réservent pas de crédits, mais peuvent importer des médias pour validation et nécessitent donc l'autorisation de modification. Les outils payants appliquent côté serveur l'autorisation de génération. L'autorisation concerne l'accès au compte, pas l'approbation d'un brief créatif individuel : examinez quand même les concepts demandés et le budget avant d'autoriser un rendu. Les contrôles de lot max_credits et d'idempotence restent en vigueur.
Les tokens d'accès durent au maximum une heure. Les tokens d'actualisation sont renouvelés à chaque utilisation, et la connexion expire après 30 jours. Reconnectez-vous lorsqu'elle expire ou lorsque des autorisations supplémentaires sont nécessaires. Dans Profil V4V → Connexions d'assistant, consultez l'utilisation, déconnectez l'assistant ou affichez son secret de signature de webhook pour votre récepteur. Ne collez pas le secret de signature dans le chat.
La déconnexion bloque les nouvelles requêtes d'outil, le renouvellement des tokens et les liens de téléversement inutilisés. Les tâches déjà soumises continuent selon les règles existantes de file d'attente et de crédits ; la déconnexion ne les annule pas et ne les rembourse pas. Les liens médias signés précédemment émis conservent leur expiration normale.
Les téléversements de fichiers depuis l'environnement d'exécution de ChatGPT dépendent du réseau et de l'accès aux pièces jointes de cet environnement. Le lien de téléversement navigateur à portée limitée reste disponible comme solution de secours. La seule connectivité MCP ne garantit pas le transfert automatique des pièces jointes.
Ouvrez Add to Claude.
Le formulaire s'ouvre avec le nom V4V et l'URL du serveur de production préremplis. Pour le dev ou
un autre déploiement, utilisez la page de connexion,
qui renseigne l'URL de ce déploiement. Si le fait de vous connecter à Claude vide le formulaire,
rouvrez le lien après vous être connecté.
Vérifiez le nom et l'URL préremplis, puis choisissez Continue.
Claude vérifie automatiquement le serveur. Conservez les paramètres détectés Sign in now et Register automatically, puis choisissez Add ; aucun autre paramètre n'a besoin d'être modifié. Laissez Client ID et Client Secret vides, sans clé API ni en-têtes de requête.
Sur la page du connecteur, choisissez Connect et connectez-vous à V4V.
Vérifiez votre compte et les trois autorisations obligatoires, puis choisissez Accept all permissions. La connexion ne consomme pas de crédits.
Sous Tool permissions → Read-only tools, ouvrez Custom à côté du nom du groupe et choisissez Always allow.
Faites défiler jusqu'à Write/delete tools et choisissez également Custom → Always allow pour ce groupe. Activez V4V dans une conversation et demandez Check my V4V balance. Les générations utilisent vos crédits V4V ; demandez d'abord une estimation.
Les autorisations d'outil de Claude sont distinctes de l'autorisation d'accès au compte V4V. Les
menus de groupe vous permettent d'autoriser les outils sans modifier chacun d'eux individuellement.
Vous pouvez réviser ces choix dans les paramètres du connecteur de Claude.
Les
callbacks hébergés de Claude sur claude.ai et claude.com sont pris en charge sans configuration
d'environnement supplémentaire. Utilisez Register automatically ; l'identité client publiée
(CIMD) de Claude n'est pas implémentée dans cette version. Les connexions existantes par clé API
continuent de fonctionner comme décrit ci-dessous.
Si les paramètres de transport sont affichés, utilisez Streamable HTTP. L'ajout d'un connecteur et
l'autorisation de son accès au compte sont des étapes distinctes lorsque Claude les présente de cette manière.
Alternative avec clé API : créez votre clé API V4V
Ouvrez votre profil V4V, accédez à API Keys et créez une clé. Gardez-la prête pour l'en-tête du connecteur ci-dessous.
2. Ajouter le connecteur
Open Add to Claude, or open Customize → Connectors → Add → Custom web connector.
Set Name to V4V.
Set MCP server URL to https://v4v.ai/api/mcp.
Under Authentication, select No sign-in.
Click Add header and enter:
Paramètre d'en-tête
Valeur
Name
x-api-key
Value
Votre clé API V4V, exactement telle que copiée
Cliquez sur Add / Connect et attendez la fin de la connexion.
Utilisez uniquement la clé dans x-api-key, sans préfixe Bearer . No sign-in ignore OAuth ; l'en-tête authentifie néanmoins chaque requête vers V4V. Laissez OAuth Client ID et Client Secret vides.
3. Autoriser les outils
Ouvrez le Gestionnaire de connecteurs de Claude.
Sélectionnez le nouveau connecteur V4V.
Ouvrez Tool permissions et autorisez tous les outils V4V.
Vérifiez que create_upload_link, get_upload, get_model et generate_lab sont disponibles et activés.
Après que V4V a ajouté ou mis à jour des outils, actualisez les outils du connecteur ou reconnectez-le avant de démarrer une nouvelle conversation.
4. Autoriser les téléversements automatiques de fichiers
Ouvrez Settings → Capabilities.
Activez Code execution and file creation et Allow network egress s'ils sont désactivés.
Dans Domain allowlist, ajoutez ces entrées :
text
v4v.ai
*.v4v.ai
*.v4vcdn.space
Conservez à la fois le domaine racine et l'entrée générique afin que le domaine de l'application et ses sous-domaines soient couverts. Saisissez uniquement les noms de domaine, sans https:// ni /api/mcp, puis enregistrez les modifications. Si votre espace de travail gère ce paramètre de manière centralisée, demandez à son administrateur de mettre à jour la liste d'autorisation.
Cela permet à l'environnement d'exécution de Claude d'envoyer la pièce jointe d'origine directement à V4V en utilisant l'autorisation de téléversement de courte durée émise par MCP. Sans ce paramètre, le connecteur peut fonctionner alors que les téléversements de fichiers échouent avec host_not_allowed.
Test en dev : utilisez https://h4000.kitpes.com/api/mcp comme URL du connecteur et ajoutez h4000.kitpes.com séparément à la liste d'autorisation des domaines. Les entrées de domaine V4V ne couvrent pas le nom d'hôte dev.
5. Démarrer une nouvelle conversation
Activez le connecteur V4V dans un nouveau chat, joignez votre image et demandez :
Agrandissez cette image en 4× avec V4V. Téléversez automatiquement le fichier d'origine, puis utilisez son ID de fichier avec le modèle Topaz.
Claude doit obtenir une autorisation de téléversement via MCP, transférer le fichier depuis son environnement d'exécution sans copier de base64 dans le chat, puis soumettre la génération. Vous n'avez pas besoin de téléverser à nouveau le fichier dans une page de navigateur distincte lorsque l'accès réseau est autorisé.
Démarrez le serveur, examinez l'invite d'approbation de confiance et finalisez la connexion à V4V lorsque VS Code ouvre votre navigateur. Activez les outils que vous souhaitez utiliser dans le chat de l'agent.
Alternative avec clé API
Pour le chat de l'éditeur, ajoutez ce qui suit à .vscode/mcp.json. VS Code demande la clé et masque la saisie. Conservez l'espace réservé dans le fichier.
Démarrez le serveur depuis la configuration MCP et activez ses outils dans votre session de chat. Vérifiez l'appel d'outil de génération avant de l'autoriser à consommer des crédits.
Pour les autres environnements d'agent VS Code, suivez la référence de configuration MCP actuelle pour l'emplacement de configuration pris en charge par cet environnement.
Enregistrez le serveur distant sans en-tête d'authentification :
bash
claude mcp add --transport http v4v https://v4v.ai/api/mcp
Démarrez Claude Code, exécutez /mcp, choisissez V4V et authentifiez-vous. Finalisez l'écran d'autorisations V4V dans votre navigateur, puis revenez à l'interface en ligne de commande.
Alternative avec clé API
Définissez V4V_API_KEY de manière sécurisée dans l'environnement de votre shell, puis enregistrez le serveur distant :
Utilisez /mcp dans Claude Code pour inspecter la connexion. L'enregistrement stocke l'en-tête configuré dans la configuration locale de votre client ; protégez ce fichier et gardez-le hors du contrôle de version. Consultez le guide MCP de Claude Code pour la portée de la configuration et la gestion des clés.
Sur la page de connexion, choisissez la connexion V4V ou la clé API, puis
cliquez sur Install in Cursor. Vérifiez l'installation dans Cursor avant de l'accepter.
OAuth ouvre une connexion dans le navigateur ; la configuration par clé API installe un espace réservé que vous
remplacez localement dans .cursor/mcp.json. Aucune clé réelle n'est intégrée dans l'URL d'installation.
Les versions desktop actuelles utilisent un URI de rappel HTTP loopback ; les clients cloud utilisent l'URI https://www.cursor.com/agents/mcp/oauth/callback
exacte approuvée.
Ajoutez le serveur distant avec gemini mcp add --transport http v4v https://v4v.ai/api/mcp.
Exécutez /mcp auth v4v dans Gemini CLI pour OAuth. Pour une configuration par clé API, définissez
V4V_API_KEY de manière sécurisée et ajoutez le serveur avec
gemini mcp add --transport http --header "x-api-key: $V4V_API_KEY" v4v https://v4v.ai/api/mcp.
La CLI enregistre l'en-tête configuré ; gardez ses paramètres privés.
Ajoutez un serveur distant sous mcp.v4v dans opencode.json avec type: "remote",
url: "https://v4v.ai/api/mcp" et enabled: true. Exécutez
opencode mcp auth v4v pour OAuth. La page de connexion
fournit le JSON complet ainsi qu'une alternative par clé API via variable d'environnement.
Choisissez un serveur distant / Streamable HTTP et renseignez :
Paramètre
Valeur
Nom
v4v
URL
https://v4v.ai/api/mcp
Authentification (choisissez-en une)
x-api-key: YOUR_V4V_API_KEY ou Authorization: Bearer YOUR_V4V_API_KEY
Les formats de configuration varient selon le client. Configurez l'en-tête dans les paramètres secrets du client, pas dans un message de chat. Les anciens clients limités à SSE ne sont pas pris en charge. Les clients OAuth natifs pris en charge utilisent des callbacks HTTP sur localhost ou 127.0.0.1 avec un port local explicite. L'inscription et l'autorisation lient exactement l'URL complète de callback. Les callbacks hébergés pour Claude, ChatGPT, Cursor et VS Code sont approuvés ; les autres clients hébergés nécessitent des URL exactes dans MCP_OAUTH_REDIRECT_URIS.
Pour un film complet ou une réinterprétation créative d'un enregistrement, réglez les choix manquants importants avant l'assemblage ou tout travail payant : objectif, public, média source, format, durée cible, traitement visuel, sous-titres, voix, musique et langues de sortie. get_started accepte des choix de request_kind (production, creative_edit, targeted_edit) et des choix creative_brief confirmés ; il renvoie videoBrief.productionQuestions et readyForProduction. Réutilisez les réponses fournies et les délégations explicites. Une coupe précise ou une correction n'a besoin que des détails pertinents pour ce changement. L'approbation automatique des dépenses ne fournit pas de réponses créatives. Ces règles sont partagées par V4V MCP et Open Video Kit 0.3.6.
Vous pouvez commencer par une demande comme :
Trouvez un modèle pour une vidéo verticale de huit secondes de ma tasse en céramique. Utilisez cette image du produit : https://example.com/mug.jpg. Montrez-moi un concept et les éléments requis avant de générer.
Si aucun modèle n'est nommé, l'assistant doit utiliser Google/Gemini Omni Flash v1.2 par défaut (video.gemini_omni_flash-1-2), inspecter son schéma actuel et sa disponibilité avec get_model, vérifier le solde, et préparer les entrées. Une fois que vous demandez la génération, il soumet une tâche et vérifie le résultat finalisé. Cette règle figure en premier dans les instructions d'initialisation MCP et est répétée dans les descriptions de list_models, get_model et generate_lab. La découverte des modèles vidéo renvoie default_video_model ; le modèle sélectionné expose default_for_unspecified_video: true. Les choix explicites de modèle ou de workflow Studio/en lot sont prioritaires.
Pour les demandes vidéo ordinaires sans modèle explicite, privilégiez generate_lab avec video.gemini_omni_flash-1-2. L'assistant ne doit pas demander à l'utilisateur de choisir un modèle simplement parce qu'il n'a pas été précisé. Les choix explicites de modèle et les Flux de travail Studio/en lot explicitement demandés sont prioritaires. get_model reste requis avant de sélectionner les entrées et les paramètres ; si le modèle préféré est désactivé, indisponible ou inadapté, expliquez la limitation et posez la question d'une alternative au lieu de dépenser discrètement des crédits ailleurs. Le routage du fournisseur est configuré par V4V, pas comme paramètre de génération. Utilisez generate_studio pour un Flux de travail Studio explicitement demandé ; la découverte d'images, d'audio, de traduction et de chat reste inchangée.
Le prompt video_brief aide à transformer un objectif, un public et un format en plan de tournage. La ressource v4v://guide explique à votre assistant le Flux de travail de génération.
Découvrir les modèles activés ; filtrage possible par image, vidéo, audio ou chat
Non
get_model
Lire les entrées, options et limites d'un modèle ; model: "studio" fonctionne aussi
Non
describe_studio
Découvrir les styles Studio actuels, durées, formats, qualité, voix et limites des médias
Non
list_products
Trouver les produits possédés ; réutiliser leurs ID comme input.product_id Studio
Non
list_avatars
Trouver les avatars publics possédés et actifs ; réutiliser les ID comme input.avatar_id Studio
Non
estimate_generation
Valider et chiffrer une demande LAB/Studio sans rendu ni réservation de crédits
Non
get_balance
Vérifier les crédits disponibles du compte
Non
get_usage
Trouver les tâches de génération récentes
Non
get_file
Inspecter un fichier de référence possédé
Non
import_media
Enregistrer une URL de média publique dans votre bibliothèque
Non
create_upload_link
Émettre une requête d'upload HTTP à portée limitée ; lien navigateur disponible en solution de secours
Non
get_upload
Récupérer le statut d'upload et l'ID du fichier
Non
upload_media
Upload programmatique d'octets inline ; évitez les gros base64 dans le texte du modèle
Non
generate_lab
Créer avec un modèle spécifique
Oui — consomme des crédits
generate_studio
Créer une vidéo à partir d'un produit ou d'un brief créatif
Oui — consomme des crédits
get_task
Vérifier le statut, l'ID du projet, les ID stables des médias et les liens signés renouvelables
Non
refresh_task_results
Renouveler les URL signées des résultats sans rendu
Non
list_projects
Trouver les projets Studio, Flux de travail, LAB et API en file d'attente possédés par titre, source ou dossier
Non
rename_project
Renommer un projet possédé ou le futur projet d'une tâche en file d'attente
Non
list_project_folders
Lister les mêmes dossiers que ceux affichés dans l'espace de travail Projets
Non
create_project_folder
Créer un dossier d'espace de travail
Non
rename_project_folder
Renommer un dossier tout en conservant ses projets
Non
move_project
Assigner un dossier possédé, ou utiliser folder_id: null pour retirer du dossier
Non
generate_studio_variants
Mettre en file d'attente 2 à 3 variantes créatives en utilisant le budget et les contrôles en lot existants
Oui — au démarrage des variantes
promote_to_example
Exemples : administrateurs uniquement ; copier/mettre à jour l'exemple d'un projet possédé avec visibilité explicite
Non
La découverte Studio lit le workflow sélectionné et les styles actifs de ce déploiement ; elle ne code pas en dur sept noms de style et ne suppose pas que chaque workflow a une limite de dix secondes. get_model avec model: "studio" est un alias de describe_studio. Les instructions essentielles figurent aussi dans les descriptions des outils pour les clients qui ne peuvent pas lire v4v://guide.
Les schémas de modèles proviennent du même catalogue que celui utilisé par V4V LAB. Demandez get_model avant de choisir les paramètres ; les références, durées et formats requis varient selon le modèle.
Appelez list_products ou list_avatars (offset et limit facultatifs, maximum 100). Les avatars prennent par défaut source: "all" ; des filtres owned et public sont disponibles. Le next_offset renvoyé est null sur la dernière page. Les ID d'avatars publics incluent public: ; conservez ce préfixe. Chaque enregistrement inclut photo_count ; Studio utilise la photo principale de l'avatar. Seuls les enregistrements de votre propre bibliothèque privée sont renvoyés.
Utilisez input.product_id et input.avatar_id dans generate_studio ou estimate_generation. parameters.avatar accepte aussi l'ID d'avatar renvoyé et continue de prendre en charge un ID de fichier ou une URL d'image publique. Choisissez soit input.avatar_id, soit parameters.avatar. Les photos de la bibliothèque sont résolues directement sans être téléchargées puis réimportées. Les entrées explicites de nom, description ou image produit remplacent les valeurs par défaut du produit enregistré. Les ID/noms de style actifs utilisent leurs instructions créatives enregistrées ; les ID/noms de style inconnus ou inactifs renvoient INVALID_PARAMETER avec allowed_values. Placez les instructions créatives libres dans input.prompt et choisissez un preset actif (ou omettez le style pour la valeur par défaut découverte).
Envoyez cela à estimate_generation. Il renvoie credits_estimated, réserve zéro crédit et ne crée ni tâche ni rendu. Les devis Studio ignorent l'enregistrement de caractères du fournisseur, y compris lorsqu'un avatar est sélectionné. Les URL de médias publics peuvent être importées pour validation. Les devis peuvent changer selon les entrées/tarifs ; les devis de chat décrivent une réservation initiale, pas les coûts finaux de jetons ni un plafond de dépense. Pour lancer le rendu, supprimez source et soumettez les mêmes entrées à generate_studio avec un nouveau idempotency_key.
generate_studio_variants accepte name, les input/parameters partagés, un max_credits requis, idempotency_key, et variants contenant deux ou trois objets avec des remplacements facultatifs d'entrée/de paramètre. Par exemple : variants: [{parameters: {style: "UGC"}}, {parameters: {style: "Product Review"}}]. Chaque variante est une tentative payante distincte. C'est un wrapper sur la file d'attente par lots Studio existante : il renvoie batch_id, utilise get_studio_batch pour les résultats et les mêmes contrôles de pause/budget/reprise. Il ne contourne jamais les limites de capacité.
Utilisez rename_project avec le project_id renvoyé par list_projects, la génération ou get_task, et project_name (après trim, 1 à 200 caractères). Le renommage met aussi à jour le titre de la tâche et l'historique LAB, y compris lorsqu'un projet est encore en attente de création. Il ne modifie pas le hash de requête d'idempotence d'origine.
Seuls les administrateurs des exemples découvrent promote_to_example. Il prend un project_id possédé avec un résultat enregistré, un active requis, et surfaces: ["dashboard", "studio", "landing"] (choisissez n'importe quel sous-ensemble). studio correspond à l'indicateur de visibilité ProVid/Studio existant. active: false masque l'exemple partout, quelle que soit la sélection de surface. Le résultat inclut visible_on afin que la visibilité effective soit claire. La publication nécessite une demande de l'utilisateur ; cet outil ne consomme pas de crédits de génération.
Utilisez list_projects pour trouver des projets existants sans générer. Il inclut Studio, les Flux de travail, l'historique LAB et les projets API en file d'attente. Filtres facultatifs : source: "all" | "studio" | "workflow" | "lab", q pour une recherche littérale par titre, et folder_id pour un dossier possédé ou "unfiled". Omettez le filtre de dossier pour voir tous les projets. list_projects et list_project_folders acceptent tous deux offset (par défaut 0) et limit (1–100, par défaut 50) ; suivez next_offset jusqu'à ce qu'il soit null.
Par exemple, pour organiser les résultats de campagne approuvés :
Appelez list_projects avec {"q":"approved"} et sélectionnez les projets visés.
Appelez list_project_folders ; réutilisez le dossier visé ou appelez create_project_folder avec {"name":"Summer campaign"}.
Appelez move_project pour chaque project_id sélectionné avec le folder_id renvoyé.
Appelez list_projects avec ce folder_id pour vérifier le contenu du dossier.
Utilisez move_project avec folder_id: null pour retirer un projet de son dossier. rename_project_folder accepte folder_id et name. Les noms de dossier doivent contenir 1 à 80 caractères après trim et être uniques dans votre compte ; un doublon renvoie FOLDER_NAME_CONFLICT. Après une réponse de création incertaine, listez les dossiers avant de réessayer. Les déplacements et renommages peuvent être répétés sans risque et ne consomment pas de crédits, ne génèrent pas de médias et ne modifient pas les résultats. Les projets en file d'attente conservent leurs noms et dossiers lorsque le worker les crée. Ces opérations ne peuvent pas accéder aux projets ou dossiers d'un autre compte.
Le média de référence peut être une URL publique ou un ID de fichier V4V possédé. Un champ nommé image_url accepte aussi un ID de fichier ; utilisez le schéma du modèle pour choisir le champ d'entrée exact.
Uploads automatiques à partir de fichiers joints et locaux
L'assistant peut téléverser lui-même le fichier d'origine lorsque son environnement d'exécution peut atteindre ce déploiement V4V. Vous n'avez pas besoin de copier une clé API dans le chat ni de sélectionner à nouveau le même fichier.
Appelez create_upload_link. Malgré son nom, l'outil renvoie aussi upload_request : une URL POST, un en-tête x-upload-token à portée limitée et le nom de champ multipart file.
Depuis l'outil d'exécution de l'assistant, envoyez les octets réels du fichier local à cette URL avec multipart/form-data. Laissez le client HTTP définir la boundary et désactivez les redirections. Ne convertissez pas l'image et n'affichez pas de base64 dans la conversation.
Lisez file_id dans la réponse et confirmez avec get_upload à l'aide de upload_id.
Découvrez le schéma d'entrée du modèle, passez cet ID dans son champ média (par exemple Topaz image_url), puis soumettez la génération demandée.
Pour plusieurs références, répétez l'opération avec un slot d'upload distinct pour chaque fichier requis.
Le jeton d'upload expire après 15 minutes, accepte un fichier jusqu'à 20 MiB sous réserve de la limite du serveur, et ne peut ni lire votre bibliothèque ni consommer des crédits de génération. Les octets réels transitent via HTTP ; MCP fournit l'autorisation à portée limitée et contrôle la génération.
Pour un environnement d'exécution où le résultat de l'outil est disponible sous slot, le transfert binaire est :
La connectivité MCP et l'accès réseau du bac à sable sont distincts. host_not_allowed signifie que le bac à sable ne peut pas envoyer l'upload binaire même si les appels MCP fonctionnent.
Suivez Claude Web → Allow automatic file uploads ci-dessus : ouvrez Settings → Capabilities → Domain allowlist, ajoutez v4v.ai, *.v4v.ai et *.v4vcdn.space, puis activez le trafic réseau sortant. Pour le dev, ajoutez h4000.kitpes.com séparément. Les restrictions gérées au niveau de l'espace de travail peuvent exiger qu'un administrateur effectue la modification.
L'assistant doit s'arrêter après la première requête refusée et expliquer le paramètre nécessaire, sans réessayer pendant des minutes ni convertir le fichier en texte de modèle. Démarrez une nouvelle conversation après la mise à jour des autorisations et actualisez les outils du connecteur après une mise à jour du serveur.
Solution de secours facultative via navigateur
Si vous choisissez l'upload manuel, ouvrez upload_url, sélectionnez le fichier d'origine, puis indiquez à l'assistant quand il est prêt. Il récupère l'ID du fichier avec get_upload. Il s'agit d'une solution de secours, pas d'une étape obligatoire lorsque l'upload HTTP automatique fonctionne.
upload_media reste disponible pour le transfert programmatique d'octets ou de très petites charges utiles jusqu'à 8 Kio encodés. Sa limite serveur de 5 Mio décodés n'est pas un budget texte pratique pour un modèle de langage. Ne redimensionnez/réencodez pas une source uniquement pour la transférer, n'affichez pas de longues chaînes base64 et ne bouclez pas sur des segments encodés.
Upload REST pour les fichiers plus volumineux
Si l'environnement d'exécution de l'assistant dispose d'un accès réseau sortant et d'une clé API configurée de manière sécurisée, il peut téléverser via POST /api/v1/files en utilisant le champ multipart file. La clé du connecteur MCP n'est pas automatiquement disponible pour les outils shell.
bash
# V4V_BASE_URL is this deployment's origin, e.g. https://h4000.kitpes.com
curl "$V4V_BASE_URL/api/v1/files" \
-H "Authorization: Bearer $V4V_API_KEY" \
-F "file=@/path/to/photo.png"
Le id de la réponse est l'ID de fichier à utiliser dans les entrées de génération. Laissez curl définir la boundary multipart. Conservez les identifiants dans la configuration sécurisée du client, pas dans la conversation.
URL publiques
Utilisez import_media pour enregistrer une URL de média accessible afin de la réutiliser, ou fournissez l'URL directement au modèle. Ne passez pas un chemin local ni une URL de bac à sable comme URL publique.
Exemple d'arguments pour generate_lab (remplacez l'ID d'exemple par l'ID renvoyé par votre upload) :
{
"project_name": "Ceramic mug — launch video",
"input": {
"product_name": "Ceramic mug",
"product_description": "A handmade mug with a matte glaze",
"product_images": [
"https://example.com/mug.jpg"
],
"prompt": "A calm product reveal in soft morning light"
},
"parameters": {
"duration": 8,
"aspect_ratio": "9:16"
},
"idempotency_key": "mug-launch-video-001"
}
Utilisez une nouvelle idempotency_key pour chaque génération intentionnelle. Réutilisez la même clé et les mêmes arguments lorsque vous relancez une requête après une interruption réseau. La réutilisation d'une clé avec des entrées modifiées renvoie un conflit.
Les outils de génération renvoient immédiatement task_id et project_id. Si la limite de concurrence du compte est atteinte, la même tâche attend avec les détails credits_reserved: 0, credits_estimated et queue contenant la limite configurée, un intervalle de vérification de cinq secondes et estimated_start_at: null. Les délais d'achèvement ne peuvent pas être prédits. Ne soumettez pas une autre génération pour contourner l'attente. Le worker réserve les crédits lorsqu'un créneau se libère ; si le solde est alors insuffisant, la tâche échoue à l'étape d'admission et envoie son webhook configuré. Ils ne gardent pas la conversation ouverte jusqu'à la fin du rendu.
json
{
"task_id": "task_6aa962444bd1dd7ab65bc6b6"
}
Transmettez cet ID à get_task. Attendez au moins cinq secondes entre deux vérifications. Une tâche peut être queued, processing, completed, failed ou cancelled.
Lorsque le statut est completed, results contient du texte intégré pour le chat ou des URL de téléchargement signées pour les médias. L'assistant peut partager ces URL avec vous sans nécessiter de cookies de navigateur. Utilisez get_task ou refresh_task_results si un lien expire. Les résultats média incluent des asset_id/file_id stables ; transmettez file_id directement dans les futurs champs média de génération au lieu de copier une URL expirante. Le contrat de réutilisation le lendemain repose sur l'ID stable plus un lien renouvelable tant que le fichier existe et que l'accès reste autorisé ; l'URL elle-même peut expirer. Les liens restent signés ; ne supprimez jamais la signature et ne dérivez jamais un chemin CDN non signé. Arrêtez l'interrogation sur tout statut terminal. La vérification d'une tâche ne lance jamais une deuxième génération. Les tâches en échec signalent error.stage, brief_completed, retryable et les retry_after_seconds suggérés lorsqu'ils sont connus, avec le credits_used réel. Un brief terminé peut conserver sa facturation même si la génération vidéo échoue. retryable: true décrit une erreur potentiellement transitoire ; cela n'autorise pas une autre tentative payante. Si la tâche renvoie GENERATION_SERVICE_ERROR, le service du modèle a signalé une défaillance interne. Ne supposez pas que la résolution source ou le facteur d'échelle en sont la cause, et ne changez pas automatiquement de modèle ni ne créez de nouvelles tentatives payantes. Expliquez l'échec et attendez une demande explicite de nouvelle tentative.
Les générations du Laboratoire apparaissent aussi dans Laboratoire → Old runs et Projects. L'utilisation de votre clé API apparaît dans votre profil.
generate_lab et generate_studio acceptent callback_url à l'aide de l'envoi de webhook REST existant et de la vérification de signature. V4V publie task.completed ou task.failed avec des event_id stables, des données de tâche, des crédits et des résultats. Vérifiez X-V4V-Timestamp et X-V4V-Signature à l'aide du secret de signature du webhook affiché lors de la création de la clé API, et dédupliquez par event_id. Ne collez pas de secrets dans le chat. Les nouvelles tentatives de livraison ne créent pas de nouvelles générations. Les URL de callback utilisent la même validation de réseau externe que REST. Les soumissions en lot et de variantes acceptent aussi callback_url pour les événements de lot signés ; voir le flux de travail de supervision ci-dessous. Voir REST webhook verification.
La génération utilise vos crédits V4V habituels. Pour les tâches ordinaires du Laboratoire/Studio, le coût estimé est réservé lorsque de la capacité est disponible ; les tâches excédentaires attendent sans réservation. Le crédit non utilisé suit les mêmes règles de libération que l'API REST. La consultation des modèles, soldes, tâches et fichiers existants ne consomme pas de crédits de génération.
Chaque outil est limité au propriétaire de la clé configurée. Il est impossible d'accéder aux fichiers et aux tâches d'un autre compte. Révoquez une clé dans votre profil pour désactiver sa connexion MCP. Les annotations d'outil identifient les appels qui créent du travail et consomment des crédits, afin que votre client puisse proposer ses contrôles habituels d'approbation d'outil.
Actualisez ou reconnectez le connecteur MCP afin que le client découvre la liste d'outils mise à jour
HTTP 401
Utilisez une clé valide et non révoquée dans x-api-key, ou Authorization avec le préfixe Bearer ; supprimez les en-têtes en conflit
HTTP 403
Pour un client basé sur navigateur, son Origin doit être autorisé par le déploiement
HTTP 405 dans un navigateur
Le point de terminaison accepte les requêtes MCP POST ; utilisez un client MCP
HTTP 406
Le client doit accepter à la fois application/json et text/event-stream
HTTP 429 / RATE_LIMIT_EXCEEDED
Lisez error.retryable et retry_after_seconds dans le JSON ; les limites de fenêtre de requête incluent aussi scope et limit. Attendez le délai et réutilisez la même requête/clé d'idempotence pour une requête rejetée. Une tâche déjà en échec reste terminale. Les limites du compte et de la clé sont partagées avec REST.
Le résultat de l'outil contient isError: true
Lisez l'erreur structurée, corrigez les entrées et évitez les nouvelles tentatives de génération à l'aveugle
Entrée de modèle rejetée
Actualisez get_model et utilisez son schéma actuel
La tâche reste en file d'attente ou en cours de traitement
Continuez à vérifier avec un délai ; ne soumettez pas automatiquement une génération de remplacement
Le service utilise le SDK TypeScript MCP officiel et un mode de réponse JSON sans état sur Streamable HTTP. Les outils à attente bornée gardent la requête individuelle ouverte jusqu'à une mise à jour ou un délai d'expiration ; ils n'établissent pas de canal de notification permanent. Le client négocie la version du protocole lorsqu'il se connecte.
Variantes d'image GPT Image 2.5
La découverte des modèles inclut les variantes texte/image Flare et Sunburst, avec les valeurs par défaut Sunburst pour image.text_to_image et ai.image_edit. Elles prennent en charge background, la tarification 1K/2K/4K (6/10/16 crédits), des prompts jusqu'à 20 000 caractères et jusqu'à 16 images d'édition. Voir GPT Image 2.5 settings and API examples pour les ID de variante et les restrictions de format d'image.
Quatre nœuds distincts partagent la même gestion de génération et de résultat dans le Laboratoire, les Flux de travail, l'API et MCP :
ID du catalogue
Modèle
Durée
Résolution
video.kling_v40_ref
Kling 4.0 Reference
3–30 secondes
720p / 1080p
video.kling_v40_key
Kling 4.0 Keyframe
3–30 secondes
720p / 1080p
video.kling_v40_flash_ref
Kling 4.0 Flash Reference
3–20 secondes
720p
video.kling_v40_flash_key
Kling 4.0 Flash Keyframe
3–20 secondes
720p
Tous acceptent un prompt obligatoire (jusqu'à 8000 caractères), un duration entier, resolution et aspectRatio (auto, 16:9, 9:16, 1:1, 21:9 ; Flash Keyframe exclut auto). Tous peuvent générer à partir du texte seul. Les entrées de référence sont facultatives.
Les modèles Reference acceptent referenceImageUrls (jusqu'à 10), referenceVideoUrls (jusqu'à 5), elements (jusqu'à 7, au plus 3 avec vidéo) et keepOriginalSound. Un élément nommé possède name, soit imageUrls (2 à 4 images), soit videoUrl (un clip de personnage de 3 à 8 s), tag facultatif, description (100 caractères) et voiceUrl de personnage. Flash accepte aussi type d'élément (image ou video). Standard Reference accepte en plus voices : jusqu'à 3 objets avec name et audioUrl. Flash associe plutôt les voix aux éléments de personnage.
Il peut y avoir au maximum 15 images, vidéos de référence, éléments et voix autonomes combinés ; les vidéos de référence plus les éléments vidéo ne peuvent pas dépasser 5. Chaque vidéo de référence doit durer 2 à 30 s (2 à 20 s pour Flash), et leur durée cumulée, éléments vidéo inclus, est d'au maximum 30 s (20 s pour Flash). Les noms doivent être uniques sans tenir compte de la casse, composés de 1 à 20 caractères chinois, lettres, chiffres ou underscores ; les noms de référence intégrés sont réservés. Mentionnez les références fournies comme @image_1, @video_1 ou leur @name déclaré. Les mentions non déclarées sont rejetées.
Les modèles Keyframe utilisent firstFrameUrl. Standard Keyframe accepte aussi des keyframeUrls ordonnés (jusqu'à 8 images intermédiaires) et lastFrameUrl ; ceux-ci nécessitent une première image. Le nombre total d'images ne peut pas dépasser min(duration + 1, 10). Flash Keyframe ne prend en charge que la première image. Mentionnez les images comme @first_frame, @keyframe_1, @last_frame. La sortie basée sur les images suit le format d'image de la première image.
Tous les champs média, y compris les éléments et voix imbriqués, acceptent des URL ou des ID de fichier V4V possédés dans l'API/MCP. Les ports image/vidéo des Flux de travail utilisent reference_image_urls / reference_video_urls, ou first_frame_url / keyframe_urls / last_frame_url ; les prompts utilisent script-in. Standard Reference accepte aussi l'audio sur voice_audio_urls, déclaré comme @voice_1, @voice_2, etc. Les deux sorties des Flux de travail sont des video / clips standard, adaptés au moteur de rendu et à l'éditeur existants. L'API/MCP renvoie la tâche asynchrone habituelle et des fichiers de résultat téléchargeables ; interrogez la tâche ou utilisez les webhooks de fin.
Taux de base approuvés en crédits V4V par seconde, avant les remplacements administrateur ou les ajustements existants de flux de travail. Ces taux sont utilisés directement, sans conversion USD ni majoration retail :
Modèle
720p, sans vidéo
720p, avec vidéo
1080p, sans vidéo
1080p, avec vidéo
Standard Reference
28.5
17
42.5
25.5
Standard Keyframe
28.5
indisponible
42.5
indisponible
Flash Reference
17
11.3
indisponible
indisponible
Flash Keyframe
17
indisponible
indisponible
indisponible
Exemples pour une sortie de 5 secondes :
Modèle
5 s sans vidéo source
5 s avec jusqu'à 5 s de vidéo source
Standard Reference, 720p
142.5 crédits
170 crédits
Standard Reference, 1080p
212.5 crédits
255 crédits
Standard Keyframe, 720p / 1080p
142.5 / 212.5 crédits
indisponible
Flash Reference, 720p
85 crédits
113 crédits
Flash Keyframe, 720p
85 crédits
indisponible
Sans entrée vidéo, les secondes facturables sont égales aux secondes de sortie. Avec une vidéo de référence ou un élément vidéo, les secondes facturables sont égales à max(total input video seconds, output seconds) + output seconds, au tarif correspondant avec entrée vidéo. Par exemple, une sortie Standard Reference 1080p de 10 s avec 15 s d'entrée représente 25 secondes facturées, soit 637.5 crédits avant ajustements. Les fractions de crédit sont conservées ; la facturation complète est arrondie une seule fois à deux décimales. Si la durée d'entrée est inconnue, la durée d'entrée maximale autorisée par le modèle est utilisée pour une estimation prudente ; le serveur vérifie les durées sources réelles avant facturation. Demandez un devis actuel en utilisant les mêmes entrées que pour la génération. L'administration expose des tarifs distincts résolution/entrée vidéo pour chaque nœud. Les anciens nœuds Kling conservent leurs tarifs et réglages existants.
json
{
"model": "video.kling_v40_key",
"input": {
"prompt": "Move from @first_frame to @keyframe_1 and finish at @last_frame",
"firstFrameUrl": "https://example.com/start.png",
"keyframeUrls": [
"https://example.com/middle.png"
],
"lastFrameUrl": "https://example.com/end.png"
},
"parameters": {
"duration": 5,
"resolution": "1080p",
"aspectRatio": "16:9"
}
}
Utilisez ce corps avec generate_lab dans MCP ou POST /api/v1/lab en HTTP. Pour un devis, ajoutez "source": "lab" et utilisez estimate_generation dans MCP ou POST /api/v1/generation/quote en HTTP. Découvrez toujours d'abord le modèle sélectionné avec get_model ou GET /api/v1/models/{id}. L'autorisation de génération standard, les vérifications de solde, les clés d'idempotence, les callbacks et les remboursements en cas d'échec s'appliquent.
Utilisez list_models avec {"type":"chat"}, puis get_model avec {"model":"chat.gpt_6_astra"} pour inspecter les entrées actuelles, les tarifs par jeton et l'arrondi. Soumettez avec generate_lab :
json
{
"model": "chat.gpt_6_astra",
"input": {
"prompt": "Explain this idea in three sentences."
},
"parameters": {
"reasoningEffort": "low",
"webSearch": false,
"stream": false
},
"idempotency_key": "astra-question-001"
}
Optional input.imageUrls accepts up to 12 public URLs or owned file IDs. Text-only requests use string input upstream; images use the model’s multimodal message array. Optional input.functionTools accepts a JSON string of function definitions; web search must be off when functions are present. Function selection is automatic, and completed task results include function_calls for the caller to handle. The model node does not execute functions. Poll get_task using the returned task ID. Completed results entries have type: "text", text, usage, credits and incomplete instead of a download URL.
Le chat réserve initialement 1 crédit. Le coût final utilise les jetons réels d'entrée, de cache et de sortie, arrondis à l'entier supérieur avec un minimum de 1 crédit. Tout montant au-dessus de la réservation est débité après la réponse ; la réservation initiale n'est pas un plafond de dépense. Les tarifs par jeton sont publiés par get_model. Réutilisez la même clé d'idempotence et les mêmes arguments pour les nouvelles tentatives réseau ; ne soumettez pas automatiquement une autre génération payante après un échec.
Pour le chat et la génération d'images facturés à l'usage, estimate_generation renvoie aussi credits_range.min et credits_range.max en crédits V4V, majoration et ajustements de prix actuels inclus. Présentez cela comme une plage approximative. Ses assumptions décrivent des scénarios d'usage illustratifs ; le coût réel peut sortir de la plage, et is_spending_cap est faux. credits_estimated et initial_reservation_estimated restent l'estimation distincte de la réservation initiale. Cet aperçu ne réserve aucun crédit et ne lance aucune génération.
Omni Flash 1.2 is the default for an unspecified video request; 1.1 remains available by explicit selection. Use get_model for image.text_to_image or ai.image_edit to discover GPT Image 2.6 Flare, Sunburst and Economy variants. Pass parameters.outputFormat and respect allowed_by_variant: Flare/Sunburst text-to-image support PNG/JPEG/WebP/GIF/SVG; their image-to-image variants support PNG/JPEG/WebP; Economy text supports PNG/GIF and Economy image supports PNG. Output downloads preserve GIF frames and SVG vector bytes. SVG conversion usage is included in final billing.
Nano Banana 2.1 (parameters.variant: "nano-banana-v2.1") prend en charge 1K/2K/4K et jusqu'à 10 références. Lisez pricing_by_variant pour son mode de facturation actuel. La génération Google/Vertex règle les jetons réels d'entrée, d'entrée mise en cache, de sortie image, de sortie texte et de réflexion, majoration incluse ; les autres routages utilisent le tarif d'image configuré. Gemini 4 Argon (chat.gemini_4_argon) inclut les jetons de réflexion dans la facturation à l'usage. Utilisez estimate_generation pour afficher des plages approximatives de crédits ; la réservation initiale et la plage sont distinctes de l'usage final et ne sont pas des plafonds de dépense. N'inventez jamais de paramètres de routage et ne modifiez jamais silencieusement les réglages d'administration.
Utilisez generate_studio_bulk lorsque vous voulez des vidéos pour une liste de produits. Il accepte 1 à 300 éléments et renvoie immédiatement un batch_id. Il partage le solde de crédits normal du compte et la file d'attente de génération V4V partagée avec REST et l'application web.
Les entrées et paramètres d'élément remplacent les paramètres partagés ; les valeurs par défaut de Studio complètent le reste. Fournissez des ID de produit que vous possédez, des URL publiques de page produit, ou des détails produit et médias préparés. Utilisez les réglages pris en charge par le modèle Studio actuel du déploiement. Omettez test_count pour traiter toute la liste. Avec test_count: 5, les cinq premiers éléments (ou tous les éléments s'ils sont moins de cinq) s'exécutent avant que le lot soit mis en pause pour révision.
Outil
Usage
Consomme des crédits de génération ?
generate_studio_bulk
Créer un lot de vidéos produit avec un budget de crédits obligatoire
Oui, au démarrage de chaque élément
list_studio_batches
Lister les lots les plus récents du compte
Non
get_studio_batch
Lire la progression paginée, les ID de tâche des éléments, les résultats et un state_token stable
Non
wait_studio_batch
Attendre un changement, une fin, une pause ou une annulation ; 25 secondes par défaut
Non
control_studio_batch
pause, resume, cancel, retry_failed, rework ou restart ; max_credits facultatif augmente le budget cumulé
La reprise et les nouvelles tentatives peuvent consommer des crédits
DIRECTOR_REQUEST_FAILED identifie le rejet de la requête de texte AI Director ; REFERENCE_MEDIA_UNAVAILABLE identifie un problème de lecture de ses fichiers de référence. Expliquez l'étape ayant échoué et indiquez l'ID de tâche ; ne supposez jamais que cela signifie qu'une requête de génération vidéo a échoué et ne créez pas automatiquement une autre tentative payante.
Les URL publiques d’articles eBay prennent en charge une solution de repli d’importation protégée via le navigateur. Si une boutique refuse toujours une importation, envoyez un product_id détenu ou des détails/images de produit préparés. IMPORT_FAILED se produit avant l’admission payante et inclut la raison d’importation connue ; PREPARATION_FAILED identifie un échec de préparation ultérieur. Une tentative échouée reste terminale. Lorsque l’utilisateur demande une nouvelle tentative, appelez control_studio_batch avec action: "retry_failed" et un nouveau idempotency_key ; vous pouvez éventuellement fournir item_indexes indexé à partir de zéro. Pour des entrées corrigées ou une recréation délibérée, utilisez action: "rework" avec items: [{task_id: "task_…", input: {prompt: "New direction"}}] (ou utilisez index: 1 au lieu de task_id). Utilisez action: "restart" uniquement lorsque l’utilisateur redemande tous les éléments, y compris ceux qui ont réussi. Ces trois actions nécessitent une nouvelle clé pour chaque opération intentionnelle ; en cas d’erreurs réseau, rejouez la même clé et les mêmes arguments. resume ne relance pas les tentatives échouées.
Pour recréer uniquement les résultats qui ne vous conviennent pas, sélectionnez leurs items[].task_id actuels et appelez control_studio_batch avec action: "rework", ces ID dans items, et un nouveau idempotency_key. Omettez les modifications d’entrée pour réexécuter le même brief. Les résultats actuels sélectionnés sont effacés immédiatement et le même lot reprend le traitement ; les autres éléments terminés restent inchangés. items[].results décrit toujours la dernière version voulue, tandis que attempts conserve la sortie plus ancienne. Un ID de tâche remplacée obsolète renvoie BATCH_ITEM_VERSION_CHANGED ; relisez le lot avant une nouvelle reprise intentionnelle.
Surveiller un lot dans le connecteur navigateur de Claude
Un webhook envoie une requête HTTP à un véritable récepteur. Il ne donne pas à cette connexion MCP un moyen de redémarrer une conversation Claude dans le navigateur lorsqu’elle est inactive. N’inventez jamais d’URL de rappel et ne promettez pas de futur message de chat une fois la conversation terminée.
Pendant le flux de travail par lot demandé par l’utilisateur, Claude doit surveiller automatiquement :
Conservez le batch_id et le state_token de generate_studio_bulk, generate_studio_variants ou get_studio_batch.
Appelez wait_studio_batch avec batch_id, after_state défini sur ce jeton, et wait_seconds: 25 pour les connecteurs navigateur. La pagination facultative utilise offset et limit (50 par défaut, 100 maximum).
Le serveur répond lors d’un changement significatif du lot, de l’achèvement, d’une pause, d’une annulation ou de l’expiration du délai borné. Les pulsations des workers et les signatures de résultat qui expirent ne modifient pas le jeton. La réponse contient la page de lot mise à jour, changed, timed_out, stop_reason et next_action.
Tant que status vaut running, continuez d’attendre avec le jeton renvoyé sans demander à l’utilisateur de dire « check again ». Signalez les jalons utiles, pas chaque délai d’attente inchangé. Un délai d’attente n’échoue ni n’annule la génération. Ne soumettez pas de lot de remplacement.
Sur completed, signalez les résultats et les échecs. Sur paused, expliquez waiting_reason et attendez la décision de l’utilisateur. Ne reprenez, n’augmentez un budget ou ne relancez jamais automatiquement des tentatives payantes. cancelled met également fin à cette boucle de surveillance.
Cela utilise du long polling côté serveur dans un flux de travail d’outil actif. Si Claude termine son tour, si l’utilisateur ferme la conversation ou si le client impose une limite de durée d’exécution, le lot continue à s’exécuter mais cette connexion ne peut pas garantir un nouveau message de chat. Annuler/se déconnecter d’une attente arrête seulement l’observation, pas le lot. Vérifier ou attendre ne consomme pas de crédits de génération.
wait_seconds accepte 1 à 240 secondes. Claude Code prend en charge la mise en arrière-plan automatique des appels MCP longs dans les versions récentes ; pour une attente de 240 secondes, configurez le timeout de ce serveur à au moins 300000 millisecondes et laissez passer la requête à travers les délais d’expiration du proxy. Les connecteurs navigateur doivent utiliser la valeur par défaut de 25 secondes. Voir Claude Code long tool calls. Ce comportement dépend du client et ne constitue pas une garantie de réveil du navigateur.
Webhooks de lot pour des récepteurs externes
Transmettez callback_url lors de la création d’un lot en masse ou de variantes. Le secret existant de signature de webhook de clé API ainsi que la vérification X-V4V-Timestamp / X-V4V-Signature s’appliquent. La destination de rappel est fixée par la requête de création idempotente ; après des erreurs réseau, rejouez la même URL et les mêmes arguments.
Le worker enregistre des instantanés significatifs et livre batch.updated, batch.completed, batch.paused et batch.cancelled. Les événements incluent des event_id stables, batch_id, batch_revision, observed_at, state_token, le statut, les décomptes et les totaux de crédits. result_lookup pointe vers get_studio_batch pour les fichiers paginés et les détails des tâches ; les charges utiles des webhooks n’intègrent pas d’URL de résultat expirables. Les transitions intermédiaires peuvent être fusionnées entre les cycles du worker.
La livraison utilise une boîte d’envoi durable avec baux et nouvelles tentatives bornées. Une livraison répétée a le même ID d’événement et la même charge utile ; les signatures sont renouvelées à chaque tentative. Les récepteurs doivent dédupliquer et tolérer une livraison dans le désordre, puis récupérer l’état actuel du lot lorsque nécessaire. Les erreurs HTTP permanentes entraînent l’abandon de la livraison ; les échecs transitoires appliquent un backoff. Un récepteur de webhook lent ne bloque pas le worker de génération/admission. Les pauses, les annulations avec travail actif et les redémarrages/reprises demandés ultérieurement continuent de produire des mises à jour. La livraison ne lance jamais une autre tentative payante.
Pour des consultations manuelles occasionnelles du statut, appelez get_studio_batch à au moins cinq secondes d’intervalle ; pour une surveillance active par agent, préférez wait_studio_batch. Les tentatives individuelles utilisent l’outil ordinaire get_task pour les liens de téléchargement signés. Ces outils poursuivent le traitement sur le serveur sans que la conversation ou un onglet de navigateur reste ouvert.
Les files d’attente en masse ne réservent que l’estimation de l’élément admis suivant. max_credits borne les crédits dépensés plus les réservations actives. Un solde ou un budget insuffisant met en pause les nouveaux démarrages ; après la demande de l’utilisateur, appelez control_studio_batch avec action: "resume", en augmentant éventuellement max_credits. Mettre en pause/annuler laisse les tentatives actives se terminer. Les lots annulés ne peuvent pas reprendre, mais peuvent redémarrer explicitement ou retravailler des éléments terminaux une fois le travail admis terminé. Les éléments sélectionnés doivent être terminaux (BATCH_ITEMS_ACTIVE) ; les requêtes fournisseur actives ou incertaines bloquent les nouvelles tentatives (GENERATION_UNRESOLVED). NO_FAILED_ITEMS signifie qu’aucun échec le plus récent ne subsiste. L’historique, les résultats et la dépense cumulée survivent à toutes les opérations ; les comptes et le statut des éléments n’utilisent que les dernières versions voulues. Les nouvelles versions partagent les mêmes files d’attente et la même attribution du Journal des crédits. Les modifications facultatives d’entrées/paramètres à l’échelle de l’opération fusionnent avec la requête précédente, et les surcharges de reprise par élément l’emportent. Une barrière d’échantillon préservée nécessite toujours une reprise explicite ; le redémarrage la supprime. Voir le contrat REST pour les limites de requête/d’historique et des exemples complets. Réutilisez le même idempotency_key et les mêmes arguments après une erreur réseau ; ne créez jamais un autre lot pour contourner l’attente dans la file.
Les requêtes de génération partagent au maximum 10 emplacements actifs entre les comptes et les processus d’application. La génération ordinaire est prioritaire ; le traitement en masse utilise la capacité restante sous des limites globales et par utilisateur définies par l’administrateur. Une réponse fournisseur perdue garde son emplacement occupé pour rapprochement et ne déclenche jamais une requête payante dupliquée automatique. Les événements de crédits API et MCP sont libellés séparément dans les Journaux des crédits de l’administrateur.
Cette version fournit la génération et les téléchargements individuels via API/MCP. Les écrans de lots Studio du plan plus large, l’import CSV, l’approbation des résultats et l’export ZIP restent des travaux futurs. Actualisez la liste d’outils de votre connecteur MCP après le déploiement pour découvrir les nouveaux outils de lot. Voir le contrat REST des lots pour les champs, la sémantique de budget et les erreurs.
L’éditeur sur /video-editor vous permet, à vous et à votre assistant, de travailler sur la même timeline enregistrée à plusieurs pistes. Il prend en charge la vidéo, les images/logos, l’audio source, des pistes musique/voix indépendantes, le texte, les sous-titres synchronisés, le rognage, le fractionnement, la vitesse, le volume, les fondus et les notes de révision des prises. Le navigateur fournit un aperçu interactif et une exportation locale MP4/WebM. Ouvrez Video Editor pour modifier de manière interactive ; les outils et les limites sont décrits ci-dessous.
Commencez par get_editor_guide (également disponible comme ressource v4v://video-editor). Actualisez la liste d’outils du connecteur après le déploiement.
Pour une usine de contenu complète, lisez get_factory_guide / v4v://factory. create_factory_run, list_factory_runs, get_factory_run et submit_factory_stage conservent les neuf rôles avec des reprises d’opération exactes et des révisions d’exécution/projet distinctes. prepare_factory_review renvoie de vraies images capturées, get_factory_frame les relit, et preview_factory_audio renvoie un extrait WAV mesuré. Inspectez chaque image capturée et examinez le mouvement/la parole avant de soumettre un jugement. repair_factory_run autorise au maximum deux corrections ; release_factory_run met en file puis vérifie une exportation complète privée de Bibliothèque, un ZIP modifiable, une couverture et REVIEW.md. Ces outils exigent la propriété du projet ; les écritures nécessitent OAuth lecture + écriture, sans permission de génération ni frais de crédits. La génération de scènes payante reste une opération budgétée distincte. Voir le contrat de l’usine ukrainienne pour les routes HTTP, la récupération et les preuves mesurées versus celles rapportées par le relecteur.
Outil
Usage
get_editor_guide
Contrat de timeline, flux de travail d’édition et exemple de timeline vide
get_motion_guide
API de motion versionnée, schémas réels, exemples natifs/HTML, unités de temps/géométrie et cycle de vie ; aussi v4v://motion-api
get_editor_troubleshooting
Guide de récupération versionné pour les erreurs réelles ; aussi v4v://troubleshooting ; la lecture n’effectue jamais de réparation ni de nouvelle tentative
get_project_transfer_guide
Interopérabilité ZIP locale/V4V, requêtes binaires, permissions et récupération ; aussi v4v://project-transfer
export_editor_bundle
Préparer une requête de téléchargement binaire à portée limitée pour un projet à la révision actuelle ; exécutez-la pour obtenir le ZIP réel
import_editor_bundle
Préparer un téléversement ZIP binaire avec {}, puis récupérer son nouveau projet avec transfer_id ; pas de base64 dans le texte du modèle
get_editor_capabilities
Formats réels, durées d’exécution, opérations locales/partagées et services facultatifs
get_creative_library / search_creative_library
Découvrir le registre créatif partagé installé
get_creative_item
Schéma exact d’un élément, exemple d’origine, chemins d’aperçu, licence et limites
get_style_format_guide
Format de pack communautaire données seules ; même contenu que v4v://style-format
create_style_example
Importer dans le compte un nouvel exemple de style modifiable et son média d’origine ; aucun crédit modèle
apply_style
Prévisualiser avec dry_run=true, puis valider à la même révision ; les verrous et surcharges manuelles restent en place
check_editor_project
Revue structurelle/médias P0/P1 ; inspectez séparément les images réelles et l’audio
list_editor_projects
Trouver les projets de l’éditeur détenus/partagés, filtrer scope, et lire les niveaux d’accès
create_editor_project
Créer un projet vide ou une timeline validée
get_editor_project
Lire la timeline, la révision et les URL de médias renouvelables
update_editor_project
Enregistrer une timeline complète à une révision attendue
edit_editor_project
Appliquer des opérations atomiques de clip/calque/sous-titre à une révision attendue
propose_editor_silence_cuts
Mesurer l’audio source réel et proposer des intervalles de silence avec marge sans modifier ; appliquez explicitement les remove_time_ranges examinés à la même révision pour répercuter sur toutes les pistes
propose_editor_audio_ducking
Mesurer les stems voix/musique réels et l’automatisation proposée ; inspectez le RMS avant/après, puis appliquez explicitement les set_audio_envelope renvoyés à la même révision
get_safe_area_guide
Profils de destination éditoriale versionnés et schéma personnalisé ; aussi v4v://safe-areas
inspect_editor_text
Mesurer le texte natif/motion/HTML enregistré avec les polices intégrées et signaler des constats échantillonnés de débordement, chevauchement et lisibilité
propose_editor_text_fit
Proposer un dimensionnement de police pour le texte statique sans changer les mots, le minutage ou le projet enregistré
propose_editor_scene_layout
Proposer des limites explicites de contenu motion/HTML et un plancher de police à partir du profil de zone sûre enregistré ; examinez puis appliquez les set_scene_layout renvoyés
list_editor_media
Rechercher les médias de Bibliothèque détenus par type et nom
get_editor_media
Inspecter la durée source détenue, les dimensions et l’URL de lecture
preview_editor_project
Renvoyer jusqu’à six images JPEG composites réelles pour inspection visuelle
get_editor_text_styles
Découvrir les préréglages de texte/sous-titres, les contours, le motion et la réaction au son
quote_editor_captions
Citer la transcription de la parole source sans générer
transcribe_editor_media
Démarrer la transcription de la parole ; consomme les crédits normaux du compte
get_editor_captions
Lire la progression de la transcription et les repères temporels source
append_editor_audio
Ajouter des ID de médias audio ordonnés à un calque déverrouillé, avec pauses facultatives
export_editor_project
Mettre en file/récupérer MP4, WebM, MP3 ou MP4 de couverture statique ; renvoyer export_id immédiatement
get_editor_export
Interroger le statut/l’étape et récupérer le média de Bibliothèque terminé avec des liens renouvelés
get_editor_project_sharing
Propriétaire : lister les collaborateurs et renvoyer le lien privé du projet
share_editor_project_with_user
Propriétaire : inviter par e-mail ou modifier l’accès en lecture/écriture, avec notification facultative par e-mail
remove_editor_project_access
Propriétaire : révoquer un collaborateur par ID utilisateur
transfer_editor_project_ownership
Propriétaire : transférer explicitement à un autre compte V4V par e-mail
share_editor_project
Publier un lien public pour la vidéo exportée actuelle, sur demande explicite
API de motion et récupération
À partir de Kit 0.1.31, get_motion_guide et get_editor_troubleshooting acceptent {} et correspondent exactement à leurs ressources JSON. Les deux contiennent version et engineVersion ; découvrez les outils du serveur actuel après le déploiement. Leur portée OAuth V4V est v4v:read. La lecture de ces ressources ne modifie pas, n’effectue pas de rendu, ne relance pas et ne réserve pas de crédits.
Le guide motion contient les schémas réellement enregistrés, des exemples add_clip natifs et HTML, le cycle de vie déterministe de prepare / renderAt / dispose, ainsi que les règles de temps de scène local et de géométrie fractionnaire. Dans un nouveau projet vide, appliquez ses opérations d’exemple à la révision enregistrée et prévisualisez les secondes 1 et 5. Dans les projets existants, adaptez délibérément l’emplacement ainsi que les ID de piste/clip. Seules les scènes JSON enregistrées sont acceptées ; la timeline n’installe pas de HTML ni de scripts arbitraires. Inspectez les images réelles et le motion exporté avant acceptation.
Utilisez le dépannage avec le code d’erreur réel et l’état enregistré. Un CONFLICT signifie recharger et préserver les modifications simultanées ; des médias manquants nécessitent une source réelle autorisée ; des polices manquantes nécessitent une restauration explicite. Inspectez la tentative d’export/plan existante après une réponse inconnue. La lecture d’une procédure de récupération n’autorise jamais un nouvel achat, un contournement des autorisations ni le redémarrage d’une opération annulée.
Propositions mesurées de mise en page et d’audio
Les profils de zone de sécurité sont des guides éditoriaux versionnés, pas des garanties officielles des plateformes. set_safe_area_profile conserve le guide sans modifier les pixels rendus. propose_editor_scene_layout l’utilise pour proposer des motion.layout explicites ; examinez applicable et le rapport, puis appliquez ses opérations retournées via edit_editor_project à la même révision. layout:null annule ce réglage. Modifier le guide plus tard n’ajuste pas automatiquement le contenu. inspect_editor_text échantillonne les glyphes/boîtes DOM réels ; le texte intégré aux médias, le rognage pivoté, le contraste sur des séquences vidéo, le mouvement complet et l’écoute restent à vérifier.
Pour de la musique sous une voix, appelez propose_editor_audio_ducking avec les project_id et revision réels, les voice_clip_ids et music_clip_ids disjoints, ainsi que l’optionnel options. Les valeurs par défaut visent une marge RMS voix/musique de 12 dB, détectent l’activité à −40 dBFS et limitent l’atténuation à 30 dB. Le service mixe les sources sélectionnées avec leurs trims, vitesse, volume et fondus réels ; il remixe et mesure aussi la musique proposée. Inspectez les comparison de référence, les after mesurés, targetMet, les avertissements et les intervalles de phrase, écoutez, puis appliquez explicitement les operations retournés via edit_editor_project à la même révision.
L’automatisation de la musique sélectionnée est remplacée plutôt qu’additionnée ; le gain et les fondus de base restent. Les courbes sont portables en ZIP et suivent leur clip musical. Recalculez après avoir modifié le timing/niveau de la voix, les sources ou le placement de la musique. Jusqu’à 500 clips de voix et 20 clips de musique, 100 MiB par source V4V, 512 MiB au total et 64 clips se croisant par fenêtre d’analyse ; les limites de ressources/de débit s’appliquent également. L’accès en lecture autorise les propositions, tandis que leur application nécessite l’accès en écriture. Ni la mesure ni l’édition locale ne consomment de crédits. Le RMS et l’amplitude détectée ne prouvent pas l’intelligibilité ; de même, les suggestions de coupe silencieuse nécessitent une écoute avant des décalages en cascade sur toutes les pistes.
ZIP portable via V4V MCP
Lisez get_project_transfer_guide / v4v://project-transfer. Les deux hôtes utilisent le même contenu .v4v.zip : un bundle.json versionné et les octets d’origine du assets/<sha256>. Seul le Kit local accepte l’argument directory ; V4V rejette explicitement les chemins du système de fichiers local.
Export : appelez export_editor_bundle avec project_id et le revision actuel, puis exécutez sa download_request en utilisant l’en-tête de portée exact et enregistrez la réponse binaire réelle. L’outil a préparé une requête, il n’a pas encore créé de fichier. Le téléchargement revérifie le compte/la clé/l’OAuth, l’accès au projet/aux médias et la révision. Sa réponse contient X-Content-SHA256 ; comparez les octets téléchargés. Si le projet a changé, relisez sa révision et demandez délibérément un autre export.
Import : appelez import_editor_bundle avec {}, envoyez en POST les octets ZIP d’origine en utilisant le upload_request retourné (application/zip, pas multipart), puis appelez import_editor_bundle avec son transfer_id. Cela crée un nouveau projet, vérifie/sonde les sources et remappe les ID de médias imbriqués. Après un accusé de réception perdu, récupérez le même transfert : un import terminé renvoie le projet existant. Un import interrompu peut récupérer son bail expiré en utilisant les octets d’origine ; un fichier différent nécessite un nouveau transfert. N’inventez jamais de données de fichier et n’imprimez pas de gros base64 dans le contexte du modèle. Les clients sans accès aux fichiers binaires peuvent utiliser Studio Open project ZIP.
Les identifiants de transfert expirent après 15 minutes ; les reçus restent récupérables pendant sept jours. Les jetons doivent être placés dans l’en-tête de requête retourné, pas dans les URL, les timelines ou les messages publics. L’import nécessite OAuth en lecture + écriture ; l’export nécessite un accès en lecture et l’accès au projet actuel. Le ZIP et son contenu décompressé sont limités à 100 MiB ; deux transferts par processus, des corps de requête bornés, des baux et des limites de débit par utilisateur/requête s’appliquent. L’import/export n’effectue ni génération, ni partage public, ni notifications. Les autorisations de partage de compte et les identifiants de modèle ne sont pas transportés dans le ZIP. Rouvrez le projet retourné et inspectez les médias/images réels avant livraison.
Partage privé de projet via MCP
L’assistant peut effectuer un partage privé sans demander à l’utilisateur d’utiliser le navigateur. Si l’e-mail V4V du destinataire ou son niveau d’accès en lecture/écriture manque, demandez-le, puis appelez :
Utilisez notify_by_email: true uniquement lorsque l’utilisateur a demandé une notification par e-mail ; sa valeur par défaut est false. Retournez project_link pour que l’utilisateur l’envoie, et signalez emailNotification avec exactitude : failed signifie que l’accès a été accordé mais que l’e-mail n’a pas été envoyé. Le lien du projet nécessite le compte invité ; les destinataires déconnectés se connectent puis reviennent au même projet. Aucun export vidéo, aucune génération ni aucun crédit de génération ne sont nécessaires.
get_editor_project_sharing répertorie les collaborateurs et leurs userId, e-mail et accès. Modifiez les autorisations avec share_editor_project_with_user ; révoquez un utilisateur listé avec remove_editor_project_access et son user_id. Ne transférez que lorsque l’utilisateur a explicitement demandé un transfert de propriété et fourni l’e-mail du nouveau propriétaire. L’ancien propriétaire perd l’accès ; les autres collaborateurs et les références de source restent inchangés. Tous les appels de gestion imposent la propriété du projet ; les mutations OAuth nécessitent en plus v4v:write.
share_editor_project reste une action différente : il publie la vidéo exportée finale sur une page de partage publique. Ne l’utilisez pas pour les invitations privées de collaborateurs. Actualisez/reconnectez le connecteur MCP après le déploiement pour découvrir les nouveaux outils et instructions.
Les ID de projet de l’éditeur sont distincts des ID de projet de génération Studio/Lab. Utilisez list_editor_projects, pas list_projects, pour les découvrir. La génération reste disponible via les outils existants de découverte de modèles, d’estimation et de generate_lab. Le file_id des médias terminés peut être utilisé directement comme assetId de timeline. La reconnaissance vocale est également détectable comme type: "subtitle" ; préférez ai.gemini_3_5_transcribe (Gemini 3.5 Transcribe). Les résultats de tâche API terminée contiennent du texte, du SRT, du VTT, ainsi que des cues/words horodatés en secondes source. Les outils de transcription dédiés de l’éditeur simplifient l’utilisation d’une source existante de la Bibliothèque.
Demande d’agent typique :
Créez un film vertical de 20 secondes à partir de mes clips de Bibliothèque. Examinez des images représentatives et remplacez la prise déformée par une nouvelle génération après m’avoir indiqué son coût. Rognez les plans, ajoutez mon logo, une musique de fond discrète, une voix off et des sous-titres synchronisés. Enregistrez la vidéo finale dans la Bibliothèque et donnez-moi un lien de téléchargement.
L’assistant doit :
Lire le guide, trouver le projet et les médias source, puis inspecter les durées et la lecture.
Créer ou modifier la timeline en utilisant sa révision actuelle. Ajouter un logo sous forme d’image sur une couche visuelle supérieure et la voix/la musique sur des couches audio. Les médias d’origine restent inchangés.
Utiliser preview_editor_project pour inspecter les temps d’image sélectionnés. Définir le review: "keep" ou le "replace" du clip et enregistrer la raison dans note. Les images n’établissent ni la qualité du mouvement ni celle du son ; inspectez aussi la lecture de la source.
Découvrir/estimer les modèles demandés, générer des remplacements avec des clés d’idempotence uniques, et attendre leurs ID de fichier terminés. Remplacer la source du clip sélectionné et borner son trim/durée à la nouvelle source.
Citer/transcrire la source vocale d’origine, interroger à au moins cinq secondes d’intervalle, puis ajouter des repères avec sourceClipId pour tenir compte du trim et de la vitesse. Vérifier le texte de transcription. Fournir des repères horodatés existants ne coûte aucun crédit.
Soumettre la révision actuelle avec export_editor_project ; interroger get_editor_export à au moins cinq secondes d’intervalle pendant la mise en file/le rendu. Une requête MCP déconnectée n’annule pas la tâche. Seul completed avec un ID de média et une URL de téléchargement signifie un succès ; inspectez les échecs avant de relancer explicitement avec retry_failed: true. Créez un lien de partage uniquement si demandé.
Exemple de modification ciblée après get_editor_project :
start/duration utilisent les secondes de timeline, trimStart utilise les secondes source, et le time de séparation est un temps absolu de timeline. Lisez la durée réelle du média avant de rogner. add_clip accepte un clip avec id unique, trackId, kind, assetId, start et duration ; les autres champs ont des valeurs par défaut. Le texte utilise kind: "text" et text au lieu d’un média. Les types de piste sont visual, audio ou text. add_track, update_track, remove_track et reorder_tracks gèrent les couches. Les pistes sont rendues dans l’ordre du tableau, la dernière au-dessus. Faites se chevaucher les couches visuelles et utilisez des fondus pour les fondus enchaînés.
Le serveur rejette les médias inaccessibles, les types de média incompatibles, les trims invalides et les révisions obsolètes. En cas de conflit de révision, lisez la nouvelle version et réappliquez les modifications prévues. N’écrasez pas le travail de l’autre éditeur. Les éditeurs de navigateur propres ouverts récupèrent automatiquement les modifications de l’agent ; les brouillons modifiés localement conservent leurs changements et affichent des conflits.
L’inspection d’images par agent et l’export WebM de timeline visuelle nécessitent Playwright Chromium sur le déploiement. Ces exports de timeline visuelle prennent en charge jusqu’à deux minutes et 300 MB de médias source, et renvoient un WebM enregistré ; un export répété à la même révision réutilise son média existant. L’export navigateur prend en charge des timelines de dix minutes et propose du MP4 lorsque l’appareil dispose d’encodeurs H.264/AAC. Si le rendu échoue, signalez l’erreur et le lien de l’éditeur ; ne prétendez pas qu’un export a réussi. L’édition/le rendu de timeline ne consomment pas de crédits de modèle ; la génération/la transcription, si. Le partage crée un lien visible par toute personne disposant du lien.
Utilisez list_models avec type="audio", puis get_model pour
ai.gemini_3_8_flash_tts ou ai.gemini_3_8_flash_lite_tts.
Les deux génèrent un audio WAV à locuteur unique à partir d’un maximum de 10 000 caractères parlés :
Read get_model.voices for each preset’s exact id, gender, description
and free preview_url. Send the selected ID as parameters.voice; omit
metadata and preview URLs from generation arguments. Check the balance and call
estimate_generation with source="lab" first, then call generate_lab. Read get_task for
owned audio file IDs and signed download links. Delivery instructions belong in
style; they are not spoken. Flash focuses on expressive narration, Flash-Lite
on efficient generation. Provider selection is managed in admin settings, not
through an MCP parameter. ElevenLabs text-to-voice is temporarily disabled.
get_editor_text_styles renvoie 14 préréglages de sous-titres, 6 préréglages de titres, et un fontCatalog avec 12 polices intégrées plus 4 alias système hérités. Chaque préréglage de sous-titres réagit à de véritables horodatages de mots. Utilisez le préréglage category et use pour choisir un traitement : word-pop (impact Creator), caption-marker (marqueur lime), caption-underline, editorial (panneau podcast), caption-soft, caption-outline, ou neon-pulse (halo néon), ainsi que d’autres styles de mouvement des mots. Les titres ont leurs propres préréglages : title-clean, title-condensed, title-magazine, title-tech, title-sticker et cinema-gold. Les nouveaux sous-titres utilisent par défaut du Montserrat majuscule de 100 px avec trois mots par phrase. Conservez un style de sous-titres cohérent et un style de titre complémentaire, avec un contraste fort et des marges de sécurité. Les timelines enregistrées existantes conservent leurs réglages jusqu’à restylage. Consultez le catalogue typographique complet.
Préférez les ID fontFamily intégrés : inter, montserrat, manrope, oswald, rubik, roboto-condensed, unbounded, nunito, playfair-display, roboto-slab, jetbrains-mono, comfortaa. Ils prennent en charge le latin et le cyrillique ukrainien et se chargent depuis V4V avant le rendu dans l’aperçu et dans les deux chemins d’export. fontCatalog.weights donne la plage prise en charge par chaque famille. Les sans, impact, serif et mono hérités dépendent des polices système. N’ignorez jamais une erreur de chargement de police en affirmant que l’export a réussi.
Les clips de texte acceptent strokeWidth (0–24 pixels de sortie), strokeColor, color, fontFamily (ID du catalogue), fontWeight (400/500/600/700/800/900, borné à la plage prise en charge par la police), textBackground, backgroundColor, backgroundOpacity, accentColor, textAnimation, activeWordEffect (none, color, pop, shake, swing, spin, box, underline, glow), activeWordColor (premier plan du marqueur), letterSpacing (-0.06–0.2 em), lineHeight (0.9–1.8), textShadow, shadowColor, shadowBlur, shadowOffsetY, backgroundFit (box ou text), backgroundRadius, textTransform (none, uppercase), fontSize, animationIntensity (0–1), audioReactive et audioSourceClipId optionnel. Les animations sont none, fade, slide, pop, float, shake, pulse, color-cycle et karaoke. audioReactive: true utilise le volume audio réel, y compris le trim, la vitesse, les fondus, le volume et les pistes muettes/masquées. Il suit toutes les sources audibles sauf si un ID de clip source est fourni ; il ne détecte pas les temps musicaux. L’aperçu, le défilement, l’export local et l’export serveur partagent ce moteur de rendu.
Utilisez edit_editor_project avec { "type": "apply_text_style", "clipIds": ["caption-1", "caption-2"], "stylePreset": "creator-pop" } pour styliser plusieurs sous-titres. Affinez avec update_clip. add_captions accepte stylePreset, maxWordsPerCaption (1–8, 3 par défaut), et les words de repère tels que { "text": "Hello", "start": 1.2, "end": 1.6 }. Les mots de repère utilisent les secondes source et sourceClipId les aligne sur le trim source, la vitesse et la position dans la timeline. Sur un clip de texte individuel, wordTimings utilise des secondes relatives à ce clip. Les effets de parole mettent en évidence et animent uniquement le mot prononcé à cet instant ; préservez les horodatages authentiques. Les majuscules modifient le rendu sans réécrire le texte d’origine ni les timings. Le SRT ne fournit que le timing des repères, donc n’inventez jamais un timing des mots à partir de celui-ci.
Pour la transcription, appelez list_models avec type: "subtitle", puis get_model avec model: "ai.gemini_3_5_transcribe". Établissez un devis avec estimate_generation et soumettez la même requête via generate_lab :
Vous pouvez aussi fournir videoUrl avec une référence vidéo possédée. Choisissez exactement une source, jusqu’à 15 minutes. Le compte de service Google connecté gère l’authentification. Ne fournissez ni identifiants du fournisseur ni paramètres de routage. Interrogez get_task pour results avec type: "subtitle" ; conservez ses repères et timings de mots pour les sous-titres de l’éditeur. Google marque actuellement les horodatages des mots comme expérimentaux, donc vérifiez l’exactitude de la transcription. Les outils de devis/transcription de l’éditeur utilisent désormais ce modèle par défaut. L’ancien ai.speech_to_text reste distinct ; les administrateurs peuvent le masquer indépendamment. Les requêtes payantes échouées sont remboursées via le cycle de vie normal de la tâche et ne doivent pas être relancées automatiquement comme un nouvel achat.
Terminer le flux de travail des sous-titres de l’éditeur
La transcription d’un fichier n’insère pas de sous-titres dans un projet de l’éditeur. Pour un film existant :
Lisez get_editor_project et identifiez le clip source ainsi que son assetId.
Si vous avez déjà un résultat de sous-titres generate_lab / get_task réussi pour cette source, réutilisez son cues et passez directement à l’insertion à l’étape 4 ; il n’est pas nécessaire d’effectuer un file_id vidéo ni une seconde transcription. Sinon, appelez quote_editor_captions, puis transcribe_editor_media avec ce asset_id, language: "auto" (ou un code BCP-47) et un idempotency_key unique. Réutilisez cette clé après un délai d’attente réseau.
Interrogez get_editor_captions en espaçant les requêtes d’au moins cinq secondes. En cas de failed, signalez error et arrêtez. Une nouvelle tentative payante nécessite la demande de l’utilisateur.
En cas de succeeded, exigez un cues non vide, récupérez la dernière révision du projet et transmettez ces repères exacts à edit_editor_project avec type: "add_captions", le sourceClipId du clip source, stylePreset: "word-pop" et maxWordsPerCaption: 3 (ou un autre préréglage de mots demandé).
Vérifiez les nouveaux clips de texte dans la timeline enregistrée et prévisualisez à un moment réel de sous-titrage. Vérifiez l’exactitude du texte. Une source modifiée pendant la transcription ou un découpage sans parole qui se chevauche doit être signalé ; n’affirmez pas que l’insertion a réussi. Réutilisez les repères terminés pour résoudre les conflits d’édition sans regénérer.
Préservez tous les horodatages de mots renvoyés, y compris les décalages début/fin identiques pour les mots courts. Renommez une superposition avec update_clip / changes.name ; modifiez les mots visibles avec changes.text. Renommez son calque avec update_track / changes.name. Préservez les ID et respectez les calques verrouillés.
La transcription Gemini coûte au moins 1 crédit par requête, y compris pour les clips courts ; indiquez le tarif actuel basé sur la durée avant de générer. Le JSON des sous-titres inclut time_unit: "seconds", un tableau words plat et cues[].words, avec pour chaque mot son text, start, end et éventuellement speaker_id. Utilisez ces mots pour le karaoké et les autres styles synchronisés. Le SRT n’a qu’un minutage par ligne. Le Laboratoire peut prévisualiser les mots minutés et copier/télécharger le JSON ou le SRT. Video Editor accepte directement le JSON via Sous-titres → Importer SRT ou JSON ; choisissez l’un des grands préréglages pour texte parlé et utilisez Propriétés du clip → Mots et minutage pour corriger des mots individuellement sans supprimer leur minutage. Les corrections MCP doivent transmettre à la fois changes.text et le changes.wordTimings corrigé complet ; modifier uniquement le texte efface le minutage existant.
Pour raccourcir un calque de sous-titres minutés existant sans autre génération, utilisez :
Utilisez la révision actuelle réelle et l’ID du calque. Cela préserve le minutage réel des mots, le style et le calque, et renvoie la timeline mise à jour avec de nouveaux ID de clip. Appliquez un préréglage de mots partagé à ces ID avec apply_text_style. Dans le navigateur, utilisez Propriétés du clip → Mots et minutage → Mots par sous-titre → Diviser ce calque en sous-titres courts, puis Texte et apparence → style → Appliquer le style au calque. Les lignes SRT ne peuvent pas être divisées avec précision en mots minutés sans transcription.
Livres audio : assembler des voix, définir des balises, exporter en MP3 ou MP4 avec couverture
MCP 1.15.0 ajoute le même flux de travail Audio et livre audio disponible dans Video Editor. Lisez get_editor_guide pour audiobookTimeline, ou lisez le projet actuel avant modification. Définissez timeline.mode sur audiobook pour une timeline allant jusqu’à 7 200 secondes (deux heures), 1 000 clips et 24 calques. Le mode vidéo conserve sa limite de dix minutes/500 clips.
Recherchez les enregistrements existants via list_editor_media / get_editor_media, ou téléversez/importez-les. Générez une nouvelle parole uniquement sur demande, en utilisant la découverte de modèle, une estimation de crédits et les outils Gemini TTS existants. L’éditeur assemble les enregistrements ; il ne devine pas le locuteur de chaque ligne.
Ajoutez un calque audio pour chaque narrateur, dialogue, musique ou effet selon les besoins. Utilisez append_editor_audio avec les asset_idsordonnés, track_id, le revision actuel et éventuellement gap_seconds (0–60). Cela ajoute des clips complets à ce calque sans espaces dus à l’arrondi image par image. Cela ne trie jamais les noms de fichiers et ne tronque jamais la dernière partie pour l’ajuster. Pour les chevauchements ou un minutage personnalisé, utilisez les opérations de clip existantes. Les découpages, la vitesse, le volume, les fondus, le mode muet et les calques masqués affectent le mixage ; changer la vitesse modifie la hauteur.
Enregistrez les balises, le débit binaire et la couverture via edit_editor_project, par exemple :
settings remplace les réglages audio enregistrés : préservez les champs que l’utilisateur n’a pas demandé de modifier. Toutes les balises sont des chaînes. artist enregistre les narrateurs/interprètes, composer peut enregistrer l’auteur, album identifie le livre, year comporte quatre chiffres, et track est un nombre ou nombre/total. N’inventez ni crédits ni copyright. Si le titre est vide, le titre du projet est utilisé par défaut. Le MP3 contient des balises Unicode ID3v2.3 et, si sélectionnée, une image APIC de couverture avant. L’image est intégrée au fichier, plutôt que référencée par URL. Le MP3 peut ne pas avoir de couverture ; le MP4 avec couverture en exige une. Les débits binaires sont 96, 128 (par défaut), 192, 256 ou 320 kbps.
Envoyez export_editor_project avec la révision enregistrée et format: "mp3" ou format: "mp4-cover". Demandez les deux lorsque les deux fichiers sont souhaités. Chaque projet/révision/format a sa propre tâche persistante, donc un format n’en remplace jamais un autre. Interrogez get_editor_export en espaçant les requêtes d’au moins cinq secondes jusqu’à completed ou failed. Les étapes incluent le chargement des médias, le mixage audio avec progression, l’encodage et l’enregistrement. Un client déconnecté n’annule pas la tâche ; un envoi répété permet de la récupérer. Les tâches en échec nécessitent un retry_failed: true explicite.
Confirmez status: "completed", assetId et les liens signés de téléchargement/lecture. Vérifiez le mix final, la durée, les balises demandées et l’image avant de signaler la fin. Le MP3 est enregistré comme média de Bibliothèque audio ; le MP4 avec couverture est un média vidéo. L’inspection d’image seule ne peut pas vérifier l’audio ni les métadonnées. L’outil public de partage vidéo n’est pas destiné aux fichiers MP3 ; la collaboration privée sur projet reste disponible.
Le format mp4-cover affiche une couverture ajustée sur l’arrière-plan du projet pendant toute la durée audio. Les clips visuels, le texte et les sous-titres de la timeline sont exclus de ce format. Pour les rendre, utilisez l’export MCP format: "webm" existant (par défaut, jusqu’à deux minutes) ou l’export navigateur MP4/WebM (jusqu’à dix minutes).
Les exports audio sont réservés au propriétaire, ne coûtent aucun crédit de génération et nécessitent le worker d’éditeur persistant ainsi que FFmpeg/ffprobe avec libmp3lame et libx264. Chromium n’est pas nécessaire pour ces deux formats. Limites : 1 Go de fichiers source, 300 Mo par fichier exporté, 64 segments de clip audio par fenêtre de mixage de 30 secondes. Utilisez un débit binaire inférieur ou divisez un livre plus volumineux en parties. Les réglages et les références de couverture persistent dans la timeline, sont vérifiés par révision et suivent les autorisations média du projet après partage ou transfert de propriété. Cette version n’ajoute ni marqueurs de chapitre, ni clonage de voix, ni attribution automatique des locuteurs.
Galerie et packs de styles partagés
/video-editor/gallery et le panneau Design affichent les mêmes 30 packs de styles natifs d’origine que le Kit local. Chacun contient cinq scènes modifiables, un aperçu silencieux de 12 secondes, une illustration d’origine étiquetée, un prompt, une rubrique et un manifeste de hachage. Il s’agit d’une démonstration réutilisable de famille de scènes, et non d’une campagne produit factuelle. Les chemins d’aperçu depuis get_creative_item sont relatifs à /api/video-editor/creative-assets/ ; ils ne contiennent que du contenu original intégré, jamais des médias de compte.
create_style_example importe la véritable image source dans la Bibliothèque du propriétaire connecté et remappe l’ID média de la timeline. Il utilise v4v:write, sans crédits de génération. apply_style(dry_run=true) exige aussi un accès en modification et la révision actuelle, signale les clips modifiés/verrouillés/non pris en charge et n’effectue aucune écriture. Appliquez avec les mêmes paramètres et la même révision après avoir examiné le plan. La portée scène sélectionnée modifie la transition entrante de ces scènes ; les durées de clip et l’audio restent fixes.
Budget de génération Open Video Kit limité
create_generation_budget crée un plafond partagé immuable sans débit ; get_generation_budget lit les dépenses réelles et les réservations, close_generation_budget ferme définitivement les nouvelles allocations. Pour les médias pris en charge, estimate_generation renvoie un quote_token signé valable cinq minutes. Passez budget_id, max_credits et quote_token ensemble dans le generate_lab / generate_studio actuel ; idempotency_key est obligatoire. Les répétitions exactes de requêtes acceptées ne déclenchent pas une seconde génération. Les réservations parallèles sont comptabilisées côté serveur ; le chat facturé au token est exclu de ce chemin. Le budget n'est pas une autorisation autonome de l'utilisateur à dépenser des crédits. Contrat détaillé et validations : Cloud Kit.
Styles de référence privés (Open Video Kit 0.1.24)
get_reference_guide / v4v://reference-style documente le flux de travail partagé. analyze_reference_style accepte un reference_id stable, un média de Bibliothèque possédé (source: { type: "asset", assetId }) ou une URL video|image|page publique explicite. Il renvoie des palettes mesurées, des limites/rythmes provisoires et des durées d’image réelles ; get_reference_frame renvoie un contenu PNG. Inspectez toutes les images enregistrées avant review_reference_style, qui exige des règles originales de typographie/mise en page/mouvement/transition/rythme, les jetons complets, les limitations des réviseurs et des citations temps/SHA-256. get_reference_profile renvoie un JSON portable privé. apply_reference_style est en mode simulation par défaut ; la validation nécessite la révision actuelle d’un projet possédé, y compris la révision zéro. La vidéo de référence n’est jamais intégrée au montage ni au ZIP.
Les outils de lecture exigent v4v:read ; l’analyse/la révision/l’application exigent v4v:read et v4v:write. Ils n’exigent ni v4v:generate ni ne dépensent de crédits de génération. Les fichiers de preuve de référence/factory V4V sont chiffrés avec des clés par objet conservées uniquement dans des manifestes de base de données limités au propriétaire, et les fichiers privés sont bloqués pour la distribution générique de médias. La propriété d’origine de la Bibliothèque de référence est vérifiée à l’accès. Voir implémentation et limites ukrainiennes.
Masques de clip géométriques et parallaxe en couches
Kit 0.1.32 adds clipMasks and layeredParallax capability flags. Search kind=effect for mask-circle, mask-ellipse, or mask-rounded-rect, then read get_creative_item for the actual schema and limits. Apply set_mask through edit_editor_project at the saved revision with write access; mask:null clears it. The mask's x/y/width/height are clip-relative fractions and its bounds must remain inside the clip box. It follows rotation/scale/keyframes, clips after effects and before transitions, and does not change audio. Locked layers and audio-only targets reject the operation.
get_motion_guide.schemas.mask et recipes.parallax sont partagés avec Studio local. Le second fournit un mouvement éditable à deux calques à l’aide de simples images clés de position. Prévisualisez les images réelles ; il ne s’agit pas d’une estimation automatique de profondeur. Les commandes GUI partagées se trouvent dans Design → Effects. Le ZIP préserve les masques ; l’inspection de texte renvoie TEXT_MASK_REVIEW car les vérifications de limites ne peuvent pas garantir la lisibilité à l’intérieur d’un masque incurvé. Voir le contrat bilingue partagé.
Design → Bibliothèques propose 28 compositions natives modifiables, dont collage, mouvement continu de caméra, panneaux à ressort, personnages peints, sous-titres, présentations produit et séquences de lancement. Kit 0.3.7 inclut aussi dix styles originaux, cinq effets raster et quinze transitions. Les treize transitions de shader nécessitent WebGL et produisent jusqu’à 4096 pixels par côté.
Utilisez get_reviewed_library_guide (ressource v4v://reviewed-libraries) pour les schémas exacts, les licences source et les limites. search_library_references et get_library_reference exposent 456 entrées de métadonnées de référence ; ce ne sont pas des modèles exécutables installés. plan_library_scene est en lecture seule et renvoie des opérations pour edit_editor_project à la révision actuelle. Utilisez des médias de Bibliothèque possédés ou des médias de projet local enregistrés ; les octets locaux d’origine restent sur l’appareil de l’utilisateur. Inspectez les images réellement rendues après modification.
Planifier avec l’IA enregistre le projet et prépare une demande Video Factory modifiable. Cela n’envoie pas de commande, ne dépense pas de crédits, ne téléverse pas d’originaux et n’autorise pas la génération. L’agent clarifie les choix créatifs conséquents manquants avant modification. Le rendu natif ne nécessite aucun service de génération ; les actions payantes facultatives conservent les devis existants et l’approbation explicite. Aucun installateur amont, HTML/JavaScript arbitraire, musique exécutable ni lecteur d’historique local n’est activé. La revue source/licence et les équivalents d’origine sont fournis dans la documentation versionnée du Kit.
Qualité de montage et preuves
Lisez get_montage_quality_guide / v4v://montage-quality pour les règles de goût partagées et les limites honnêtes des preuves. plan_montage_beats dérive des coupes visuelles alignées image par image à partir des minutages réels des mots ; plan_compact_captions groupe 1 à 3 mots sans inventer d’horodatages. analyze_ui_regions mesure les limites de captures d’écran possédées ; rectify_ui_region crée une image séparée corrigée en perspective à partir d’une empreinte/ID de région renvoyée. detect_media_scenes mesure les coupes visuelles dans une fenêtre source allant jusqu’à 600 secondes. Ces opérations préservent la source et ne génèrent pas de médias payants.
compare_narration_transcript exige une transcription run_id terminée et possédée du audio_asset_id exact ; il compare la transcription réelle à script et à d’éventuels noms confirmés. Le texte ASR n’établit ni l’accentuation de prononciation ni un rendu naturel. N’achetez une transcription ou une nouvelle prise que via le flux habituel d’autorisation avec devis.
preview_editor_project accepte jusqu’à 12 times d’images réelles ; contact_sheet: true renvoie une image pour révision. Le mode navigateur Factory effectue l’inspection/la rectification sur l’appareil de l’utilisateur et conserve les originaux en local. Les appelants MCP externes utilisant un original disponible uniquement dans le navigateur reçoivent BROWSER_REQUIRED ; utilisez l’agent Factory ouvert pour ces opérations navigateur. Les nouvelles commandes Factory enregistrent des réponses distinctes de révision du contenu/de la finition pour huit questions explicites sur les preuves. Une preuve inconnue n’est pas une révision réussie.
Les résultats get_task en échec incluent error.provider_error, la raison du service de modèle nettoyée et error.provider: "managed". Les échecs connus incluent un hint et retryable ; les limitations temporaires de débit/délais d’attente donnent aussi retry_after_seconds: 60. Lisez la raison avant de modifier la demande ou d’en demander une autre tentative payante. Les erreurs inconnues conservent leur raison nettoyée sans supposer qu’une nouvelle tentative fonctionnera. Les réponses de tâche REST et les callbacks signés task.failed utilisent les mêmes champs ; voir diagnostics des générations en échec.