Vai alla documentazione
v4v.Documentazione per sviluppatoriANTEPRIMALe tue chiavi API ↗
IN QUESTA GUIDA
Collega il tuo assistenteAutorizzazione OAuth 2.1ChatGPT (OAuth)Claude WebVS CodeClaude CodeCursorCodex CLIGemini CLIOpenCodeAltri client MCPInizia con un briefStrumenti disponibiliRiutilizza il contenuto della libreria e visualizza il costoVarianti, nomi progetto ed esempiOrganizza i progetti esistentiMedia e generazioneRecupera il risultatoWebhook di completamentoCrediti e accessoRisoluzione dei problemiModelli video Kling 4.0Chat GPT-6 AstraModelli attuali di immagini e chatVideo prodotto Studio in bulkEditor videoGemini text-to-voiceTesto stilizzato, sottotitoli e trascrizione GoogleRaccolte creative e pianificazione dell'agente
Disponibile per i test
Anteprima ad accesso diretto
MCP connection guide

Crea dal tuo assistente AI.

Accedi con OAuth 2.1 oppure connettiti con una chiave API. Scopri i modelli, crea con file multimediali di riferimento, assembla modifiche multilivello e porta nella tua conversazione video, immagini e audio completati.

Inizia →
ENDPOINThttps://v4v.ai/api/mcp
OAuth
{
  "type": "http",
  "url": "https://v4v.ai/api/mcp"
}
01

Collega il tuo assistente#

Per una configurazione guidata, scegli il tuo assistente nella pagina di connessione MCP.

V4V MCP consente a un assistente AI di scoprire modelli di generazione, lavorare con media di riferimento, creare immagini, video, audio e risposte chat, e recuperare i risultati. Usa lo stesso account, gli stessi crediti e la stessa cronologia di generazione della V4V API.

URL del server: https://v4v.ai/api/mcp

Trasporto: HTTP streamabile

Autenticazione: accesso OAuth 2.1 nelle distribuzioni abilitate oppure una chiave API nei client che supportano intestazioni di richiesta personalizzate. Entrambi usano il tuo account V4V esistente e i tuoi crediti.

Usa il dominio della tua distribuzione al posto di v4v.ai quando testi un altro ambiente. Il server è già ospitato; non devi eseguire un processo locale.

Accedi con 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.

Connettiti con una chiave API

  1. Apri il tuo profilo V4V e crea una chiave in API Keys.
  2. Salva il segreto API nelle impostazioni sicure del tuo client MCP.
  3. Aggiungi il server con x-api-key: YOUR_V4V_API_KEY oppure Authorization: Bearer YOUR_V4V_API_KEY.
  4. Connettiti e inizia con get_balance oppure list_models.

Invia un solo header di autenticazione. Se vengono inviati entrambi, devono contenere la stessa chiave; credenziali in conflitto o malformate restituiscono HTTP 401. Il valore di x-api-key è la chiave stessa, senza il prefisso Bearer . Entrambi i formati di header per chiave API usano le stesse autorizzazioni, gli stessi crediti, gli stessi limiti di frequenza e la stessa revoca della chiave.

I client con chiave API continuano a usare gli stessi header e le stesse autorizzazioni. I client OAuth accedono al proprio account V4V esistente tramite il browser. Non incollare mai una chiave o un token in una conversazione con un assistente e non salvarli in un repository.

V4V / MCP connection guideCrea qualcosa che valga la pena guardare.
02

Autorizzazione OAuth 2.1#

  1. Add https://v4v.ai/api/mcp as a remote Streamable HTTP server in your assistant.
  2. 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.
  3. Your assistant opens V4V in your browser. Sign in to the V4V account whose credits and library you want to use.
  4. 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.
  5. 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'assistente individua gli endpoint OAuth dal server e usa PKCE per completare l'accesso. Non creare una chiave API e non incollare un bearer token per questo flusso. L'esempio OAuth in cima a questa pagina contiene solo il trasporto HTTP e l'URL del server; ogni client ha il proprio formato di configurazione.

La connessione non consuma crediti. Le generazioni usano il tuo saldo V4V esistente. I token di accesso durano al massimo un'ora e si aggiornano automaticamente quando il client lo supporta. La connessione scade dopo 30 giorni; riconnettiti allora o dopo aver revocato l'accesso. Gestisci e disconnetti le sessioni in Profilo V4V → Connessioni assistente. I job già inviati continuano a essere eseguiti dopo la disconnessione.

Se OAuth non è disponibile nella tua distribuzione, chiedi al relativo operatore di abilitare le connessioni assistente oppure usa una chiave API in un client compatibile.

03

ChatGPT (OAuth)#

OAuth deve prima essere abilitato nella distribuzione V4V. Le autorizzazioni di account e workspace in ChatGPT determinano se è disponibile una connessione MCP personalizzata.

  1. Apri ChatGPT Plugins → Personal, scegli Add (o +), poi Add custom MCP server (l'etichetta può variare in base all'account).
  2. Inserisci V4V e l'URL del server https://v4v.ai/api/mcp.
  3. Scegli OAuth e la registrazione dinamica del client (DCR). Lascia vuoti Client ID e Client Secret; V4V registra automaticamente un client PKCE pubblico. Questa versione supporta DCR, non CIMD.
  4. Connettiti e accedi usando il tuo login V4V esistente.
  5. Nella schermata delle autorizzazioni di V4V, controlla l'account e l'host di callback. Tutte e tre le autorizzazioni sono obbligatorie: lettura dell'account, modifica/caricamento e generazione con crediti. Le tre caselle di controllo sono selezionate e bloccate. Scegli Accept all permissions per connetterti oppure Cancel per rifiutare; il consenso parziale non è supportato.
  6. Torna in ChatGPT e installa il plugin se richiesto. In Personal plugins, apri il menu a tre punti di V4V e scegli Manage.
  7. Apri la riga Permission. Per chiamate agli strumenti senza approvazione, scegli Allow all tools. Le generazioni usano comunque i tuoi crediti V4V, quindi chiedi una stima prima di iniziare.
  8. Avvia una nuova conversazione, scegli + → Plugins → V4V (oppure menzionalo con @) e chiedi Check my V4V balance.

La guida con schermate di ChatGPT mostra tutti e otto i passaggi. Nel passaggio dei dettagli di connessione ci sono pulsanti per copiare il nome del plugin, la descrizione e l'URL del server della distribuzione corrente, oltre a un download facoltativo dell'icona V4V.

Esempio:

Crea tre concept di video prodotto verticali 9:16 da questo link prodotto. Mostrami prima i concept e la stima dei crediti. Aspetta la mia approvazione prima di avviare la generazione.

L'assistente usa gli strumenti di discovery esistenti, estimate_generation e generate_studio_variants. Le stime non eseguono il rendering e non riservano crediti, ma possono importare media per la convalida e quindi richiedono l'autorizzazione di modifica. Gli strumenti a pagamento applicano sul server l'autorizzazione di generazione. L'autorizzazione riguarda l'accesso all'account, non l'approvazione di un singolo brief creativo: controlla comunque i concept richiesti e il budget prima di autorizzare un rendering. I controlli batch max_credits e di idempotenza restano attivi.

I token di accesso durano al massimo un'ora. I token di aggiornamento ruotano quando vengono usati e la connessione scade dopo 30 giorni. Riconnettiti quando scade o quando sono necessarie autorizzazioni aggiuntive. In Profilo V4V → Connessioni assistente, controlla l'utilizzo, disconnetti l'assistente oppure mostra il suo segreto di firma del webhook per il tuo ricevitore. Non incollare il segreto di firma in chat.

La disconnessione blocca nuove richieste di strumenti, l'aggiornamento dei token e i link di caricamento non usati. I job già inviati continuano secondo le regole esistenti di coda e crediti; la disconnessione non li annulla e non li rimborsa. I link media firmati emessi in precedenza mantengono la loro normale scadenza.

I caricamenti di file dall'ambiente di esecuzione di ChatGPT dipendono dalla rete e dall'accesso agli allegati di quell'ambiente. Il link di caricamento scoped nel browser resta disponibile come alternativa. La sola connettività MCP non garantisce il trasferimento automatico degli allegati.

Il test di una connessione personalizzata e la pubblicazione pubblica del plugin sono passaggi separati. Vedi la guida alle connessioni MCP di OpenAI, i requisiti OAuth e i requisiti per la revisione pubblica.

04

Claude Web#

Connessione OAuth

Apri Add to Claude. Il modulo si apre con il nome V4V e l'URL del server di produzione già compilati. Per dev o un'altra distribuzione, usa la pagina di connessione, che compila l'URL di quella distribuzione. Se l'accesso a Claude svuota il modulo, riapri il link dopo aver effettuato l'accesso.

Segui la guida con schermate in sei passaggi insieme a Claude:

  1. Controlla nome e URL precompilati, poi scegli Continue.
  2. Claude controlla automaticamente il server. Mantieni le impostazioni rilevate Sign in now e Register automatically e scegli Add; non è necessario modificare altre impostazioni. Lascia vuoti Client ID e Client Secret, senza chiave API né header di richiesta.
  3. Nella pagina del connettore, scegli Connect e accedi a V4V.
  4. Controlla il tuo account e tutte e tre le autorizzazioni richieste, poi scegli Accept all permissions. La connessione non consuma crediti.
  5. In Tool permissions → Read-only tools, apri Custom accanto al nome del gruppo e scegli Always allow.
  6. Scorri fino a Write/delete tools e scegli Custom → Always allow anche per quel gruppo. Abilita V4V in una conversazione e chiedi Check my V4V balance. Le generazioni usano i tuoi crediti V4V; chiedi prima una stima.

Le autorizzazioni degli strumenti di Claude sono separate dall'autorizzazione dell'account V4V. I menu dei gruppi ti permettono di autorizzare gli strumenti senza modificare ciascuno singolarmente. Puoi rivedere queste scelte nelle impostazioni del connettore di Claude.

I callback ospitati di Claude su claude.ai e claude.com sono supportati senza configurazioni aggiuntive dell'ambiente. Usa Register automatically; l'identità client pubblicata di Claude (CIMD) non è implementata in questa release. Le connessioni esistenti con chiave API continuano a funzionare come descritto sotto.

Se vengono mostrate le impostazioni di trasporto, usa Streamable HTTP. L'aggiunta di un connettore e l'autorizzazione del suo accesso all'account sono passaggi separati quando Claude li presenta in questo modo.

Alternativa con chiave API: crea la tua chiave API V4V

Apri il tuo profilo V4V, vai su API Keys e crea una chiave. Tienila pronta per l'header del connettore qui sotto.

2. Aggiungi il connettore

  1. Open Add to Claude, or open Customize → Connectors → Add → Custom web connector.
  2. Set Name to V4V.
  3. Set MCP server URL to https://v4v.ai/api/mcp.
  4. Under Authentication, select No sign-in.
  5. Click Add header and enter:
Impostazione headerValore
Namex-api-key
ValueLa tua chiave API V4V, esattamente come copiata
  1. Fai clic su Add / Connect e attendi il completamento della connessione.

Usa solo la chiave in x-api-key, senza il prefisso Bearer . No sign-in salta OAuth; l'header autentica comunque ogni richiesta a V4V. Lascia vuoti OAuth Client ID e Client Secret.

3. Autorizza gli strumenti

  1. Apri il Connectors manager di Claude.
  2. Seleziona il nuovo connettore V4V.
  3. Apri Tool permissions e autorizza tutti gli strumenti V4V.
  4. Conferma che create_upload_link, get_upload, get_model e generate_lab siano disponibili e abilitati.

Dopo che V4V aggiunge o aggiorna strumenti, aggiorna gli strumenti del connettore oppure riconnettilo prima di iniziare una nuova conversazione.

4. Consenti i caricamenti automatici dei file

  1. Apri Settings → Capabilities.
  2. Abilita Code execution and file creation e Allow network egress se sono disattivati.
  3. In Domain allowlist, aggiungi queste voci:
text
v4v.ai
*.v4v.ai
*.v4vcdn.space

Mantieni sia il dominio radice sia la voce con wildcard, così sono coperti il dominio dell'app e i suoi sottodomini. Inserisci solo i nomi di dominio, senza https:// o /api/mcp, e salva le modifiche. Se il tuo workspace gestisce centralmente questa impostazione, chiedi al suo amministratore di aggiornare l'allowlist.

Questo consente all'ambiente di esecuzione di Claude di inviare l'allegato originale direttamente a V4V usando l'autorizzazione di caricamento a breve durata emessa da MCP. Senza questa impostazione, il connettore può funzionare mentre i caricamenti dei file falliscono con host_not_allowed.

Test su dev: usa https://h4000.kitpes.com/api/mcp come URL del connettore e aggiungi h4000.kitpes.com separatamente alla Domain allowlist. Le voci di dominio V4V non coprono l'hostname dev.

5. Avvia una nuova conversazione

Abilita il connettore V4V in una nuova chat, allega la tua immagine e chiedi:

Migliora la risoluzione di questa immagine di 4× con V4V. Carica automaticamente il file originale, poi usa il suo file ID con il modello Topaz.

Claude dovrebbe ottenere un'autorizzazione di caricamento tramite MCP, trasferire il file dal suo ambiente di esecuzione senza copiare base64 nella chat e inviare la generazione. Non devi caricare di nuovo il file in una pagina browser separata quando l'accesso di rete è consentito.

Per i controlli generali di connettore e rete di Claude, vedi gestione connettori e esecuzione del codice e accesso alla rete.

05

VS Code#

Accesso con OAuth

Usa Install in VS Code nella pagina di connessione, oppure aggiungi questo a .vscode/mcp.json:

json
{
  "servers": {
    "v4v": {
      "type": "http",
      "url": "https://v4v.ai/api/mcp"
    }
  }
}

Avvia il server, controlla il prompt di attendibilità e completa l'accesso a V4V quando VS Code apre il browser. Abilita gli strumenti che vuoi usare nella chat agent.

Alternativa con chiave API

Per la chat dell'editor, aggiungi quanto segue a .vscode/mcp.json. VS Code richiede la chiave e ne maschera l'input. Mantieni il segnaposto nel file.

json
{
  "inputs": [
    {
      "id": "v4v-api-key",
      "type": "promptString",
      "description": "V4V API key",
      "password": true
    }
  ],
  "servers": {
    "v4v": {
      "type": "http",
      "url": "https://v4v.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:v4v-api-key}"
      }
    }
  }
}

Avvia il server dalla configurazione MCP e abilita i suoi strumenti nella tua sessione di chat. Controlla la chiamata allo strumento di generazione prima di consentirgli di spendere crediti.

Per altri ambienti agent di VS Code, segui l'attuale riferimento di configurazione MCP per il percorso di configurazione supportato da quell'ambiente.

06

Claude Code#

Accesso con OAuth

Registra il server remoto senza un header di autenticazione:

bash
claude mcp add --transport http v4v https://v4v.ai/api/mcp

Avvia Claude Code, esegui /mcp, scegli V4V e autenticati. Completa la schermata delle autorizzazioni V4V nel browser, poi torna alla CLI.

Alternativa con chiave API

Imposta V4V_API_KEY in modo sicuro nell'ambiente della tua shell, poi registra il server remoto:

bash
claude mcp add --transport http \
  --header "x-api-key: $V4V_API_KEY" \
  v4v https://v4v.ai/api/mcp

Usa /mcp dentro Claude Code per controllare la connessione. La registrazione salva l'header configurato nella configurazione locale del client; proteggi quel file e tienilo fuori dal controllo del codice sorgente. Vedi la guida MCP di Claude Code per ambito della configurazione e gestione delle chiavi.

07

Cursor#

Nella pagina di connessione, scegli l'accesso V4V o la chiave API e fai clic su Install in Cursor. Controlla l'installazione in Cursor prima di accettare. OAuth apre un accesso nel browser; la configurazione con chiave API installa un segnaposto che sostituisci localmente in .cursor/mcp.json. Nessuna chiave reale è incorporata nell'URL di installazione. Le attuali versioni desktop usano un callback HTTP loopback; i client cloud usano l'URI https://www.cursor.com/agents/mcp/oauth/callback esatto approvato.

08

Codex CLI#

Per OAuth, aggiungi il server ed effettua l'accesso:

bash
codex mcp add v4v --url https://v4v.ai/api/mcp
codex mcp login v4v

Per una chiave API, imposta in modo sicuro V4V_API_KEY nel tuo ambiente, poi esegui:

bash
codex mcp add v4v --url https://v4v.ai/api/mcp --bearer-token-env-var V4V_API_KEY
09

Gemini CLI#

Aggiungi il server remoto con gemini mcp add --transport http v4v https://v4v.ai/api/mcp. Esegui /mcp auth v4v dentro Gemini CLI per OAuth. Per la configurazione con chiave API, imposta V4V_API_KEY in modo sicuro e aggiungi il server con gemini mcp add --transport http --header "x-api-key: $V4V_API_KEY" v4v https://v4v.ai/api/mcp. La CLI salva l'header configurato; mantieni private le sue impostazioni.

10

OpenCode#

Aggiungi un server remoto sotto mcp.v4v in opencode.json con type: "remote", url: "https://v4v.ai/api/mcp" e enabled: true. Esegui opencode mcp auth v4v per OAuth. La pagina di connessione fornisce il JSON completo e un'alternativa con chiave API tramite variabile d'ambiente.

11

Altri client MCP#

Scegli un server remoto / Streamable HTTP e fornisci:

ImpostazioneValore
Nomev4v
URLhttps://v4v.ai/api/mcp
Autenticazione (scegline una)x-api-key: YOUR_V4V_API_KEY o Authorization: Bearer YOUR_V4V_API_KEY

I formati di configurazione variano in base al client. Configura l'header nelle impostazioni dei segreti del client, non in un messaggio di chat. I client legacy solo SSE non sono supportati. I client OAuth nativi supportati usano callback HTTP su localhost o 127.0.0.1 con una porta locale esplicita. Registrazione e autorizzazione associano esattamente l'URL di callback completo. Le callback ospitate per Claude, ChatGPT, Cursor e VS Code sono approvate; altri client ospitati richiedono URL esatti in MCP_OAUTH_REDIRECT_URIS.

12

Inizia con un brief#

Per un film completo o un riedit creativo di una registrazione, risolvi le scelte mancanti più importanti prima dell'assemblaggio o del lavoro a pagamento: obiettivo, pubblico, materiale sorgente, formato, durata target, trattamento visivo, sottotitoli, voce, musica e lingue di output. get_started accetta scelte request_kind (production, creative_edit, targeted_edit) e creative_brief confermate; restituisce videoBrief.productionQuestions e readyForProduction. Riutilizza le risposte fornite e le deleghe esplicite. Un taglio preciso o una correzione richiede solo i dettagli rilevanti per quella modifica. L'approvazione automatica della spesa non fornisce risposte creative. Queste regole sono condivise da V4V MCP e Open Video Kit 0.3.6.

Puoi iniziare con una richiesta come:

Trova un modello per un video verticale di otto secondi del mio mug in ceramica. Usa questa immagine del prodotto: https://example.com/mug.jpg. Mostrami un concept e gli input richiesti prima di generare.

Se non viene indicato alcun modello, l'assistente deve usare Google/Gemini Omni Flash v1.2 per impostazione predefinita (video.gemini_omni_flash-1-2), esaminare il suo schema e la disponibilità attuali con get_model, controllare il saldo e preparare gli input. Quando richiedi la generazione, invia un task e controlla il risultato finale. Questa regola è al primo posto nelle istruzioni di inizializzazione MCP ed è ripetuta nelle descrizioni di list_models, get_model e generate_lab. Il rilevamento dei modelli video restituisce default_video_model; il modello selezionato espone default_for_unspecified_video: true. Le scelte esplicite di modello o di flusso di lavoro Studio/in blocco hanno la priorità.

Per normali richieste video senza un modello esplicito, preferisci generate_lab con video.gemini_omni_flash-1-2. L'assistente non dovrebbe chiedere all'utente di scegliere un modello solo perché è stato omesso. Le scelte esplicite del modello e i flussi di lavoro Studio/in blocco richiesti esplicitamente hanno la priorità. get_model resta obbligatorio prima di selezionare input e parametri; se il modello preferito è disattivato, non disponibile o non adatto, spiega il limite e chiedi un'alternativa invece di spendere silenziosamente crediti altrove. Il routing del provider è configurato da V4V, non è un parametro di generazione. Usa generate_studio per un flusso di lavoro Studio richiesto esplicitamente; il rilevamento di immagini, audio, traduzione e chat resta invariato.

Il prompt video_brief aiuta a trasformare obiettivo, pubblico e formato in un piano di inquadrature. La risorsa v4v://guide spiega il flusso di lavoro di generazione al tuo assistente.

13

Strumenti disponibili#

StrumentoScopoCrea una generazione?
list_modelsScopri i modelli abilitati; facoltativamente filtra per immagine, video, audio o chatNo
get_modelLeggi input, opzioni e limiti di un modello; funziona anche model: "studio"No
describe_studioScopri stili, durate, formati, qualità, voci e limiti media correnti di StudioNo
list_productsTrova i prodotti posseduti; riutilizza i loro ID come Studio input.product_idNo
list_avatarsTrova avatar pubblici attivi e posseduti; riutilizza gli ID come Studio input.avatar_idNo
estimate_generationConvalida e preventivizza una richiesta LAB/Studio senza eseguire il rendering o riservare creditiNo
get_balanceControlla i crediti disponibili dell'accountNo
get_usageTrova i task di generazione recentiNo
get_fileEsamina un file di riferimento possedutoNo
import_mediaSalva un URL media pubblico nella tua libreriaNo
create_upload_linkEmetti una richiesta di upload HTTP con ambito limitato; link browser disponibile come fallbackNo
get_uploadRecupera lo stato dell'upload e l'ID fileNo
upload_mediaUpload inline programmatico di byte; evita grandi base64 nel testo del modelloNo
generate_labCrea con un modello specificoSì — spende crediti
generate_studioCrea un video da un prodotto o da un brief creativoSì — spende crediti
get_taskControlla stato, ID progetto, ID media stabili e link firmati rinnovabiliNo
refresh_task_resultsRinnova URL dei risultati firmati senza renderingNo
list_projectsTrova progetti Studio, flussi di lavoro, LAB e API in coda posseduti per titolo, sorgente o cartellaNo
rename_projectRinomina un progetto posseduto o il futuro progetto di un task in codaNo
list_project_foldersElenca le stesse cartelle mostrate nello spazio di lavoro ProgettiNo
create_project_folderCrea una cartella di workspaceNo
rename_project_folderRinomina una cartella mantenendo i suoi progettiNo
move_projectAssegna una cartella posseduta, oppure usa folder_id: null per rimuovere dalla cartellaNo
generate_studio_variantsMetti in coda 2–3 varianti creative usando il budget e i controlli in blocco esistentiSì — quando le varianti iniziano
promote_to_exampleEsempi solo per amministratori: copia/aggiorna l'esempio di un progetto posseduto con visibilità esplicitaNo

Il rilevamento di Studio legge il flusso di lavoro selezionato e gli stili attivi da questa distribuzione; non codifica rigidamente sette nomi di stile né presume che ogni flusso di lavoro abbia un limite di dieci secondi. get_model con model: "studio" è un alias di describe_studio. Le istruzioni essenziali sono anche nelle descrizioni degli strumenti per i client che non possono leggere v4v://guide.

Gli schemi dei modelli provengono dallo stesso catalogo usato da V4V LAB. Chiedi get_model prima di scegliere i parametri; riferimenti, durate e formati richiesti variano in base al modello.

14

Riutilizza il contenuto della libreria e visualizza il costo#

Chiama list_products o list_avatars (facoltativi offset e limit, massimo 100). Gli avatar usano per impostazione predefinita source: "all"; sono disponibili i filtri owned e public. Il valore next_offset restituito è null nell'ultima pagina. Gli ID avatar pubblici includono public:; mantieni questo prefisso. Ogni record include photo_count; Studio usa la foto principale dell'avatar. Vengono restituiti solo i record della tua libreria privata.

Usa input.product_id e input.avatar_id in generate_studio o estimate_generation. parameters.avatar accetta anche l'ID avatar restituito e continua a supportare un ID file o un URL immagine pubblico. Scegli input.avatar_id oppure parameters.avatar. Le foto della libreria vengono risolte direttamente senza scaricarle e caricarle di nuovo. Input espliciti di nome prodotto, descrizione o immagine sovrascrivono i valori predefiniti del prodotto salvato. Gli ID/nomi di stile attivi usano le istruzioni creative salvate; ID/nomi di stile sconosciuti o inattivi restituiscono INVALID_PARAMETER con allowed_values. Inserisci le indicazioni creative in forma libera in input.prompt e scegli un preset attivo (oppure ometti lo stile per usare il predefinito rilevato).

json
{
  "source": "studio",
  "input": {
    "product_id": "0123456789abcdef01234567",
    "avatar_id": "public:0123456789abcdef01234568",
    "prompt": "A short product review"
  },
  "parameters": {
    "duration": 10,
    "style": "Product Review"
  }
}

Invialo a estimate_generation. Restituisce credits_estimated, riserva zero crediti e non crea task né rendering. I preventivi Studio saltano la registrazione dei personaggi del provider, anche quando è selezionato un avatar. Gli URL media pubblici possono essere importati per la convalida. I preventivi possono cambiare in base a input/prezzi; i preventivi chat descrivono una riserva iniziale, non i costi finali dei token né un tetto di spesa. Per eseguire il rendering, rimuovi source e invia gli stessi input a generate_studio con un nuovo idempotency_key.

15

Varianti, nomi progetto ed esempi#

generate_studio_variants accetta name, input/parameters condivisi, un max_credits obbligatorio, idempotency_key e variants contenente due o tre oggetti con override facoltativi di input/parametri. Per esempio: variants: [{parameters: {style: "UGC"}}, {parameters: {style: "Product Review"}}]. Ogni variante è un tentativo a pagamento separato. Questo è un wrapper sulla coda batch Studio esistente: restituisce batch_id, usa get_studio_batch per i risultati e gli stessi controlli di pausa/budget/rilavorazione. Non aggira mai i limiti di capacità.

Usa rename_project con project_id restituito da list_projects, generazione o get_task, e project_name (senza spazi superflui, 1–200 caratteri). La rinomina aggiorna anche il titolo del task e la cronologia LAB, incluso quando un progetto è ancora in attesa di essere creato. Non cambia l'hash di richiesta di idempotenza originale.

Solo gli amministratori degli esempi vedono promote_to_example. Accetta un project_id posseduto con un risultato salvato, active obbligatorio e surfaces: ["dashboard", "studio", "landing"] (scegli qualsiasi sottoinsieme). studio corrisponde al flag di visibilità ProVid/Studio esistente. active: false nasconde l'esempio ovunque indipendentemente dalla selezione della superficie. Il risultato include visible_on così la visibilità effettiva è chiara. La pubblicazione richiede una richiesta dell'utente; questo strumento non spende crediti di generazione.

16

Organizza i progetti esistenti#

Usa list_projects per trovare progetti esistenti senza generare. Include Studio, flussi di lavoro, cronologia LAB e progetti API in coda. Filtri facoltativi: source: "all" | "studio" | "workflow" | "lab", q per la ricerca letterale nel titolo e folder_id per una cartella posseduta o "unfiled". Ometti il filtro cartella per vedere tutti i progetti. Sia list_projects sia list_project_folders accettano offset (predefinito 0) e limit (1–100, predefinito 50); segui next_offset finché non è null.

Per esempio, per organizzare i risultati approvati di una campagna:

  1. Chiama list_projects con {"q":"approved"} e seleziona i progetti desiderati.
  2. Chiama list_project_folders; riutilizza la cartella desiderata oppure chiama create_project_folder con {"name":"Summer campaign"}.
  3. Chiama move_project per ogni project_id selezionato con il valore folder_id restituito.
  4. Chiama list_projects con quel folder_id per verificare il contenuto della cartella.

Usa move_project con folder_id: null per rimuovere un progetto dalla sua cartella. rename_project_folder accetta folder_id e name. I nomi delle cartelle devono contenere 1–80 caratteri dopo la rimozione degli spazi superflui ed essere univoci nel tuo account; un duplicato restituisce FOLDER_NAME_CONFLICT. Dopo una risposta incerta alla creazione, elenca le cartelle prima di riprovare. Spostamenti e rinomine sono sicuri da ripetere e non spendono crediti, non generano media e non cambiano i risultati. I progetti in coda mantengono nomi e cartelle quando il worker li crea. Queste operazioni non possono accedere a progetti o cartelle di un altro account.

17

Media e generazione#

I media di riferimento possono essere un URL pubblico o un ID file V4V posseduto. Anche un campo chiamato image_url accetta un ID file; usa lo schema del modello per scegliere il campo di input esatto.

Upload automatici da file allegati e locali

L'assistente può caricare direttamente il file originale quando il suo ambiente di esecuzione può raggiungere questa distribuzione V4V. Non devi copiare una chiave API nella chat né selezionare di nuovo lo stesso file.

  1. Chiama create_upload_link. Nonostante il nome, lo strumento restituisce anche upload_request: un URL POST, un header x-upload-token con ambito limitato e il nome del campo multipart file.
  2. Dallo strumento di esecuzione dell'assistente, invia i byte effettivi del file locale a quell'URL usando multipart/form-data. Lascia che il client HTTP imposti il boundary e disattiva i redirect. Non convertire l'immagine né stampare base64 nella conversazione.
  3. Leggi file_id della risposta e conferma con get_upload usando upload_id.
  4. Scopri lo schema di input del modello, passa quell'ID nel suo campo media (come Topaz image_url) e invia la generazione richiesta.
  5. Per più riferimenti, ripeti con uno slot di upload separato per ogni file richiesto.

Il token di upload scade dopo 15 minuti, accetta un file fino a 20 MiB soggetto al limite del server e non può leggere la tua libreria né spendere crediti di generazione. I byte effettivi viaggiano su HTTP; MCP fornisce l'autorizzazione con ambito limitato e controlla la generazione.

Per un ambiente di esecuzione con il risultato dello strumento disponibile come slot, il trasferimento binario è:

python
import requests

upload = slot["upload_request"]
with open(local_file_path, "rb") as source:
    response = requests.post(
        upload["url"],
        headers=upload["headers"],
        files={upload["file_field"]: (filename, source, content_type)},
        allow_redirects=False,
        timeout=120,
    )
if response.status_code != 200:
    raise RuntimeError(f"Upload failed: HTTP {response.status_code}")
file_id = response.json()["file_id"]

Consentire l'hostname di upload in Claude

La connettività MCP e l'accesso di rete del sandbox sono separati. host_not_allowed significa che il sandbox non può inviare l'upload binario anche se le chiamate MCP funzionano.

Segui Claude Web → Consenti upload automatici di file sopra: apri Impostazioni → Capacità → Allowlist domini, aggiungi v4v.ai, *.v4v.ai e *.v4vcdn.space, e abilita l'uscita di rete. Per lo sviluppo, aggiungi separatamente h4000.kitpes.com. Le restrizioni gestite dal workspace potrebbero richiedere a un amministratore di effettuare la modifica.

L'assistente deve fermarsi dopo la prima richiesta negata e spiegare l'impostazione necessaria, non riprovare per minuti né convertire il file in testo del modello. Avvia una nuova conversazione dopo aver aggiornato i permessi e aggiorna gli strumenti del connettore dopo un aggiornamento del server.

Fallback opzionale del browser

Se scegli l'upload manuale, apri upload_url, seleziona il file originale e comunica all'assistente quando è pronto. Recupererà l'ID file con get_upload. Questo è un fallback, non un passaggio obbligatorio quando l'upload HTTP automatico funziona.

upload_media resta disponibile per l'inoltro programmatico di byte o payload molto piccoli fino a 8 KiB codificati. Il suo limite server decodificato di 5 MiB non è un budget pratico per il testo di un modello linguistico. Non ridimensionare/ricomprimere una sorgente solo per trasferirla, non stampare grandi stringhe base64 e non ciclare su chunk codificati.

Upload REST per file più grandi

Se l'ambiente di esecuzione dell'assistente ha accesso alla rete in uscita e una chiave API configurata in modo sicuro, può caricare tramite POST /api/v1/files usando il campo multipart file. La chiave del connettore MCP non è automaticamente disponibile agli strumenti 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"

Il valore id della risposta è l'ID file da usare negli input di generazione. Lascia che curl imposti il boundary multipart. Mantieni le credenziali nella configurazione sicura del client, non nella conversazione.

URL pubblici

Usa import_media per salvare un URL media accessibile da riutilizzare, oppure fornisci l'URL direttamente al modello. Non passare un percorso locale o un URL sandbox come URL pubblico.

Argomenti di esempio per generate_lab (sostituisci l'ID di esempio con l'ID restituito dal tuo upload):

json
{
  "model": "image-upscale-topaz",
  "project_name": "Product detail — enlarged",
  "input": {
    "image_url": "0123456789abcdef01234567"
  },
  "parameters": {
    "upscale_factor": "2"
  },
  "idempotency_key": "product-detail-upscale-001"
}

Argomenti di esempio per generate_studio:

json
{
  "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"
}

Usa un nuovo idempotency_key per ogni generazione intenzionale. Riutilizza la stessa chiave e gli stessi argomenti quando ritenti una richiesta dopo un'interruzione di rete. Riutilizzare una chiave con input modificati restituisce un conflitto.

18

Recupera il risultato#

Gli strumenti di generazione restituiscono subito task_id e project_id. Se il limite di concorrenza dell'account è pieno, la stessa attività resta in attesa con i dettagli credits_reserved: 0, credits_estimated e queue che contengono il limite configurato, un intervallo di controllo di cinque secondi e estimated_start_at: null. I tempi di completamento non possono essere previsti. Non inviare un'altra generazione per aggirare l'attesa. Il worker riserva i crediti quando si apre uno slot; se in quel momento il saldo è insufficiente, l'attività fallisce nella fase di ammissione e invia il webhook configurato. Non tengono la conversazione aperta fino al termine del rendering.

json
{
  "task_id": "task_6aa962444bd1dd7ab65bc6b6"
}

Passa quell'ID a get_task. Attendi almeno cinque secondi tra un controllo e l'altro. Un'attività può essere queued, processing, completed, failed o cancelled.

Quando lo stato è completed, results contiene testo inline per la chat o URL di download firmati per i media. L'assistente può condividere questi URL con te senza richiedere cookie del browser. Usa get_task o refresh_task_results se un link scade. I risultati media includono asset_id/file_id stabili; passa file_id direttamente nei futuri campi media di generazione invece di copiare un URL in scadenza. Il contratto di riutilizzo del giorno successivo è l'ID stabile più un link rinnovabile finché il file esiste e l'accesso resta consentito; l'URL stesso può scadere. I link restano firmati; non rimuovere mai la firma e non ricavare un percorso CDN non firmato. Interrompi il polling su qualsiasi stato terminale. Controllare un'attività non avvia mai una seconda generazione. Le attività non riuscite riportano error.stage, brief_completed, retryable e le retry_after_seconds suggerite quando note, insieme all'effettivo credits_used. Un brief completato può mantenere il proprio addebito anche quando la generazione video fallisce. retryable: true descrive un errore potenzialmente transitorio; non autorizza un altro tentativo a pagamento. Se l'attività restituisce GENERATION_SERVICE_ERROR, il servizio del modello ha segnalato un errore interno. Non presumere che la causa sia stata la risoluzione di origine o il fattore di scala, e non cambiare automaticamente modello né creare nuovi tentativi a pagamento. Spiega l'errore e attendi un nuovo tentativo richiesto.

Le generazioni di LAB compaiono anche in LAB → Vecchie esecuzioni e Progetti. L'utilizzo della tua chiave API compare nel tuo profilo.

19

Webhook di completamento#

generate_lab e generate_studio accettano callback_url usando la consegna webhook REST esistente e la verifica della firma. V4V invia task.completed o task.failed con event_id stabili, dati dell'attività, crediti e risultati. Verifica X-V4V-Timestamp e X-V4V-Signature usando il segreto di firma del webhook mostrato quando è stata creata la chiave API, e deduplica in base a event_id. Non incollare segreti nella chat. I nuovi tentativi di consegna non creano nuove generazioni. Gli URL di callback usano la stessa convalida di rete esterna del REST. Anche gli invii bulk e di varianti accettano callback_url per eventi batch firmati; vedi il flusso di monitoraggio qui sotto. Vedi REST webhook verification.

20

Crediti e accesso#

La generazione usa i tuoi normali crediti V4V. Per le normali attività LAB/Studio, il costo stimato viene riservato quando la capacità è disponibile; le attività in eccesso restano in attesa senza riserva. Il credito non utilizzato segue le stesse regole di rilascio dell'API REST. La consultazione di modelli, saldi, attività e file esistenti non consuma crediti di generazione.

Ogni strumento è limitato al proprietario della chiave configurata. Non è possibile accedere ai file e alle attività di un altro account. Revoca una chiave nel tuo profilo per disattivare la sua connessione MCP. Le annotazioni degli strumenti identificano le chiamate che creano lavoro e consumano crediti, così il tuo client può offrire i suoi normali controlli di approvazione degli strumenti.

21

Risoluzione dei problemi#

SintomoCosa controllare
create_upload_link o upload_media mancaAggiorna o riconnetti il connettore MCP in modo che il client rilevi l'elenco aggiornato degli strumenti
HTTP 401Usa una chiave valida e non revocata in x-api-key, oppure Authorization con il prefisso Bearer ; rimuovi gli header in conflitto
HTTP 403Per un client basato su browser, il suo Origin deve essere consentito dal deployment
HTTP 405 in un browserL'endpoint accetta richieste MCP POST; usa un client MCP
HTTP 406Il client deve accettare sia application/json sia text/event-stream
HTTP 429 / RATE_LIMIT_EXCEEDEDLeggi error.retryable e retry_after_seconds nel JSON; i limiti della finestra di richiesta includono anche scope e limit. Attendi il ritardo e riutilizza la stessa chiave di richiesta/idempotenza per una richiesta rifiutata. Un'attività già fallita resta terminale. I limiti dell'account e della chiave sono condivisi con REST.
Il risultato dello strumento contiene isError: trueLeggi l'errore strutturato, correggi gli input ed evita ritenti ciechi della generazione
Input del modello rifiutatoAggiorna get_model e usa il suo schema corrente
L'attività resta in coda o in elaborazioneContinua a controllare con un ritardo; non inviare automaticamente una generazione sostitutiva

Il servizio usa l'SDK TypeScript MCP ufficiale e una modalità di risposta JSON stateless su Streamable HTTP. Gli strumenti con attesa limitata mantengono aperta la singola richiesta fino a un aggiornamento o a un timeout; non stabiliscono un canale di notifica permanente. Il client negozia la versione del protocollo quando si connette.

Varianti immagine GPT Image 2.5

L'individuazione dei modelli include le varianti testo/immagine Flare e Sunburst con valori predefiniti Sunburst per image.text_to_image e ai.image_edit. Supportano background, prezzi 1K/2K/4K (6/10/16 crediti), prompt fino a 20.000 caratteri e fino a 16 immagini di modifica. Vedi GPT Image 2.5 settings and API examples per gli ID delle varianti e le restrizioni del rapporto d'aspetto.

22

Modelli video Kling 4.0#

Quattro nodi separati condividono la stessa gestione di generazione e risultati in Laboratorio, Flussi di lavoro, API e MCP:

ID catalogoModelloDurataRisoluzione
video.kling_v40_refKling 4.0 Reference3–30 secondi720p / 1080p
video.kling_v40_keyKling 4.0 Keyframe3–30 secondi720p / 1080p
video.kling_v40_flash_refKling 4.0 Flash Reference3–20 secondi720p
video.kling_v40_flash_keyKling 4.0 Flash Keyframe3–20 secondi720p

Tutti accettano un prompt obbligatorio (fino a 8000 caratteri), duration intero, resolution e aspectRatio (auto, 16:9, 9:16, 1:1, 21:9; Flash Keyframe esclude auto). Tutti possono generare dal solo testo. Gli input di riferimento sono facoltativi.

I modelli Reference accettano referenceImageUrls (fino a 10), referenceVideoUrls (fino a 5), elements (fino a 7, al massimo 3 con video) e keepOriginalSound. Un elemento denominato ha name, oppure imageUrls (2–4 immagini) oppure videoUrl (una clip personaggio di 3–8 s), tag facoltativo, description (100 caratteri) e voiceUrl del personaggio. Flash accetta anche l'elemento type (image o video). Standard Reference accetta inoltre voices: fino a 3 oggetti con name e audioUrl. Flash invece associa le voci agli elementi personaggio.

Ci sono al massimo 15 tra immagini, riferimenti video, elementi e voci standalone combinati; i video di riferimento più gli elementi video non possono superare 5. Ogni video di riferimento deve durare 2–30 s (2–20 s per Flash), e la loro durata combinata inclusi gli elementi video è al massimo di 30 s (20 s per Flash). I nomi devono essere univoci ignorando maiuscole e minuscole, 1–20 caratteri cinesi, lettere, cifre o underscore; i nomi di riferimento incorporati sono riservati. Cita i riferimenti forniti come @image_1, @video_1 o con il loro @name dichiarato. Le menzioni non dichiarate vengono rifiutate.

I modelli Keyframe usano firstFrameUrl. Standard Keyframe accetta anche keyframeUrls ordinati (fino a 8 fotogrammi intermedi) e lastFrameUrl; questi richiedono un primo fotogramma. Il totale dei fotogrammi non può superare min(duration + 1, 10). Flash Keyframe supporta solo il primo fotogramma. Cita i fotogrammi come @first_frame, @keyframe_1, @last_frame. L'output basato sui fotogrammi segue il rapporto d'aspetto della prima immagine.

Tutti i campi media, inclusi elementi e voci nidificati, accettano URL o ID file V4V di tua proprietà in API/MCP. Le porte immagine/video dei flussi di lavoro usano reference_image_urls / reference_video_urls, oppure first_frame_url / keyframe_urls / last_frame_url; i prompt usano script-in. Standard Reference accetta inoltre audio su voice_audio_urls, dichiarato come @voice_1, @voice_2, ecc. Entrambi gli output del flusso di lavoro sono standard video / clips, adatti al renderer e all'editor esistenti. API/MCP restituiscono la consueta attività asincrona e i file di risultato scaricabili; esegui il polling dell'attività o usa i webhook di completamento.

Tariffe base approvate in crediti V4V al secondo, prima delle sostituzioni dell'amministratore o delle regolazioni esistenti del flusso di lavoro. Queste tariffe vengono usate direttamente, senza conversione in USD né ricarico retail:

Modello720p, senza video720p, con video1080p, senza video1080p, con video
Standard Reference28.51742.525.5
Standard Keyframe28.5non disponibile42.5non disponibile
Flash Reference1711.3non disponibilenon disponibile
Flash Keyframe17non disponibilenon disponibilenon disponibile

Esempi per un output di 5 secondi:

Modello5 s senza video sorgente5 s con fino a 5 s di video sorgente
Standard Reference, 720p142.5 crediti170 crediti
Standard Reference, 1080p212.5 crediti255 crediti
Standard Keyframe, 720p / 1080p142.5 / 212.5 creditinon disponibile
Flash Reference, 720p85 crediti113 crediti
Flash Keyframe, 720p85 creditinon disponibile

Senza input video, i secondi fatturabili equivalgono ai secondi di output. Con video di riferimento o un elemento video, i secondi fatturabili equivalgono a max(total input video seconds, output seconds) + output seconds, alla corrispondente tariffa con input video. Per esempio, un output Standard Reference 1080p di 10 s con 15 s di input corrisponde a 25 secondi fatturati, 637.5 crediti prima delle regolazioni. I crediti frazionari vengono mantenuti; l'addebito completo viene arrotondato una sola volta a due decimali. Se la durata dell'input è sconosciuta, viene usata per una stima prudenziale la durata massima di input consentita dal modello; il server verifica le durate reali delle sorgenti prima dell'addebito. Richiedi un preventivo aggiornato usando gli stessi input della generazione. L'amministrazione espone tariffe separate per risoluzione/input video per ogni nodo. I nodi Kling meno recenti mantengono i loro prezzi e impostazioni esistenti.

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

Usa questo body con generate_lab in MCP o POST /api/v1/lab in HTTP. Per un preventivo, aggiungi "source": "lab" e usa estimate_generation in MCP o POST /api/v1/generation/quote in HTTP. Individua sempre prima il modello selezionato con get_model o GET /api/v1/models/{id}. Si applicano l'autorizzazione standard della generazione, i controlli del saldo, le chiavi di idempotenza, i callback e i rimborsi per errore.

23

Chat GPT-6 Astra#

Usa list_models con {"type":"chat"}, poi get_model con {"model":"chat.gpt_6_astra"} per ispezionare input correnti, tariffe token e arrotondamento. Invia usando 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.

La chat riserva inizialmente 1 credito. Il costo finale usa i token effettivi di input, cache e output, arrotondati per eccesso a un credito intero con un minimo di 1. Qualsiasi importo oltre la riserva viene detratto dopo la risposta; la riserva iniziale non è un limite di spesa. Le tariffe token sono pubblicate da get_model. Riutilizza la stessa chiave di idempotenza e gli stessi argomenti per i nuovi tentativi di rete; non inviare automaticamente un'altra generazione a pagamento dopo un errore.

Per la chat e la generazione immagini con prezzo basato sull'uso, estimate_generation restituisce anche credits_range.min e credits_range.max in crediti V4V, con ricarico e regolazioni di prezzo correnti inclusi. Presentali come un intervallo approssimativo. I suoi assumptions descrivono scenari d'uso illustrativi; il costo effettivo può uscire dall'intervallo, e is_spending_cap è false. credits_estimated e initial_reservation_estimated restano la stima separata della riserva iniziale. Questa anteprima non riserva crediti e non avvia alcuna generazione.

24

Modelli attuali di immagini e chat#

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") supporta 1K/2K/4K e fino a 10 riferimenti. Leggi pricing_by_variant per la sua modalità di fatturazione corrente. La generazione Google/Vertex regola i token effettivi di input, input in cache, output immagine, output testo e thinking, incluso il ricarico; altri instradamenti usano la tariffa immagine configurata. Gemini 4 Argon (chat.gemini_4_argon) include i token thinking nella fatturazione a consumo. Usa estimate_generation per mostrare intervalli approssimativi di crediti; la riserva iniziale e l'intervallo sono separati dall'uso finale e non sono limiti di spesa. Non inventare mai parametri di instradamento e non modificare silenziosamente le impostazioni di amministrazione.

25

Video prodotto Studio in bulk#

Usa generate_studio_bulk quando vuoi video per un elenco di prodotti. Accetta 1–300 elementi e restituisce subito un batch_id. Condivide il normale saldo crediti dell'account e la coda di generazione V4V condivisa con REST e con l'applicazione web.

json
{
  "name": "Autumn product videos",
  "input": {
    "prompt": "Show three benefits in a calm product reveal"
  },
  "parameters": {
    "duration": 8,
    "aspect_ratio": "9:16"
  },
  "max_credits": 600,
  "test_count": 5,
  "items": [
    {
      "sku": "MUG-01",
      "product_id": "0123456789abcdef01234567"
    },
    {
      "sku": "BAG-02",
      "product_url": "https://shop.example/products/bag?variant=blue"
    },
    {
      "sku": "LAMP-03",
      "input": {
        "product_name": "Desk lamp",
        "product_images": [
          "https://shop.example/lamp.jpg"
        ]
      },
      "parameters": {
        "style": "TV Spot"
      }
    }
  ],
  "idempotency_key": "autumn-products-001"
}

L'input e i parametri dell'elemento sovrascrivono le impostazioni condivise; i valori predefiniti di Studio completano il resto. Fornisci ID prodotto di tua proprietà, URL pubblici delle pagine prodotto oppure dettagli e media prodotto preparati. Usa le impostazioni supportate dal modello Studio corrente del deployment. Ometti test_count per elaborare l'intero elenco. Con test_count: 5, i primi cinque elementi (o tutti gli elementi se sono meno di cinque) vengono eseguiti prima che il batch si metta in pausa per la revisione.

StrumentoScopoConsuma crediti di generazione?
generate_studio_bulkCrea un batch di video prodotto con un budget crediti obbligatorioSì, quando ogni elemento inizia
list_studio_batchesElenca i batch più recenti dell'accountNo
get_studio_batchLegge avanzamento paginato, ID attività degli elementi, risultati e un state_token stabileNo
wait_studio_batchAttende una modifica, il completamento, una pausa o un annullamento; valore predefinito 25 secondiNo
control_studio_batchpause, resume, cancel, retry_failed, rework o restart; max_credits facoltativo aumenta il budget cumulativoLa ripresa e i nuovi tentativi possono consumare crediti

DIRECTOR_REQUEST_FAILED identifica il rifiuto della richiesta di testo AI Director; REFERENCE_MEDIA_UNAVAILABLE identifica un problema nella lettura dei suoi file di riferimento. Spiega la fase non riuscita e segnala l'ID dell'attività; non presumere mai che questo significhi che una richiesta di generazione video non sia riuscita e non creare automaticamente un altro tentativo a pagamento.

Gli URL pubblici degli articoli eBay supportano un fallback di importazione protetto nel browser. Se un negozio continua a rifiutare un'importazione, invia un product_id di tua proprietà o dettagli/immagini del prodotto preparati. IMPORT_FAILED si verifica prima dell'ammissione a pagamento e include il motivo di importazione noto; PREPARATION_FAILED identifica un successivo errore di preparazione. Un tentativo non riuscito resta terminale. Quando l'utente richiede un nuovo tentativo, chiama control_studio_batch con action: "retry_failed" e un nuovo idempotency_key; facoltativamente fornisci item_indexes con indice a base zero. Per input corretti o un rifacimento intenzionale, usa action: "rework" con items: [{task_id: "task_…", input: {prompt: "New direction"}}] (oppure usa index: 1 invece di task_id). Usa action: "restart" solo quando l'utente richiede di nuovo tutti gli elementi, compresi quelli riusciti. Queste tre azioni richiedono una nuova chiave per ogni operazione intenzionale; in caso di errori di rete ripeti la stessa chiave e gli stessi argomenti. resume non ritenta i tentativi non riusciti.

Per rifare solo i risultati che non ti piacciono, seleziona i loro items[].task_id correnti e chiama control_studio_batch con action: "rework", quegli ID in items e un nuovo idempotency_key. Ometti le modifiche agli input per eseguire di nuovo lo stesso brief. I risultati correnti selezionati vengono cancellati immediatamente e lo stesso batch riprende l'elaborazione; gli altri elementi completati restano invariati. items[].results descrive sempre l'ultima versione prevista, mentre attempts conserva l'output precedente. Un ID attività sostituita obsoleto restituisce BATCH_ITEM_VERSION_CHANGED; leggi di nuovo il batch prima di una nuova rielaborazione intenzionale.

Monitora un batch nel connettore browser di Claude

Un webhook invia una richiesta HTTP a un ricevitore reale. Non fornisce a questa connessione MCP un modo per riavviare una conversazione browser inattiva di Claude. Non inventare mai un URL di callback e non promettere un futuro messaggio in chat dopo che la conversazione è terminata.

Durante il flusso di lavoro batch richiesto dall'utente, Claude deve monitorare automaticamente:

  1. Mantieni batch_id e state_token da generate_studio_bulk, generate_studio_variants o get_studio_batch.
  2. Chiama wait_studio_batch con batch_id, after_state impostato su quel token e wait_seconds: 25 per i connettori browser. La paginazione facoltativa usa offset e limit (predefinito 50, massimo 100).
  3. Il server restituisce una risposta in caso di modifica significativa del batch, completamento, pausa, annullamento o timeout limitato. Gli heartbeat del worker e le firme dei risultati in scadenza non modificano il token. La risposta contiene la pagina batch aggiornata, changed, timed_out, stop_reason e next_action.
  4. Finché status è running, continua ad attendere con il token restituito senza chiedere all'utente di dire “controlla di nuovo”. Riporta le tappe utili, non ogni timeout senza modifiche. Un timeout non fa fallire né annulla la generazione. Non inviare un batch sostitutivo.
  5. Su completed, riporta risultati ed errori. Su paused, spiega waiting_reason e attendi la decisione dell'utente. Non riprendere mai automaticamente, non aumentare un budget e non ritentare tentativi a pagamento. Anche cancelled termina questo ciclo di monitoraggio.

Questo usa il long polling lato server all'interno di un flusso di lavoro strumenti attivo. Se Claude termina il suo turno, l'utente chiude la conversazione o il client impone un limite di runtime, il batch continua comunque a essere eseguito ma questa connessione non può garantire un nuovo messaggio in chat. Annullare/disconnettere un'attesa interrompe solo l'osservazione, non il batch. Controllare o attendere non consuma crediti di generazione.

wait_seconds accetta da 1 a 240 secondi. Claude Code supporta il passaggio automatico in background delle chiamate MCP lunghe nelle versioni recenti; per un'attesa di 240 secondi, configura timeout di quel server ad almeno 300000 millisecondi e consenti il passaggio della richiesta attraverso i timeout del proxy. I connettori browser devono usare il valore predefinito di 25 secondi. Vedi Claude Code long tool calls. Questo comportamento è specifico del client e non garantisce il riattivarsi del browser.

Webhook batch per ricevitori esterni

Passa callback_url quando crei un batch bulk o delle varianti. Si applicano il segreto di firma webhook della chiave API esistente e la verifica X-V4V-Timestamp / X-V4V-Signature. La destinazione di callback è fissata dalla richiesta di creazione idempotente; dopo errori di rete ripeti lo stesso URL e gli stessi argomenti.

Il worker registra snapshot significativi e consegna batch.updated, batch.completed, batch.paused e batch.cancelled. Gli eventi includono event_id, batch_id, batch_revision, observed_at, state_token, stato, conteggi e totali dei crediti stabili. result_lookup punta a get_studio_batch per file paginati e dettagli delle attività; i payload webhook non incorporano URL di risultati in scadenza. Le transizioni intermedie possono essere accorpate tra i tick del worker.

La consegna usa un outbox durevole con lease e tentativi limitati. La consegna ripetuta ha lo stesso ID evento e lo stesso payload; le firme vengono aggiornate a ogni tentativo. I ricevitori devono deduplicare e tollerare consegne fuori ordine, poi recuperare lo stato batch corrente quando necessario. Gli errori HTTP permanenti fanno abbandonare la consegna; i guasti transitori applicano un backoff. Un ricevitore webhook lento non blocca il worker di generazione/ammissione. Pause, annullamenti con lavoro attivo e successivi riavvii/rielaborazioni richiesti continuano a produrre aggiornamenti. La consegna non avvia mai un altro tentativo a pagamento.

Per letture manuali occasionali dello stato, chiama get_studio_batch ad almeno cinque secondi di distanza; per il monitoraggio attivo da parte di agenti preferisci wait_studio_batch. I singoli tentativi usano il normale strumento get_task per link di download firmati. Questi strumenti continuano l'elaborazione sul server senza che la conversazione o una scheda del browser restino aperte.

Le code bulk riservano solo la stima dell'elemento ammesso successivo. max_credits limita i crediti spesi più le riserve attive. Un saldo o budget insufficiente mette in pausa i nuovi avvii; dopo la richiesta dell'utente, chiama control_studio_batch con action: "resume", aumentando facoltativamente max_credits. Pausa/annulla consente ai tentativi attivi di terminare. I batch annullati non possono riprendere, ma possono riavviare o rielaborare esplicitamente elementi terminali dopo che il lavoro ammesso è terminato. Gli elementi selezionati devono essere terminali (BATCH_ITEMS_ACTIVE); richieste del provider attive o incerte bloccano i nuovi tentativi (GENERATION_UNRESOLVED). NO_FAILED_ITEMS significa che non rimangono errori più recenti. Cronologia, risultati e spesa cumulativa sopravvivono a tutte le operazioni; conteggi e stato degli elementi usano solo le versioni previste più recenti. Le nuove versioni condividono le stesse code e la stessa attribuzione del Registro crediti. Le modifiche facoltative a input/parametri a livello di operazione si uniscono alla richiesta precedente e hanno la precedenza gli override di rielaborazione per elemento. Un gate campione preservato richiede comunque una ripresa esplicita; il riavvio lo rimuove. Vedi il contratto REST per limiti di richiesta/cronologia ed esempi completi. Riutilizza lo stesso idempotency_key e gli stessi argomenti dopo un errore di rete; non creare mai un altro batch per aggirare l'attesa in coda.

Le richieste di generazione condividono al massimo 10 slot attivi tra account e processi applicativi. La generazione ordinaria ha priorità; il bulk usa la capacità residua entro limiti globali e per utente definiti dall'amministratore. Una risposta del provider persa mantiene occupato il proprio slot per la riconciliazione e non attiva mai una richiesta a pagamento duplicata automatica. Gli eventi di crediti API e MCP sono etichettati separatamente nei Registri crediti dell'amministratore.

Questa release fornisce generazione e download individuali tramite API/MCP. Le schermate bulk di Studio del piano più ampio, il caricamento CSV, l'approvazione dei risultati e l'esportazione ZIP restano lavori futuri. Aggiorna l'elenco strumenti del tuo connettore MCP dopo il deployment per individuare i nuovi strumenti batch. Vedi il contratto bulk REST per campi, semantica del budget ed errori.

26

Editor video#

L'editor in /video-editor permette a te e al tuo assistente di lavorare sulla stessa timeline salvata multilivello. Supporta video, immagini/loghi, audio sorgente, livelli indipendenti di musica/voce, testo, sottotitoli temporizzati, rifilo, divisione, velocità, volume, dissolvenze e note di revisione delle take. Il browser fornisce anteprima interattiva ed esportazione locale in MP4/WebM. Apri Video Editor per modificare in modo interattivo; strumenti e limiti sono descritti sotto.

Inizia con get_editor_guide (disponibile anche come risorsa v4v://video-editor). Aggiorna l'elenco strumenti del connettore dopo il deployment.

Per una content factory completa, leggi get_factory_guide / v4v://factory. create_factory_run, list_factory_runs, get_factory_run e submit_factory_stage mantengono i nove ruoli con ritentativi esatti dell'operazione e revisioni distinte di esecuzione/progetto. prepare_factory_review restituisce immagini catturate reali, get_factory_frame le legge di nuovo e preview_factory_audio restituisce un estratto WAV misurato. Ispeziona ogni frame catturato e rivedi movimento/parlato prima di inviare un giudizio. repair_factory_run consente al massimo due correzioni; release_factory_run mette in coda e poi verifica un'esportazione completa privata della Libreria, ZIP modificabile, copertina e REVIEW.md. Questi strumenti richiedono la proprietà del progetto; le scritture richiedono OAuth lettura + scrittura, senza permesso di generazione né addebiti di crediti. La generazione di scene a pagamento resta un'operazione separata con budget. Vedi il contratto della factory ucraina per route HTTP, recupero ed evidenze misurate rispetto a quelle riportate dal revisore.

StrumentoScopo
get_editor_guideContratto della timeline, flusso di lavoro di editing ed esempio di timeline vuota
get_motion_guideAPI motion versionata, schemi effettivi, esempi nativi/HTML, unità di tempo/geometria e ciclo di vita; anche v4v://motion-api
get_editor_troubleshootingGuida di recupero versionata per errori effettivi; anche v4v://troubleshooting; la lettura non esegue mai una riparazione o un tentativo di nuovo
get_project_transfer_guideInteroperabilità ZIP locale/V4V, richieste binarie, permessi e recupero; anche v4v://project-transfer
export_editor_bundlePrepara una richiesta di download binario con ambito limitato per un progetto alla revisione corrente; eseguila per ottenere lo ZIP effettivo
import_editor_bundlePrepara un caricamento ZIP binario con {}, poi recupera il suo nuovo progetto con transfer_id; niente base64 nel testo del modello
get_editor_capabilitiesFormati effettivi, runtime, operazioni locali/condivise e servizi facoltativi
get_creative_library / search_creative_libraryScopri il registro creativo condiviso installato
get_creative_itemSchema esatto di un elemento, esempio originale, percorsi di anteprima, licenza e limiti
get_style_format_guideFormato del pacchetto community solo dati; stesso contenuto di v4v://style-format
create_style_exampleImporta nell'account un nuovo esempio di stile modificabile e il media originale; nessun credito modello
apply_styleAnteprima con dry_run=true, poi conferma alla stessa revisione; i lock e gli override manuali restano
check_editor_projectRevisione strutturale/media P0/P1; ispeziona separatamente frame e audio effettivi
list_editor_projectsTrova progetti dell'editor posseduti/condivisi, filtra scope e leggi i livelli di accesso
create_editor_projectCrea un progetto vuoto o una timeline validata
get_editor_projectLeggi timeline, revisione e URL media rinnovabili
update_editor_projectSalva una timeline completa a una revisione prevista
edit_editor_projectApplica operazioni atomiche di clip/livello/sottotitolo a una revisione prevista
propose_editor_silence_cutsMisura l'audio sorgente effettivo e propone intervalli silenziosi con padding senza modificare; applica esplicitamente i remove_time_ranges rivisti alla stessa revisione per propagare l'effetto su tutte le tracce
propose_editor_audio_duckingMisura stem effettivi voce/musica e automazione proposta; ispeziona RMS prima/dopo, poi applica esplicitamente i set_audio_envelope restituiti alla stessa revisione
get_safe_area_guideProfili di destinazione editoriali versionati e schema personalizzato; anche v4v://safe-areas
inspect_editor_textMisura testo nativo/motion/HTML salvato con i font inclusi e riporta risultati campionati di overflow, sovrapposizione e leggibilità
propose_editor_text_fitPropone il ridimensionamento del font per testo statico senza cambiare parole, tempi o il progetto salvato
propose_editor_scene_layoutPropone limiti espliciti di contenuto motion/HTML e soglia minima del font dal profilo di safe area salvato; rivedi e applica i set_scene_layout restituiti
list_editor_mediaCerca media della Libreria posseduti per tipo e nome
get_editor_mediaIspeziona durata, dimensioni e URL di riproduzione della sorgente posseduta
preview_editor_projectRestituisce fino a sei frame JPEG compositati effettivi per ispezione visiva
get_editor_text_stylesScopri preset di testo/sottotitoli, contorni, motion e reazione al suono
quote_editor_captionsCita la trascrizione del parlato sorgente senza generare
transcribe_editor_mediaAvvia la trascrizione del parlato; consuma i normali crediti dell'account
get_editor_captionsLeggi avanzamento della trascrizione e cue nel tempo sorgente
append_editor_audioAggiungi in append ID di risorse audio ordinati a un livello sbloccato, con pause facoltative
export_editor_projectMetti in coda/recupera MP4, WebM, MP3 o MP4 con copertina statica; restituisce subito export_id
get_editor_exportEsegui il polling di stato/fase e recupera la risorsa completata della Libreria con link rinnovati
get_editor_project_sharingProprietario: elenca i collaboratori e restituisce il link privato del progetto
share_editor_project_with_userProprietario: invita tramite email o modifica l'accesso in lettura/scrittura, facoltativamente con notifica via email
remove_editor_project_accessProprietario: revoca un collaboratore tramite ID utente
transfer_editor_project_ownershipProprietario: trasferisce esplicitamente a un altro account V4V tramite email
share_editor_projectPubblica un link pubblico per il video esportato corrente, quando richiesto esplicitamente

Motion API e recupero

A partire da Kit 0.1.31, get_motion_guide e get_editor_troubleshooting accettano {} e corrispondono esattamente alle loro risorse JSON. Entrambi contengono version e engineVersion; individua gli strumenti del server corrente dopo il deployment. Il loro ambito OAuth V4V è v4v:read. La lettura di queste risorse non modifica, renderizza, ritenta né riserva crediti.

La guida motion contiene schemi effettivi registrati, esempi add_clip nativi e HTML, ciclo di vita deterministico di prepare / renderAt / dispose, tempo locale della scena e regole di geometria frazionaria. In un nuovo progetto vuoto, applica le sue operazioni di esempio alla revisione salvata e visualizza in anteprima i secondi 1 e 5. Nei progetti esistenti, adatta deliberatamente ID traccia/clip e posizionamento. Sono accettate solo scene JSON registrate; la timeline non installa HTML o script arbitrari. Ispeziona i frame effettivi e il motion esportato prima dell'accettazione.

Usa la risoluzione dei problemi con il codice di errore effettivo e lo stato salvato. Un CONFLICT significa ricaricare e preservare le modifiche simultanee; i media mancanti richiedono una fonte reale autorizzata; i font mancanti richiedono un ripristino esplicito. Ispeziona il tentativo di esportazione/inquadratura esistente dopo una risposta sconosciuta. Leggere una procedura di recupero non autorizza mai un nuovo acquisto, un aggiramento dei permessi o il riavvio di un'operazione annullata.

Proposte misurate di layout e audio

I profili safe-area sono guide editoriali versionate, non garanzie ufficiali della piattaforma. set_safe_area_profile mantiene la guida senza modificare i pixel renderizzati. propose_editor_scene_layout la usa per proporre motion.layout espliciti; controlla applicable e il report, poi applica le operazioni restituite tramite edit_editor_project alla stessa revisione. layout:null annulla l'impostazione. Modificare la guida in seguito non adatta nuovamente il contenuto. inspect_editor_text campiona glifi reali/riquadri DOM; il testo incorporato nei media, il ritaglio ruotato, il contrasto sul girato, il movimento completo e l'ascolto restano attività di revisione.

Per la musica sotto la voce, chiama propose_editor_audio_ducking con project_id, revision, voice_clip_ids e music_clip_ids disgiunti effettivi, e facoltativamente options. Le impostazioni predefinite puntano a un margine RMS voce/musica di 12 dB, rilevano attività a −40 dBFS e limitano l'attenuazione a 30 dB. Il servizio mixa le fonti selezionate con i loro trim, velocità, volume e dissolvenze effettivi; inoltre rimixa e misura la musica proposta. Ispeziona comparison di base, after misurato, targetMet, gli avvisi e gli intervalli delle frasi, ascolta, poi applica esplicitamente operations restituito tramite edit_editor_project alla stessa revisione.

L'automazione musicale selezionata viene sostituita anziché sommata; guadagno di base e dissolvenze restano. Le curve sono portabili in ZIP e seguono la loro clip musicale. Ricalcola dopo aver cambiato timing/livello della voce, fonti o posizionamento della musica. Fino a 500 clip vocali e 20 clip musicali, 100 MiB per fonte V4V, 512 MiB totali e 64 clip intersecanti per finestra di analisi; si applicano anche i limiti di risorse/frequenza. L'accesso in lettura consente le proposte, mentre per applicarle serve l'accesso in scrittura. Né la misurazione né la modifica locale consumano crediti. RMS e ampiezza rilevata non dimostrano l'intelligibilità; anche i suggerimenti di quiet-cut richiedono ascolto prima delle modifiche ripple su tutte le tracce.

ZIP portabile tramite V4V MCP

Leggi get_project_transfer_guide / v4v://project-transfer. Entrambi gli host usano lo stesso contenuto .v4v.zip: un bundle.json versionato e i byte originali assets/<sha256>. Solo Kit locale accetta l'argomento directory; V4V rifiuta esplicitamente i percorsi locali del filesystem.

Esporta: chiama export_editor_bundle con project_id e revision corrente, quindi esegui il suo download_request usando l'header con ambito esatto e salva la risposta binaria effettiva. Lo strumento ha preparato una richiesta, non ha ancora creato un file. Il download ricontrolla account/chiave/OAuth, accesso a progetto/media e revisione. La sua risposta contiene X-Content-SHA256; confrontalo con i byte scaricati. Se il progetto è cambiato, rileggi la sua revisione e richiedi deliberatamente un'altra esportazione.

Importa: chiama import_editor_bundle con {}, invia in POST i byte ZIP originali usando upload_request restituito (application/zip, non multipart), poi chiama import_editor_bundle con il suo transfer_id. Questo crea un nuovo progetto, verifica/analizza le fonti e rimappa gli ID delle risorse nidificate. Dopo una conferma persa, recupera lo stesso trasferimento: un'importazione completata restituisce il progetto esistente. Un'importazione interrotta può recuperare il lease scaduto usando i byte originali; un file diverso richiede un nuovo trasferimento. Non inventare mai dati di file e non stampare grandi base64 nel contesto del modello. I client senza accesso a file binari possono usare Studio Apri ZIP del progetto.

Le credenziali di trasferimento scadono dopo 15 minuti; le ricevute restano recuperabili per sette giorni. I token vanno nell'header di richiesta restituito, non in URL, timeline o messaggi pubblici. L'importazione richiede OAuth lettura + scrittura; l'esportazione richiede lettura e accesso al progetto corrente. ZIP e contenuti espansi sono limitati a 100 MiB; si applicano due trasferimenti per processo, corpi di richiesta limitati, lease e limiti di frequenza per utente/richiesta. Importazione/esportazione non eseguono generazione, condivisione pubblica o notifiche. I permessi di condivisione dell'account e le credenziali del modello non viaggiano nello ZIP. Riapri il progetto restituito e ispeziona media/frame effettivi prima della consegna.

Condivisione privata del progetto tramite MCP

L'assistente può completare la condivisione privata senza chiedere all'utente di usare il browser. Se manca l'email V4V del destinatario o il livello di accesso in lettura/scrittura, chiedilo, poi chiama:

json
{
  "name": "share_editor_project_with_user",
  "arguments": {
    "project_id": "169000000000000000000002",
    "email": "collaborator@example.com",
    "access": "write",
    "notify_by_email": true
  }
}

Usa notify_by_email: true solo quando l'utente ha richiesto una notifica email; il valore predefinito è false. Restituisci project_link perché l'utente lo invii e riporta emailNotification con precisione: failed significa che l'accesso è stato concesso ma l'email non è stata inviata. Il link del progetto richiede l'account invitato; i destinatari disconnessi effettuano l'accesso e tornano allo stesso progetto. Non servono esportazione video, generazione o crediti di generazione.

get_editor_project_sharing elenca i collaboratori e i loro userId, email e accesso. Modifica i permessi con share_editor_project_with_user; revoca un utente elencato con remove_editor_project_access e il suo user_id. Trasferisci solo quando l'utente ha richiesto esplicitamente il trasferimento di proprietà e ha fornito l'email del nuovo proprietario. Il vecchio proprietario perde l'accesso; gli altri collaboratori e i riferimenti alle fonti restano. Tutte le chiamate di gestione applicano la proprietà del progetto; inoltre le mutazioni OAuth richiedono v4v:write.

share_editor_project resta un'azione diversa: pubblica il video esportato finito su una pagina di condivisione pubblica. Non usarlo per inviti privati ai collaboratori. Aggiorna/ricollega il connettore MCP dopo la distribuzione per scoprire i nuovi strumenti e istruzioni.

Gli ID progetto dell'editor sono separati dagli ID progetto di generazione Studio/LAB. Usa list_editor_projects, non list_projects, per individuarli. La generazione resta disponibile tramite gli strumenti esistenti di scoperta modelli, stima e generate_lab. Gli file_id dei media completati possono essere usati direttamente come assetId della timeline. Anche la conversione speech-to-text è individuabile come type: "subtitle"; preferisci ai.gemini_3_5_transcribe (Gemini 3.5 Transcribe). I risultati delle sue attività API completate contengono testo, SRT, VTT e cues/words temporizzati in secondi della fonte. Gli strumenti dedicati di trascrizione dell'editor semplificano l'uso di una fonte esistente della Libreria.

Una richiesta tipica dell'agente:

Crea un filmato verticale di 20 secondi dalle mie clip della Libreria. Controlla frame rappresentativi e sostituisci la ripresa distorta con una nuova generazione dopo avermi mostrato il costo. Rifila le inquadrature, aggiungi il mio logo, musica di sottofondo discreta, una voce fuori campo e sottotitoli temporizzati. Salva il video finito nella Libreria e dammi un link per il download.

L'assistente dovrebbe:

  1. Leggere la guida, trovare il progetto e i media sorgente, e ispezionare durate e riproduzione.
  2. Creare o modificare la timeline usando la sua revisione corrente. Aggiungi un logo come immagine su un livello visivo superiore e voce/musica su livelli audio. Il media originale resta invariato.
  3. Usa preview_editor_project per ispezionare i tempi dei frame selezionati. Imposta il review: "keep" o "replace" della clip e registra il motivo in note. I frame non stabiliscono qualità del movimento o del suono; ispeziona anche la riproduzione della fonte.
  4. Individuare/stimare i modelli richiesti, generare sostituzioni con chiavi di idempotenza uniche e attendere i loro ID file completati. Sostituire la fonte della clip selezionata e bloccare trim/durata sulla nuova fonte.
  5. Quotare/trascrivere la fonte vocale originale, eseguire il polling ad almeno cinque secondi di distanza, poi aggiungere cue con sourceClipId per tenere conto di trim e velocità. Controlla il testo della trascrizione. Fornire cue temporizzati esistenti non costa crediti.
  6. Invia la revisione corrente con export_editor_project; esegui il polling di get_editor_export ad almeno cinque secondi di distanza mentre è in coda/rendering. Una richiesta MCP disconnessa non annulla il job. Solo completed con un ID risorsa e URL di download significa successo; ispeziona i guasti prima di riprovare esplicitamente con retry_failed: true. Crea un link di condivisione solo se richiesto.

Esempio di modifica mirata dopo get_editor_project:

json
{
  "project_id": "PROJECT_ID_FROM_CREATE",
  "revision": 3,
  "operations": [
    {
      "type": "update_clip",
      "clipId": "shot-1",
      "changes": {
        "trimStart": 1.5,
        "duration": 3,
        "volume": 0.25,
        "review": "keep"
      }
    },
    {
      "type": "split_clip",
      "clipId": "shot-2",
      "time": 7,
      "newClipId": "shot-2b"
    },
    {
      "type": "add_captions",
      "sourceClipId": "voice-1",
      "cues": [
        {
          "start": 0.2,
          "end": 2.1,
          "text": "A new perspective."
        }
      ]
    }
  ]
}

start/duration usano secondi della timeline, trimStart usa secondi della fonte e lo split time è un tempo assoluto della timeline. Leggi la durata effettiva del media prima di rifilare. add_clip accetta una clip con id univoco, trackId, kind, assetId, start e duration; gli altri campi hanno valori predefiniti. Il testo usa kind: "text" e text invece di una risorsa. I tipi di traccia sono visual, audio o text. add_track, update_track, remove_track e reorder_tracks gestiscono i livelli. Le tracce vengono renderizzate nell'ordine dell'array, con l'ultima sopra. Sovrapponi i livelli visivi e usa dissolvenze per le dissolvenze incrociate.

Il server rifiuta media inaccessibili, tipi di media non corrispondenti, trim non validi e revisioni obsolete. In caso di conflitto di revisione, leggi la nuova versione e riapplica le modifiche volute. Non sovrascrivere il lavoro dell'altro editor. Gli editor del browser aperti e puliti recepiscono automaticamente le modifiche dell'agente; le bozze modificate localmente mantengono le proprie modifiche e mostrano conflitti.

L'ispezione dei frame dell'agente e l'esportazione WebM della timeline visiva richiedono Playwright Chromium nella distribuzione. Queste esportazioni della timeline visiva supportano fino a due minuti e 300 MB di media sorgente e restituiscono un WebM salvato; un'esportazione ripetuta della stessa revisione riusa la sua risorsa esistente. L'esportazione dal browser supporta timeline di dieci minuti e offre MP4 quando il dispositivo dispone di encoder H.264/AAC. Se il rendering fallisce, riporta l'errore e il link dell'editor; non dichiarare un'esportazione riuscita. La modifica/rendering della timeline non consuma crediti modello; generazione/trascrizione sì. La condivisione crea un link visibile a chiunque abbia il link.

27

Gemini text-to-voice#

Usa list_models con type="audio", poi get_model per ai.gemini_3_8_flash_tts o ai.gemini_3_8_flash_lite_tts. Entrambi generano audio WAV con voce singola da fino a 10.000 caratteri parlati:

json
{
  "model": "ai.gemini_3_8_flash_tts",
  "input": {
    "text": "Welcome! <short pause> Let’s get started."
  },
  "parameters": {
    "voice": "Kore",
    "style": "Warm and friendly"
  },
  "idempotency_key": "unique-intentional-generation-id"
}

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.

28

Testo stilizzato, sottotitoli e trascrizione Google#

get_editor_text_styles restituisce 14 preset per sottotitoli, 6 preset per titoli e un fontCatalog con 12 font inclusi più 4 alias di sistema legacy. Ogni preset di sottotitoli reagisce ai veri timestamp delle parole. Usa il preset category e use per scegliere un trattamento: word-pop (Creator punch), caption-marker (Lime marker), caption-underline, editorial (Podcast panel), caption-soft, caption-outline o neon-pulse (Neon glow), oltre ad altri stili di movimento delle parole. I titoli hanno preset propri: title-clean, title-condensed, title-magazine, title-tech, title-sticker e cinema-gold. I nuovi sottotitoli usano per impostazione predefinita Montserrat maiuscolo da 100 px con tre parole per frase. Mantieni uno stile di sottotitoli coerente e uno stile di titoli complementare, contrasto forte e margini di sicurezza. Le timeline salvate esistenti mantengono le loro impostazioni finché non vengono ristilizzate. Vedi il catalogo tipografico completo.

Preferisci gli ID fontFamily inclusi: inter, montserrat, manrope, oswald, rubik, roboto-condensed, unbounded, nunito, playfair-display, roboto-slab, jetbrains-mono, comfortaa. Supportano il latino e il cirillico ucraino e vengono caricati da V4V prima del rendering nell'anteprima e in entrambi i percorsi di esportazione. fontCatalog.weights fornisce l'intervallo supportato di ogni famiglia. I legacy sans, impact, serif e mono dipendono dai font di sistema. Non ignorare mai un errore di caricamento del font dichiarando che l'esportazione è riuscita.

Le clip di testo accettano strokeWidth (0–24 pixel di output), strokeColor, color, fontFamily (ID catalogo), fontWeight (400/500/600/700/800/900, limitato all'intervallo supportato dal font), textBackground, backgroundColor, backgroundOpacity, accentColor, textAnimation, activeWordEffect (none, color, pop, shake, swing, spin, box, underline, glow), activeWordColor (primo piano marker), letterSpacing (-0.06–0.2 em), lineHeight (0.9–1.8), textShadow, shadowColor, shadowBlur, shadowOffsetY, backgroundFit (box o text), backgroundRadius, textTransform (none, uppercase), fontSize, animationIntensity (0–1), audioReactive e audioSourceClipId facoltativo. Le animazioni sono none, fade, slide, pop, float, shake, pulse, color-cycle e karaoke. audioReactive: true usa il volume audio effettivo, inclusi trim, velocità, dissolvenze, volume e tracce mute/nascoste. Segue tutte le fonti udibili salvo quando viene fornito un ID clip sorgente; non rileva i beat musicali. Anteprima, seek, esportazione locale ed esportazione server condividono questo renderer.

Usa edit_editor_project con { "type": "apply_text_style", "clipIds": ["caption-1", "caption-2"], "stylePreset": "creator-pop" } per applicare lo stile a più sottotitoli. Affina con update_clip. add_captions accetta stylePreset, maxWordsPerCaption (1–8, predefinito 3) e words dei cue come { "text": "Hello", "start": 1.2, "end": 1.6 }. Le parole dei cue usano secondi della fonte e sourceClipId le allinea a trim, velocità e posizione nella timeline della fonte. Su una singola clip di testo, wordTimings usa secondi relativi a quella clip. Gli effetti sulla parola pronunciata evidenziano e animano solo la parola pronunciata in quel momento; preserva i timestamp autentici. Le maiuscole cambiano il rendering senza riscrivere testo o tempi originali. SRT fornisce solo il timing dei cue, quindi non inventare mai il timing delle parole a partire da esso.

Per la trascrizione, chiama list_models con type: "subtitle", poi get_model con model: "ai.gemini_3_5_transcribe". Fai un preventivo con estimate_generation e invia la stessa richiesta tramite generate_lab:

json
{
  "model": "ai.gemini_3_5_transcribe",
  "input": {
    "audioUrl": {
      "file_id": "OWNED_AUDIO_ID"
    }
  },
  "parameters": {
    "language_code": "auto",
    "diarize": false
  },
  "idempotency_key": "transcribe-unique-request"
}

In alternativa, fornisci videoUrl con un riferimento video posseduto. Scegli esattamente una fonte, fino a 15 minuti. L'account di servizio Google connesso gestisce l'autenticazione. Non fornire credenziali del provider né parametri di instradamento. Esegui il polling di get_task per results con type: "subtitle"; conserva i suoi cue e i timing delle parole per i sottotitoli dell'editor. Google attualmente contrassegna i timestamp delle parole come sperimentali, quindi controlla l'accuratezza della trascrizione. Gli strumenti di preventivo/trascrizione dell'editor ora usano questo modello per impostazione predefinita. Il legacy ai.speech_to_text resta separato; gli amministratori possono nasconderlo in modo indipendente. Le richieste a pagamento fallite vengono rimborsate tramite il normale ciclo di vita del job e non devono essere ritentate automaticamente come nuovo acquisto.

Completa il flusso di lavoro dei sottotitoli dell'editor

Trascrivere un file non inserisce i sottotitoli in un progetto dell'editor. Per un filmato esistente:

  1. Leggi get_editor_project e identifica la clip sorgente e il suo assetId.
  2. Se hai già un risultato sottotitoli generate_lab / get_task riuscito per questa sorgente, riutilizza il suo cues e passa direttamente all'inserimento nel passaggio 4; non servono un file_id video né una seconda trascrizione. Altrimenti chiama quote_editor_captions, poi transcribe_editor_media con quel asset_id, language: "auto" (o un codice BCP-47) e un idempotency_key univoco. Riutilizza quella chiave dopo un timeout di rete.
  3. Interroga get_editor_captions a intervalli di almeno cinque secondi. In caso di failed, segnala error e interrompi. Un nuovo tentativo a pagamento richiede la richiesta dell'utente.
  4. In caso di succeeded, richiedi cues non vuoto, recupera l'ultima revisione del progetto e passa quegli stessi cue a edit_editor_project con type: "add_captions", il sourceClipId della clip sorgente, stylePreset: "word-pop" e maxWordsPerCaption: 3 (o un altro preset di parole richiesto).
  5. Verifica le nuove clip di testo nella timeline salvata e nell'anteprima in un momento reale dei sottotitoli. Controlla l'accuratezza del testo. Se la sorgente è cambiata durante la trascrizione o c'è un taglio senza parlato sovrapposto, devi segnalarlo; non dichiarare che l'inserimento è riuscito. Riutilizza i cue completati per risolvere i conflitti di modifica senza generarli di nuovo.

Conserva tutti i timestamp restituiti delle parole, inclusi offset di inizio/fine uguali per parole brevi. Rinomina una sovrapposizione con update_clip / changes.name; modifica le parole visibili con changes.text. Rinomina il relativo livello con update_track / changes.name. Conserva gli ID e rispetta i livelli bloccati.

La trascrizione Gemini costa almeno 1 credito per richiesta, incluse le clip brevi; indica il prezzo corrente basato sulla durata prima di generare. Il JSON dei sottotitoli include time_unit: "seconds", un array piatto words e cues[].words, con text, start, end e l'eventuale speaker_id di ogni parola. Usa queste parole per il karaoke e altri stili sincronizzati. L'SRT ha solo il timing delle righe. Laboratorio può mostrare in anteprima le parole temporizzate e copiare/scaricare JSON o SRT. Video Editor accetta direttamente il JSON tramite Sottotitoli → Importa SRT o JSON; scegli uno dei grandi preset per parlato e usa Proprietà clip → Parole e timing per correggere le singole parole senza rimuoverne il timing. Le correzioni MCP devono passare sia changes.text sia il changes.wordTimings corretto completo; cambiare solo il testo cancella il timing obsoleto.

Per accorciare un livello di sottotitoli temporizzati esistente senza un'altra generazione, usa:

json
{
  "project_id": "EDITOR_PROJECT_ID",
  "revision": 3,
  "operations": [
    {
      "type": "reflow_captions",
      "trackId": "CAPTION_TRACK_ID",
      "maxWordsPerCaption": 3
    }
  ]
}

Usa la revisione attuale reale e l'ID del livello. Questo conserva il timing autentico delle parole, lo stile e il livello, e restituisce la timeline aggiornata con nuovi ID clip. Applica un preset di parole condiviso a quegli ID con apply_text_style. Nel browser, usa Proprietà clip → Parole e timing → Parole per sottotitolo → Dividi questo livello in sottotitoli brevi, poi Testo e aspetto → stile → Applica stile al livello. Le righe SRT non possono essere divise accuratamente in parole temporizzate senza trascrizione.

Audiolibri: assembla voci, imposta tag, esporta MP3 o MP4 con copertina

MCP 1.15.0 aggiunge lo stesso flusso di lavoro Audio e audiolibro disponibile in Video Editor. Leggi get_editor_guide per audiobookTimeline, oppure leggi il progetto corrente prima di modificare. Imposta timeline.mode su audiobook per una timeline fino a 7.200 secondi (due ore), 1.000 clip e 24 livelli. La modalità video mantiene il suo limite di dieci minuti/500 clip.

  1. Trova le registrazioni esistenti tramite list_editor_media / get_editor_media, oppure caricale/importale. Genera nuovo parlato solo quando richiesto, usando scoperta del modello, una stima dei crediti e gli strumenti Gemini TTS esistenti. L'editor assembla le registrazioni; non indovina il parlante per ogni riga.
  2. Aggiungi un livello audio per ogni narratore, dialogo, musica o effetti secondo necessità. Usa append_editor_audio con gli asset_ids ordinati, track_id, l'revision corrente e l'eventuale gap_seconds (0–60). Aggiunge clip complete a quel livello senza spazi dovuti all'arrotondamento dei frame. Non ordina mai i nomi file né tronca l'ultima parte per farla rientrare. Per sovrapposizioni o timing personalizzati usa le operazioni clip esistenti. Tagli, velocità, volume, dissolvenze, mute e livelli nascosti influiscono sul mix; cambiare velocità cambia l'intonazione.
  3. Salva tag, bitrate e copertina tramite edit_editor_project, per esempio:
json
{
  "project_id": "<project ID>",
  "revision": 3,
  "operations": [
    {
      "type": "set_audio_settings",
      "mode": "audiobook",
      "settings": {
        "metadata": {
          "title": "Розділ перший",
          "artist": "Олена та Андрій",
          "album": "Книга пригод",
          "albumArtist": "Назва видавництва",
          "composer": "Ім’я автора",
          "year": "2026",
          "track": "1/12",
          "genre": "Audiobook",
          "comment": "",
          "copyright": ""
        },
        "coverAssetId": "<accessible image asset ID>",
        "bitrateKbps": 128
      }
    }
  ]
}

settings sostituisce le impostazioni audio salvate: conserva i campi che l'utente non ha chiesto di cambiare. Tutti i tag sono stringhe. artist registra narratori/interpreti, composer può registrare l'autore, album identifica il libro, year è di quattro cifre e track è un numero o numero/totale. Non inventare crediti o copyright. Un titolo vuoto usa come fallback il titolo del progetto. L'MP3 contiene tag Unicode ID3v2.3 e, se selezionata, un'immagine APIC di copertina frontale. L'immagine è incorporata nel file, anziché essere referenziata tramite URL. L'MP3 può non avere copertina; l'MP4 con copertina ne richiede una. I bitrate sono 96, 128 (predefinito), 192, 256 o 320 kbps.

  1. Invia export_editor_project con la revisione salvata e format: "mp3" o format: "mp4-cover". Richiedili entrambi quando servono entrambi i file. Ogni progetto/revisione/formato ha il proprio job persistente, quindi un formato non sostituisce mai un altro. Interroga get_editor_export a intervalli di almeno cinque secondi fino a completed o failed. Le fasi includono caricamento dei media, mix audio con avanzamento, codifica e salvataggio. Un client disconnesso non annulla il job; un invio ripetuto lo recupera. I job non riusciti richiedono un retry_failed: true esplicito.
  2. Conferma status: "completed", assetId e i link firmati per download/riproduzione. Controlla il mix finale, la durata, i tag richiesti e l'immagine prima di segnalare il completamento. L'MP3 viene salvato come risorsa di Libreria audio; l'MP4 con copertina è una risorsa video. La sola ispezione dei frame non può verificare audio o metadati. Lo strumento pubblico di condivisione video non è per file MP3; la collaborazione privata al progetto resta disponibile.

Il formato mp4-cover mostra una copertina adattata sopra lo sfondo del progetto per l'intera durata dell'audio. Le clip visive della timeline, il testo e i sottotitoli sono esclusi da questo formato. Per renderizzare quelli, usa l'esportazione MCP format: "webm" esistente (predefinita, fino a due minuti) oppure l'esportazione browser MP4/WebM (fino a dieci minuti).

Le esportazioni audio sono solo per il proprietario, non costano crediti di generazione e richiedono il worker persistente dell'editor più FFmpeg/ffprobe con libmp3lame e libx264. Chromium non è necessario per questi due formati. Limiti: 1 GB di file sorgente, 300 MB per file esportato, 64 segmenti di clip audio per finestra di mixaggio di 30 secondi. Usa un bitrate più basso o dividi un libro più grande in parti. Impostazioni e riferimenti alla copertina persistono nella timeline, sono controllati per revisione e seguono i permessi media del progetto dopo condivisione o trasferimento di proprietà. Questa release non aggiunge indicatori di capitolo, clonazione vocale o assegnazione automatica del parlante.

Galleria e pacchetti di stili condivisi

/video-editor/gallery e il pannello Design mostrano gli stessi 30 pacchetti di stili nativi originali del Kit locale. Ognuno contiene cinque scene modificabili, un'anteprima silenziosa di 12 secondi, illustrazione originale etichettata, prompt, rubrica e manifesto hash. Questa è una dimostrazione riutilizzabile di famiglia di scene, non una campagna prodotto fattuale. I percorsi di anteprima da get_creative_item sono relativi a /api/video-editor/creative-assets/; contengono solo materiale originale incluso nel pacchetto, mai media dell'account.

create_style_example importa l'immagine sorgente reale nella Libreria del proprietario connesso e rimappa l'ID media della timeline. Usa v4v:write, senza crediti di generazione. Anche apply_style(dry_run=true) richiede accesso di modifica e la revisione corrente, segnala clip modificate/bloccate/non supportate e non esegue scritture. Applica con gli stessi parametri e revisione dopo aver esaminato il piano. L'ambito scena selezionata modifica la transizione in ingresso di quelle scene; i tempi delle clip e l'audio restano fissi.

Budget di generazione limitato per Open Video Kit

create_generation_budget crea un limite condiviso immutabile senza addebitare; get_generation_budget legge la spesa effettiva e le prenotazioni, close_generation_budget chiude definitivamente le nuove indennità. Per i media supportati, estimate_generation restituisce un quote_token firmato valido per cinque minuti. Passa budget_id, max_credits e quote_token insieme nell'attuale generate_lab / generate_studio; idempotency_key è obbligatorio. Le ripetizioni esatte di richieste accettate non attivano una seconda generazione. Le prenotazioni parallele vengono contabilizzate sul server; la chat a prezzo per token è esclusa da questo percorso. Il budget non è un'autorizzazione autonoma dell'utente a spendere crediti. Contratto dettagliato e validazioni: Cloud Kit.

Stili di riferimento privati (Open Video Kit 0.1.24)

get_reference_guide / v4v://reference-style documenta il flusso di lavoro condiviso. analyze_reference_style accetta un reference_id stabile, una risorsa di Libreria posseduta (source: { type: "asset", assetId }) o un URL video|image|page pubblico esplicito. Restituisce palette misurate, confini/ritmo provvisori e tempi frame reali; get_reference_frame restituisce contenuto PNG. Ispeziona tutti i frame registrati prima di review_reference_style, che richiede regole originali di tipografia/layout/movimento/transizione/ritmo, token completi, limitazioni del revisore e citazioni di tempo/SHA-256. get_reference_profile restituisce JSON portabile privato. apply_reference_style usa dry run per impostazione predefinita; per il commit è richiesta la revisione corrente di un progetto posseduto, inclusa la revisione zero. Il girato di riferimento non viene mai incorporato nel montaggio o nello ZIP.

Gli strumenti di lettura richiedono v4v:read; analisi/revisione/applicazione richiedono v4v:read e v4v:write. Non richiedono v4v:generate né consumano crediti di generazione. I file di evidenza di riferimento/factory V4V sono crittografati con chiavi per oggetto conservate solo in manifest del database limitati al proprietario, e i file privati sono bloccati dalla consegna generica delle risorse. La proprietà originale della Libreria di riferimento viene verificata all'accesso. Vedi implementazione e limiti in ucraino.

Maschere geometriche per clip e parallasse a livelli

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 e recipes.parallax sono condivisi con Studio locale. Quest'ultimo fornisce movimento modificabile a due livelli usando normali keyframe di posizione. Visualizza in anteprima i frame reali; non è stima automatica della profondità. I controlli GUI condivisi si trovano in Design → Effetti. ZIP conserva le maschere; l'ispezione del testo restituisce TEXT_MASK_REVIEW perché i controlli dei limiti non possono garantire la leggibilità dentro una maschera curva. Vedi il contratto bilingue condiviso.

29

Raccolte creative e pianificazione dell'agente#

Design → Librerie fornisce 28 composizioni native modificabili, tra cui collage, movimento continuo della camera, pannelli a molla, personaggi dipinti, sottotitoli, walkthrough di prodotti e sequenze di lancio. Kit 0.3.7 include anche dieci stili originali, cinque effetti raster e quindici transizioni. Le tredici transizioni shader richiedono WebGL e producono fino a 4096 pixel per lato.

Usa get_reviewed_library_guide (risorsa v4v://reviewed-libraries) per schemi esatti, licenze delle fonti e limiti. search_library_references e get_library_reference espongono 456 voci di metadati di riferimento; non sono modelli eseguibili installati. plan_library_scene è di sola lettura e restituisce operazioni per edit_editor_project alla revisione corrente. Usa media di Libreria posseduti o media di progetto locale registrati; i byte locali originali restano sul dispositivo dell'utente. Ispeziona i frame realmente renderizzati dopo la modifica.

Pianifica con AI salva il progetto e prepara una richiesta Video Factory modificabile. Non invia un comando, non spende crediti, non carica originali e non autorizza la generazione. L'agente chiarisce le scelte creative mancanti rilevanti prima di modificare. Il rendering nativo non richiede alcun servizio di generazione; le azioni a pagamento facoltative mantengono preventivi esistenti e approvazione esplicita. Nessun installer upstream, HTML/JavaScript arbitrario, musica eseguibile o lettore della cronologia locale è abilitato. Revisione di fonti/licenze ed equivalenti originali sono inclusi nella documentazione del Kit versionato.

Qualità del montaggio ed evidenze

Leggi get_montage_quality_guide / v4v://montage-quality per regole di gusto condivise e limiti onesti delle evidenze. plan_montage_beats ricava tagli visivi allineati ai frame da timing reali delle parole; plan_compact_captions raggruppa 1–3 parole senza inventare timestamp. analyze_ui_regions misura i confini di screenshot posseduti; rectify_ui_region crea un'immagine separata corretta prospetticamente da un fingerprint/ID regione restituito. detect_media_scenes misura i tagli visivi in una finestra sorgente fino a 600 secondi. Queste operazioni conservano la sorgente e non generano media a pagamento.

compare_narration_transcript richiede una run_id di trascrizione posseduta completata dell'esatto audio_asset_id; confronta la trascrizione reale con script ed eventuali nomi confermati. Il testo ASR non stabilisce accento di pronuncia o naturalezza dell'interpretazione. Acquista trascrizione o un nuovo take solo tramite il consueto flusso di autorizzazione con preventivo.

preview_editor_project accetta fino a 12 times di frame reali; contact_sheet: true restituisce un'immagine per revisione. La modalità browser Factory esegue ispezione/rettifica sul dispositivo dell'utente e mantiene gli originali in locale. I chiamanti MCP esterni che usano un originale solo browser ricevono BROWSER_REQUIRED; usa l'agente Factory aperto per quelle operazioni browser. I nuovi comandi Factory registrano risposte separate di revisione contenuto/finitura per otto domande esplicite sulle evidenze. Evidenze sconosciute non costituiscono una revisione superata.

I risultati get_task non riusciti includono error.provider_error, il motivo sanitizzato del servizio del modello e error.provider: "managed". I fallimenti noti includono un hint e retryable; anche limiti di frequenza/timeout transitori restituiscono retry_after_seconds: 60. Leggi il motivo prima di modificare la richiesta o chiedere un altro tentativo a pagamento. Gli errori sconosciuti conservano il loro motivo sanitizzato senza presumere che un nuovo tentativo funzionerà. Le risposte ai task REST e i callback firmati task.failed usano gli stessi campi; vedi diagnostica delle generazioni non riuscite.