Ir a la documentación
v4v.Documentación para desarrolladoresPREVIEWTus claves de API ↗
EN ESTA GUÍA
Conecta tu asistenteAutorización OAuth 2.1ChatGPT (OAuth)Claude WebVS CodeClaude CodeCursorCodex CLIGemini CLIOpenCodeOtros clientes MCPEmpieza con un resumenHerramientas disponiblesReutiliza contenido de la biblioteca y previsualiza el costeVariantes, nombres de proyecto y ejemplosOrganiza proyectos existentesMedios y generaciónRecuperar el resultadoWebhooks de finalizaciónCréditos y accesoResolución de problemasModelos de vídeo Kling 4.0Chat GPT-6 AstraModelos actuales de imagen y chatVídeos de producto masivos de EstudioEditor de vídeoGemini text-to-voiceTexto con estilo, subtítulos y transcripción de GoogleColecciones creativas y planificación de agentes
Disponible para pruebas
Vista previa de acceso directo
MCP connection guide

Crea desde tu asistente de IA.

Inicia sesión con OAuth 2.1 o conéctate con una clave de API. Descubre modelos, crea con medios de referencia, monta ediciones multicapa y lleva vídeo, imágenes y audio terminados a tu conversación.

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

Conecta tu asistente#

Para una configuración guiada, elige tu asistente en la página de conexión de MCP.

V4V MCP permite que un asistente de IA descubra modelos de generación, trabaje con medios de referencia, cree imágenes, vídeo, audio y respuestas de chat, y recupere resultados. Usa la misma cuenta, créditos e historial de generación que la API de V4V.

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

Transporte: HTTP con transmisión

Autenticación: inicio de sesión OAuth 2.1 en despliegues habilitados, o una clave de API en clientes que admiten encabezados de solicitud personalizados. Ambos usan tu cuenta y créditos existentes de V4V.

Usa el dominio de tu despliegue en lugar de v4v.ai al probar otro entorno. El servidor ya está alojado; no necesitas ejecutar un proceso local.

Inicia sesión 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.

Conéctate con una clave de API

  1. Abre tu perfil de V4V y crea una clave en API Keys.
  2. Guarda el secreto de la API en la configuración segura de tu cliente MCP.
  3. Añade el servidor con x-api-key: YOUR_V4V_API_KEY o Authorization: Bearer YOUR_V4V_API_KEY.
  4. Conéctate y empieza con get_balance o list_models.

Envía un encabezado de autenticación. Si se envían ambos, deben contener la misma clave; unas credenciales en conflicto o mal formadas devuelven HTTP 401. El valor de x-api-key es la propia clave, sin prefijo Bearer . Ambos formatos de encabezado de clave de API usan los mismos permisos, créditos, límites de tasa y revocación de clave.

Los clientes con clave de API siguen usando los mismos encabezados y permisos. Los clientes OAuth inician sesión en su cuenta existente de V4V a través del navegador. No pegues nunca una clave o token en una conversación con un asistente ni lo subas a un repositorio.

02
V4V / MCP connection guideCrea algo que merezca la pena ver.

Autorización 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.

El asistente detecta los endpoints de OAuth desde el servidor y utiliza PKCE para completar el inicio de sesión. No crees una clave de API ni pegues un bearer token para este flujo. El ejemplo de OAuth al principio de esta página solo contiene el transporte HTTP y la URL del servidor; cada cliente tiene su propio formato de configuración.

Conectarse no consume créditos. Las generaciones usan tu saldo existente de V4V. Los tokens de acceso duran como máximo una hora y se renuevan automáticamente cuando el cliente lo admite. La conexión caduca al cabo de 30 días; vuelve a conectarte entonces o después de revocar el acceso. Gestiona y desconecta sesiones en Perfil de V4V → Conexiones de asistentes. Los trabajos ya enviados siguen ejecutándose después de la desconexión.

Si OAuth no está disponible en tu despliegue, pide a su operador que active las conexiones de asistentes, o usa una clave de API en un cliente compatible.

03

ChatGPT (OAuth)#

OAuth debe estar activado primero en el despliegue de V4V. Los permisos de cuenta y espacio de trabajo en ChatGPT determinan si hay disponible una conexión MCP personalizada.

  1. Abre ChatGPT Plugins → Personal, elige Add (o +) y luego Add custom MCP server (la etiqueta puede variar según la cuenta).
  2. Introduce V4V y la URL del servidor https://v4v.ai/api/mcp.
  3. Elige OAuth y el registro dinámico de cliente (DCR). Deja Client ID y Client Secret vacíos; V4V registra automáticamente un cliente PKCE público. Esta versión admite DCR, no CIMD.
  4. Conéctate e inicia sesión con tu acceso existente de V4V.
  5. En la pantalla de permisos de V4V, revisa la cuenta y el host de callback. Los tres permisos son obligatorios: leer la cuenta, editar/subir y generar con créditos. Las tres casillas están seleccionadas y bloqueadas. Elige Accept all permissions para conectarte, o Cancel para rechazar; no se admite el consentimiento parcial.
  6. Vuelve a ChatGPT e instala el plugin si se te pide. En los plugins personales, abre el menú de tres puntos de V4V y elige Manage.
  7. Abre la fila Permission. Para llamadas a herramientas sin aprobación, elige Allow all tools. Las generaciones siguen usando tus créditos de V4V, así que pide una estimación antes de empezar.
  8. Inicia una nueva conversación, elige + → Plugins → V4V (o menciónalo con @) y pide Check my V4V balance.

La guía con capturas de pantalla de ChatGPT recorre las ocho pantallas. Su paso de detalles de conexión incluye botones para copiar el nombre del plugin, la descripción y la URL del servidor del despliegue actual, además de una descarga opcional del icono de V4V.

Ejemplo:

Crea tres conceptos de vídeo de producto verticales 9:16 a partir de este enlace de producto. Muestra primero los conceptos y los créditos estimados. Espera mi aprobación antes de iniciar la generación.

El asistente utiliza las herramientas existentes de descubrimiento, estimate_generation y generate_studio_variants. Las estimaciones no renderizan ni reservan créditos, pero pueden importar medios para su validación y, por tanto, requieren el permiso de edición. Las herramientas de pago aplican el permiso de generación en el servidor. El permiso es de acceso a la cuenta, no la aprobación de un briefing creativo individual: aun así, revisa los conceptos solicitados y el presupuesto antes de autorizar un renderizado. Los controles de lote max_credits e idempotencia siguen aplicándose.

Los tokens de acceso duran como máximo una hora. Los tokens de actualización rotan al usarse y la conexión caduca al cabo de 30 días. Vuelve a conectarte cuando caduque o cuando se necesiten permisos adicionales. En Perfil de V4V → Conexiones de asistentes, revisa el uso, desconecta el asistente o muestra su secreto de firma de webhook para tu receptor. No pegues el secreto de firma en el chat.

Al desconectar se bloquean las nuevas solicitudes de herramientas, la renovación de tokens y los enlaces de subida no utilizados. Los trabajos ya enviados siguen adelante según las reglas existentes de cola y créditos; desconectar no los cancela ni los reembolsa. Los enlaces multimedia firmados emitidos anteriormente conservan su caducidad normal.

Las subidas de archivos desde el entorno de ejecución de ChatGPT dependen de la red y del acceso a adjuntos de ese entorno. El enlace de subida en navegador con ámbito limitado sigue estando disponible como alternativa. La conectividad MCP por sí sola no garantiza la transferencia automática de adjuntos.

Las pruebas de conexiones personalizadas y la publicación pública de plugins son pasos independientes. Consulta la guía de conexiones MCP de OpenAI, los requisitos de OAuth y los requisitos de revisión pública.

04

Claude Web#

Conexión OAuth

Abre Add to Claude. El formulario se abre con el nombre de V4V y la URL del servidor de producción ya rellenados. Para dev u otro despliegue, usa la página de conexión, que completa la URL de ese despliegue. Si al iniciar sesión en Claude se borra el formulario, vuelve a abrir el enlace después de iniciar sesión.

Sigue la guía de seis pasos con capturas de pantalla junto con Claude:

  1. Revisa el nombre y la URL ya rellenados y luego elige Continue.
  2. Claude comprueba el servidor automáticamente. Mantén la configuración detectada Sign in now y Register automatically y elige Add; no hace falta cambiar ninguna otra opción. Deja Client ID y Client Secret vacíos, sin clave de API ni encabezados de solicitud.
  3. En la página del conector, elige Connect e inicia sesión en V4V.
  4. Revisa tu cuenta y los tres permisos obligatorios, y luego elige Accept all permissions. Conectarse no consume créditos.
  5. En Tool permissions → Read-only tools, abre Custom junto al nombre del grupo y elige Always allow.
  6. Desplázate hasta Write/delete tools y elige también Custom → Always allow para ese grupo. Activa V4V en una conversación y pide Check my V4V balance. Las generaciones usan tus créditos de V4V; pide una estimación primero.

Los permisos de herramientas de Claude son independientes de la autorización de cuenta de V4V. Los menús de grupo te permiten autorizar las herramientas sin cambiar cada una individualmente. Puedes revisar estas opciones en la configuración del conector de Claude.

Los callbacks alojados de Claude en claude.ai y claude.com son compatibles sin configuración adicional del entorno. Usa Register automatically; la identidad de cliente publicada (CIMD) de Claude no está implementada en esta versión. Las conexiones existentes con clave de API siguen funcionando como se describe a continuación.

Si se muestran opciones de transporte, usa Streamable HTTP. Añadir un conector y autorizar su acceso a la cuenta son pasos independientes cuando Claude los presenta de esa forma.

Alternativa con clave de API: crea tu clave de API de V4V

Abre tu perfil de V4V, ve a API Keys y crea una clave. Tenla preparada para el encabezado del conector de abajo.

2. Añade el conector

  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:
Configuración del encabezadoValor
Namex-api-key
ValueTu clave de API de V4V, exactamente como la copiaste
  1. Haz clic en Add / Connect y espera a que se complete la conexión.

Usa solo la clave en x-api-key, sin prefijo Bearer . No sign-in omite OAuth; el encabezado sigue autenticando todas las solicitudes a V4V. Deja OAuth Client ID y Client Secret vacíos.

3. Autoriza las herramientas

  1. Abre el Connectors manager de Claude.
  2. Selecciona el nuevo conector V4V.
  3. Abre Tool permissions y autoriza todas las herramientas de V4V.
  4. Confirma que create_upload_link, get_upload, get_model y generate_lab están disponibles y activadas.

Después de que V4V añada o actualice herramientas, actualiza las herramientas del conector o vuelve a conectarlo antes de iniciar una conversación nueva.

4. Permite las subidas automáticas de archivos

  1. Abre Settings → Capabilities.
  2. Activa Code execution and file creation y Allow network egress si están desactivadas.
  3. En Domain allowlist, añade estas entradas:
text
v4v.ai
*.v4v.ai
*.v4vcdn.space

Mantén tanto el dominio raíz como la entrada comodín para que queden cubiertos el dominio de la aplicación y sus subdominios. Introduce solo los nombres de dominio, sin https:// ni /api/mcp, y guarda los cambios. Si tu espacio de trabajo gestiona esta configuración de forma centralizada, pide a su administrador que actualice la lista de permitidos.

Esto permite que el entorno de ejecución de Claude envíe el adjunto original directamente a V4V usando el permiso de subida de corta duración emitido por MCP. Sin esta configuración, el conector puede funcionar mientras las subidas de archivos fallan con host_not_allowed.

Pruebas en dev: usa https://h4000.kitpes.com/api/mcp como URL del conector y añade h4000.kitpes.com por separado a la lista de permitidos de dominios. Las entradas de dominio de V4V no cubren el nombre de host dev.

5. Inicia una nueva conversación

Activa el conector de V4V en un chat nuevo, adjunta tu imagen y pide:

Mejora esta imagen 4× con V4V. Sube el archivo original automáticamente y luego usa su ID de archivo con el modelo Topaz.

Claude debería obtener un permiso de subida a través de MCP, transferir el archivo desde su entorno de ejecución sin copiar base64 en el chat y enviar la generación. No necesitas volver a subir el archivo en una página del navegador aparte cuando el acceso a red está permitido.

Para los controles generales de conectores y red de Claude, consulta gestión de conectores y ejecución de código y acceso a la red.

05

VS Code#

Inicio de sesión con OAuth

Usa Install in VS Code en la página de conexión, o añade esto a .vscode/mcp.json:

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

Inicia el servidor, revisa el aviso de confianza y completa el inicio de sesión en V4V cuando VS Code abra tu navegador. Activa las herramientas que quieras usar en el chat del agente.

Alternativa con clave de API

Para el chat del editor, añade lo siguiente a .vscode/mcp.json. VS Code te pedirá la clave y ocultará la entrada. Mantén el marcador de posición en el archivo.

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

Inicia el servidor desde la configuración de MCP y activa sus herramientas en tu sesión de chat. Revisa la llamada a la herramienta de generación antes de permitir que consuma créditos.

Para otros entornos de agente de VS Code, sigue la referencia actual de configuración de MCP para la ubicación de configuración compatible con ese entorno.

06

Claude Code#

Inicio de sesión con OAuth

Registra el servidor remoto sin un encabezado de autenticación:

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

Inicia Claude Code, ejecuta /mcp, elige V4V y autentícate. Completa la pantalla de permisos de V4V en tu navegador y luego vuelve a la CLI.

Alternativa con clave de API

Configura V4V_API_KEY de forma segura en el entorno de tu shell y luego registra el servidor remoto:

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

Usa /mcp dentro de Claude Code para inspeccionar la conexión. El registro guarda el encabezado configurado en la configuración local del cliente; protege ese archivo y mantenlo fuera del control de código fuente. Consulta la guía de MCP de Claude Code para ver el alcance de la configuración y la gestión de claves.

07

Cursor#

En la página de conexión, elige el inicio de sesión de V4V o la clave de API y haz clic en Install in Cursor. Revisa la instalación en Cursor antes de aceptarla. OAuth abre un inicio de sesión en el navegador; la configuración con clave de API instala un marcador de posición que sustituyes localmente en .cursor/mcp.json. No se incrusta ninguna clave real en la URL de instalación. Las versiones actuales de escritorio usan un callback HTTP loopback; los clientes en la nube usan la URI https://www.cursor.com/agents/mcp/oauth/callback exacta aprobada.

08

Codex CLI#

Para OAuth, añade el servidor e inicia sesión:

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

Para una clave de API, configura V4V_API_KEY de forma segura en tu entorno y luego ejecuta:

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

Gemini CLI#

Añade el servidor remoto con gemini mcp add --transport http v4v https://v4v.ai/api/mcp. Ejecuta /mcp auth v4v dentro de Gemini CLI para OAuth. Para la configuración con clave de API, configura V4V_API_KEY de forma segura y añade el servidor con gemini mcp add --transport http --header "x-api-key: $V4V_API_KEY" v4v https://v4v.ai/api/mcp. La CLI guarda el encabezado configurado; mantén privada su configuración.

10

OpenCode#

Añade un servidor remoto en mcp.v4v dentro de opencode.json con type: "remote", url: "https://v4v.ai/api/mcp" y enabled: true. Ejecuta opencode mcp auth v4v para OAuth. La página de conexión proporciona el JSON completo y una alternativa con clave API mediante variable de entorno.

11

Otros clientes MCP#

Elige un servidor remoto / Streamable HTTP y proporciona:

ConfiguraciónValor
Nombrev4v
URLhttps://v4v.ai/api/mcp
Autenticación (elige una)x-api-key: YOUR_V4V_API_KEY o Authorization: Bearer YOUR_V4V_API_KEY

Los formatos de configuración varían según el cliente. Configura la cabecera en los ajustes secretos del cliente, no en un mensaje de chat. Los clientes heredados solo con SSE no son compatibles. Los clientes OAuth nativos compatibles usan callbacks HTTP en localhost o 127.0.0.1 con un puerto local explícito. El registro y la autorización vinculan exactamente la URL completa de callback. Los callbacks alojados para Claude, ChatGPT, Cursor y VS Code están aprobados; otros clientes alojados necesitan URL exactas en MCP_OAUTH_REDIRECT_URIS.

12

Empieza con un resumen#

Para una película completa o una reedición creativa de una grabación, resuelve las decisiones importantes que falten antes del montaje o del trabajo de pago: objetivo, audiencia, material de origen, formato, duración objetivo, tratamiento visual, subtítulos, voz, música e idiomas de salida. get_started acepta opciones de request_kind (production, creative_edit, targeted_edit) y elecciones confirmadas de creative_brief; devuelve videoBrief.productionQuestions y readyForProduction. Reutiliza las respuestas proporcionadas y las delegaciones explícitas. Un recorte o corrección preciso solo necesita detalles relevantes para ese cambio. La aprobación automática del gasto no proporciona respuestas creativas. Estas reglas las comparten V4V MCP y Open Video Kit 0.3.6.

Puedes empezar con una solicitud como:

Busca un modelo para un vídeo vertical de ocho segundos de mi taza de cerámica. Usa esta imagen del producto: https://example.com/mug.jpg. Muéstrame un concepto y las entradas necesarias antes de generar.

Si no se indica ningún modelo, el asistente debe usar Google/Gemini Omni Flash v1.2 por defecto (video.gemini_omni_flash-1-2), inspeccionar su esquema y disponibilidad actuales con get_model, comprobar el saldo y preparar las entradas. Cuando solicites la generación, enviará una tarea y comprobará el resultado finalizado. Esta regla es la primera en las instrucciones de inicialización de MCP y se repite en las descripciones de list_models, get_model y generate_lab. El descubrimiento de modelos de vídeo devuelve default_video_model; el modelo seleccionado anuncia default_for_unspecified_video: true. Las elecciones explícitas de modelo o de Estudio/flujo de trabajo masivo tienen prioridad.

Para solicitudes de vídeo normales sin un modelo explícito, prioriza generate_lab con video.gemini_omni_flash-1-2. El asistente no debe pedir al usuario que elija un modelo solo porque se haya omitido. Las elecciones explícitas de modelo y los flujos de trabajo de Estudio/masivos solicitados explícitamente tienen prioridad. get_model sigue siendo obligatorio antes de seleccionar entradas y parámetros; si el modelo preferido está desactivado, no está disponible o no es adecuado, explica la limitación y pregunta por una alternativa en lugar de gastar créditos en otro sitio sin avisar. El enrutamiento del proveedor lo configura V4V, no es un parámetro de generación. Usa generate_studio para un flujo de trabajo de Estudio solicitado explícitamente; el descubrimiento de imagen, audio, traducción y chat no cambia.

El prompt de video_brief ayuda a convertir un objetivo, una audiencia y un formato en un plan de tomas. El recurso v4v://guide explica el flujo de trabajo de generación a tu asistente.

13

Herramientas disponibles#

HerramientaFinalidad¿Crea una generación?
list_modelsDescubrir modelos habilitados; opcionalmente filtrar por imagen, vídeo, audio o chatNo
get_modelLeer las entradas, opciones y límites de un modelo; model: "studio" también funcionaNo
describe_studioDescubrir los estilos, duraciones, formatos, calidad, voces y límites de medios actuales de EstudioNo
list_productsEncontrar productos de tu propiedad; reutiliza sus ID como input.product_id de EstudioNo
list_avatarsEncontrar avatares públicos activos y de tu propiedad; reutiliza sus ID como input.avatar_id de EstudioNo
estimate_generationValidar y presupuestar una solicitud de LAB/Estudio sin renderizar ni reservar créditosNo
get_balanceComprobar los créditos disponibles de la cuentaNo
get_usageEncontrar tareas de generación recientesNo
get_fileInspeccionar un archivo de referencia de tu propiedadNo
import_mediaGuardar una URL de medios pública en tu bibliotecaNo
create_upload_linkEmitir una solicitud de carga HTTP con alcance; enlace en navegador disponible como alternativaNo
get_uploadRecuperar el estado de la carga y el ID del archivoNo
upload_mediaCarga programática de bytes en línea; evita base64 grande en el texto del modeloNo
generate_labCrear con un modelo específicoSí — gasta créditos
generate_studioCrear un vídeo a partir de un producto o brief creativoSí — gasta créditos
get_taskComprobar estado, ID de proyecto, ID de medios estables y enlaces firmados renovablesNo
refresh_task_resultsRenovar URL firmadas de resultados sin renderizarNo
list_projectsEncontrar proyectos de Estudio, flujo de trabajo, LAB y API en cola de tu propiedad por título, fuente o carpetaNo
rename_projectRenombrar un proyecto de tu propiedad o el proyecto futuro de una tarea en colaNo
list_project_foldersEnumerar las mismas carpetas que se muestran en el espacio de trabajo ProyectosNo
create_project_folderCrear una carpeta del espacio de trabajoNo
rename_project_folderRenombrar una carpeta manteniendo sus proyectosNo
move_projectAsignar una carpeta de tu propiedad, o usar folder_id: null para quitarla de la carpetaNo
generate_studio_variantsPoner en cola 2–3 variantes creativas usando el presupuesto y los controles masivos existentesSí — cuando empiezan las variantes
promote_to_exampleSolo administradores de ejemplos: copiar/actualizar el ejemplo de un proyecto de tu propiedad con visibilidad explícitaNo

El descubrimiento de Estudio lee el flujo de trabajo seleccionado y los estilos activos de esta implementación; no codifica de forma fija siete nombres de estilo ni asume que cada flujo de trabajo tenga un límite de diez segundos. get_model con model: "studio" es un alias de describe_studio. Las instrucciones esenciales también están en las descripciones de las herramientas para clientes que no pueden leer v4v://guide.

Los esquemas de modelo proceden del mismo catálogo que usa V4V LAB. Pide get_model antes de elegir parámetros; las referencias, duraciones y formatos requeridos varían según el modelo.

14

Reutiliza contenido de la biblioteca y previsualiza el coste#

Llama a list_products o list_avatars (offset y limit opcionales, máximo 100). Los avatares usan source: "all" por defecto; hay disponibles filtros owned y public. El next_offset devuelto es null en la última página. Los ID de avatares públicos incluyen public:; conserva este prefijo. Cada registro incluye photo_count; Estudio usa la foto principal del avatar. Solo se devuelven los registros privados de tu propia biblioteca.

Usa input.product_id y input.avatar_id en generate_studio o estimate_generation. parameters.avatar también acepta el ID de avatar devuelto y sigue admitiendo un ID de archivo o una URL de imagen pública. Elige input.avatar_id o parameters.avatar. Las fotos de la biblioteca se resuelven directamente sin descargarlas y volver a subirlas. Las entradas explícitas de nombre, descripción o imagen del producto sustituyen los valores predeterminados del producto guardado. Los ID/nombres de estilo activos usan sus instrucciones creativas guardadas; los ID/nombres de estilo desconocidos o inactivos devuelven INVALID_PARAMETER con allowed_values. Pon las indicaciones creativas de texto libre en input.prompt y elige un preajuste activo (u omite el estilo para usar el predeterminado descubierto).

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

Envía eso a estimate_generation. Devuelve credits_estimated, reserva cero créditos y no crea ninguna tarea ni renderizado. Los presupuestos de Estudio omiten el registro de personajes del proveedor, incluso cuando se selecciona un avatar. Las URL de medios públicos se pueden importar para la validación. Los presupuestos pueden cambiar según las entradas/Precios; los presupuestos de chat describen una reserva inicial, no los costes finales de tokens ni un límite de gasto. Para renderizar, elimina source y envía las mismas entradas a generate_studio con un nuevo idempotency_key.

15

Variantes, nombres de proyecto y ejemplos#

generate_studio_variants acepta name, input/parameters compartidos, un max_credits obligatorio, idempotency_key y variants que contiene dos o tres objetos con sustituciones opcionales de entradas/parámetros. Por ejemplo: variants: [{parameters: {style: "UGC"}}, {parameters: {style: "Product Review"}}]. Cada variante es un intento de pago independiente. Esto es un envoltorio sobre la cola por lotes existente de Estudio: devuelve batch_id, usa get_studio_batch para los resultados y los mismos controles de pausa/presupuesto/retrabajo. Nunca evita los límites de capacidad.

Usa rename_project con el project_id devuelto por list_projects, generación o get_task, y project_name (recortado, de 1 a 200 caracteres). El cambio de nombre también actualiza el título de la tarea y el historial de LAB, incluso cuando un proyecto todavía está esperando a crearse. No cambia el hash de solicitud de idempotencia original.

Solo los administradores de ejemplos descubren promote_to_example. Acepta un project_id de tu propiedad con un resultado guardado, un active obligatorio y surfaces: ["dashboard", "studio", "landing"] (elige cualquier subconjunto). studio se corresponde con la marca de visibilidad existente de ProVid/Estudio. active: false oculta el ejemplo en todas partes independientemente de la selección de superficie. El resultado incluye visible_on para que la visibilidad efectiva quede clara. La publicación requiere una solicitud del usuario; esta herramienta no gasta créditos de generación.

16

Organiza proyectos existentes#

Usa list_projects para encontrar proyectos existentes sin generar. Incluye Estudio, flujos de trabajo, historial de LAB y proyectos API en cola. Filtros opcionales: source: "all" | "studio" | "workflow" | "lab", q para búsqueda literal por título, y folder_id para una carpeta de tu propiedad o "unfiled". Omite el filtro de carpeta para ver todos los proyectos. Tanto list_projects como list_project_folders aceptan offset (predeterminado 0) y limit (1–100, predeterminado 50); sigue next_offset hasta que sea null.

Por ejemplo, para organizar resultados de campaña aprobados:

  1. Llama a list_projects con {"q":"approved"} y selecciona los proyectos previstos.
  2. Llama a list_project_folders; reutiliza la carpeta prevista o llama a create_project_folder con {"name":"Summer campaign"}.
  3. Llama a move_project para cada project_id seleccionado con el folder_id devuelto.
  4. Llama a list_projects con ese folder_id para verificar el contenido de la carpeta.

Usa move_project con folder_id: null para quitar un proyecto de su carpeta. rename_project_folder acepta folder_id y name. Los nombres de carpeta deben contener entre 1 y 80 caracteres tras el recorte y ser únicos en tu cuenta; un duplicado devuelve FOLDER_NAME_CONFLICT. Tras una respuesta de creación dudosa, enumera las carpetas antes de reintentar. Los movimientos y cambios de nombre se pueden repetir con seguridad y no gastan créditos, no generan medios ni cambian resultados. Los proyectos en cola conservan sus nombres y carpetas cuando el worker los crea. Estas operaciones no pueden acceder a proyectos o carpetas de otra cuenta.

17

Medios y generación#

Los medios de referencia pueden ser una URL pública o un ID de archivo V4V de tu propiedad. Un campo llamado image_url también acepta un ID de archivo; usa el esquema del modelo para elegir el campo de entrada exacto.

Cargas automáticas desde archivos adjuntos y locales

El asistente puede subir por sí mismo el archivo original cuando su entorno de ejecución puede acceder a esta implementación de V4V. No necesitas copiar una clave API en el chat ni seleccionar el mismo archivo otra vez.

  1. Llama a create_upload_link. A pesar de su nombre, la herramienta también devuelve upload_request: una URL POST, una cabecera x-upload-token con alcance y el nombre de campo multipart file.
  2. Desde la herramienta de ejecución del asistente, envía los bytes reales del archivo local a esa URL usando multipart/form-data. Deja que el cliente HTTP establezca el boundary y desactiva las redirecciones. No conviertas la imagen ni imprimas base64 en la conversación.
  3. Lee el file_id de la respuesta y confirma con get_upload usando upload_id.
  4. Descubre el esquema de entrada del modelo, pasa ese ID a su campo de medios (como Topaz image_url) y envía la generación solicitada.
  5. Para varias referencias, repite el proceso con una ranura de carga independiente para cada archivo requerido.

El token de carga caduca después de 15 minutos, acepta un archivo de hasta 20 MiB sujeto al límite del servidor y no puede leer tu biblioteca ni gastar créditos de generación. Los bytes reales viajan por HTTP; MCP proporciona la autorización con alcance y controla la generación.

Para un entorno de ejecución con el resultado de la herramienta disponible como slot, la transferencia binaria es:

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

Permitir el nombre de host de carga en Claude

La conectividad MCP y el acceso de red del sandbox son independientes. host_not_allowed significa que el sandbox no puede enviar la carga binaria aunque las llamadas MCP funcionen.

Sigue Claude Web → Permitir cargas automáticas de archivos arriba: abre Ajustes → Capacidades → Lista de permitidos de dominios, añade v4v.ai, *.v4v.ai y *.v4vcdn.space, y habilita la salida de red. Para desarrollo, añade h4000.kitpes.com por separado. Las restricciones gestionadas del espacio de trabajo pueden requerir que un administrador haga el cambio.

El asistente debe detenerse tras la primera solicitud denegada y explicar el ajuste necesario, no reintentarlo durante minutos ni convertir el archivo en texto del modelo. Inicia una conversación nueva después de actualizar los permisos y actualiza las herramientas del conector tras una actualización del servidor.

Alternativa opcional en el navegador

Si eliges la carga manual, abre upload_url, selecciona el archivo original y avisa al asistente cuando esté listo. Recupera el ID del archivo con get_upload. Esto es una alternativa, no un paso obligatorio cuando la carga HTTP automática funciona.

upload_media sigue disponible para reenvío programático de bytes o cargas muy pequeñas de hasta 8 KiB codificados. Su límite de servidor de 5 MiB decodificados no es un presupuesto práctico de texto de modelo. No redimensiones ni recomprimas una fuente solo para transferirla, no imprimas cadenas base64 grandes ni recorras fragmentos codificados en bucle.

Carga REST para archivos más grandes

Si el entorno de ejecución del asistente tiene acceso saliente a la red y una clave API configurada de forma segura, puede subir mediante POST /api/v1/files usando el campo multipart file. La clave del conector MCP no está disponible automáticamente para las herramientas de 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"

El id de la respuesta es el ID de archivo que se debe usar en las entradas de generación. Deja que curl establezca el boundary multipart. Mantén las credenciales en la configuración segura del cliente, no en la conversación.

URL públicas

Usa import_media para guardar una URL de medios accesible para reutilizarla, o proporciona la URL directamente al modelo. No pases una ruta local ni una URL del sandbox como URL pública.

Argumentos de ejemplo para generate_lab (sustituye el ID de ejemplo por el ID devuelto por tu carga):

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

Argumentos de ejemplo para 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 nuevo idempotency_key para cada generación intencionada. Reutiliza la misma clave y argumentos al reintentar una solicitud tras una interrupción de red. Reutilizar una clave con entradas modificadas devuelve un conflicto.

18

Recuperar el resultado#

Las herramientas de generación devuelven task_id y project_id de inmediato. Si el límite de concurrencia de la cuenta está completo, la misma tarea queda en espera con los detalles credits_reserved: 0, credits_estimated y queue que contienen el límite configurado, un intervalo de comprobación de cinco segundos y estimated_start_at: null. No se pueden predecir los tiempos de finalización. No envíes otra generación para saltarte la espera. El worker reserva créditos cuando se abre una plaza; si entonces el saldo es insuficiente, la tarea falla en la fase de admisión y envía su webhook configurado. No mantienen la conversación abierta hasta que termine el renderizado.

json
{
  "task_id": "task_6aa962444bd1dd7ab65bc6b6"
}

Pasa ese ID a get_task. Espera al menos cinco segundos entre comprobaciones. Una tarea puede estar en queued, processing, completed, failed o cancelled.

Cuando el estado es completed, results contiene texto integrado para el chat o URL de descarga firmadas para medios. El asistente puede compartir contigo estas URL sin necesitar cookies del navegador. Usa get_task o refresh_task_results si un enlace caduca. Los resultados multimedia incluyen asset_id/file_id estables; pasa file_id directamente a los campos multimedia de futuras generaciones en lugar de copiar una URL que caduca. El contrato de reutilización al día siguiente es el ID estable más un enlace renovable mientras el archivo exista y el acceso siga estando permitido; la propia URL puede caducar. Los enlaces siguen firmados; nunca elimines la firma ni derives una ruta CDN sin firmar. Deja de consultar en cualquier estado terminal. Consultar una tarea nunca inicia una segunda generación. Las tareas fallidas informan de error.stage, brief_completed, retryable y la retry_after_seconds sugerida cuando se conoce, junto con el credits_used real. Un brief completado puede conservar su cargo incluso cuando falla la generación de vídeo. retryable: true describe un error potencialmente transitorio; no autoriza otro intento de pago. Si la tarea devuelve GENERATION_SERVICE_ERROR, el servicio del modelo informó de un fallo interno. No supongas que la resolución de origen o el factor de escala lo causaron, ni cambies automáticamente de modelo ni crees nuevos intentos de pago. Explica el fallo y espera a que se solicite un reintento.

Las generaciones de Laboratorio también aparecen en LAB → Old runs y Projects. El uso de tu clave API aparece en tu perfil.

19

Webhooks de finalización#

generate_lab y generate_studio aceptan callback_url usando la entrega y verificación de firma de webhooks REST existentes. V4V publica task.completed o task.failed con event_id estable, datos de tarea, créditos y resultados. Verifica X-V4V-Timestamp y X-V4V-Signature usando el secreto de firma del webhook mostrado cuando se creó la clave API, y elimina duplicados por event_id. No pegues secretos en el chat. Los reintentos de entrega no crean nuevas generaciones. Las URL de callback usan la misma validación de red externa que REST. Los envíos masivos y de variantes también aceptan callback_url para eventos por lotes firmados; consulta el flujo de trabajo de supervisión más abajo. Consulta REST webhook verification.

20

Créditos y acceso#

La generación usa tus créditos V4V normales. Para las tareas ordinarias de LAB/Estudio, el coste estimado se reserva cuando hay capacidad disponible; las tareas adicionales esperan sin reserva. El crédito no usado sigue las mismas reglas de liberación que la API REST. Consultar modelos, saldos, tareas y archivos existentes no gasta créditos de generación.

Cada herramienta está limitada al propietario de la clave configurada. No se puede acceder a los archivos ni a las tareas de otra cuenta. Revoca una clave en tu perfil para desactivar su conexión MCP. Las anotaciones de herramientas identifican las llamadas que crean trabajo y gastan créditos, para que tu cliente pueda ofrecer sus controles habituales de aprobación de herramientas.

21

Resolución de problemas#

SíntomaQué comprobar
Falta create_upload_link o upload_mediaActualiza o vuelve a conectar el conector MCP para que el cliente detecte la lista de herramientas actualizada
HTTP 401Usa una clave válida y no revocada en x-api-key, o Authorization con el prefijo Bearer ; elimina los encabezados en conflicto
HTTP 403En un cliente basado en navegador, su Origin debe estar permitido por la implementación
HTTP 405 en un navegadorEl endpoint acepta solicitudes MCP POST; usa un cliente MCP
HTTP 406El cliente debe aceptar tanto application/json como text/event-stream
HTTP 429 / RATE_LIMIT_EXCEEDEDLee error.retryable y retry_after_seconds en JSON; los límites por ventana de solicitud también incluyen scope y limit. Espera el retraso y reutiliza la misma clave de solicitud/idempotencia para una solicitud rechazada. Una tarea que ya ha fallado sigue en estado terminal. Los límites de cuenta y de clave se comparten con REST.
El resultado de la herramienta tiene isError: trueLee el error estructurado, corrige las entradas y evita reintentos de generación a ciegas
Entrada del modelo rechazadaActualiza get_model y usa su esquema actual
La tarea sigue en cola o procesándoseSigue comprobando con una espera; no envíes automáticamente una generación de sustitución

El servicio usa el MCP TypeScript SDK oficial y un modo de respuesta JSON sin estado sobre Streamable HTTP. Las herramientas de espera acotada mantienen abierta la solicitud individual hasta una actualización o un tiempo de espera; no establecen un canal de notificación permanente. El cliente negocia la versión del protocolo al conectarse.

Variantes de imagen GPT Image 2.5

La detección de modelos incluye las variantes de texto/imagen Flare y Sunburst, con valores predeterminados Sunburst para image.text_to_image y ai.image_edit. Admiten background, precios 1K/2K/4K (6/10/16 créditos), prompts de hasta 20.000 caracteres y hasta 16 imágenes de edición. Consulta GPT Image 2.5 settings and API examples para ver los ID de variantes y las restricciones de relación de aspecto.

22

Modelos de vídeo Kling 4.0#

Cuatro nodos independientes comparten la misma gestión de generación y resultados en Laboratorio, Flujos de trabajo, API y MCP:

ID de catálogoModeloDuraciónResolución
video.kling_v40_refKling 4.0 Reference3–30 segundos720p / 1080p
video.kling_v40_keyKling 4.0 Keyframe3–30 segundos720p / 1080p
video.kling_v40_flash_refKling 4.0 Flash Reference3–20 segundos720p
video.kling_v40_flash_keyKling 4.0 Flash Keyframe3–20 segundos720p

Todos aceptan un prompt obligatorio (hasta 8000 caracteres), un duration entero, resolution y aspectRatio (auto, 16:9, 9:16, 1:1, 21:9; Flash Keyframe excluye auto). Todos pueden generar solo a partir de texto. Las entradas de referencia son opcionales.

Los modelos Reference aceptan referenceImageUrls (hasta 10), referenceVideoUrls (hasta 5), elements (hasta 7, como máximo 3 con vídeo) y keepOriginalSound. Un elemento con nombre tiene name, ya sea imageUrls (2–4 imágenes) o videoUrl (un clip de personaje de 3–8 s), además de tag opcional, description (100 caracteres) y voiceUrl de personaje. Flash también acepta type del elemento (image o video). Standard Reference acepta además voices: hasta 3 objetos con name y audioUrl. En cambio, Flash vincula las voces a elementos de personaje.

Hay como máximo 15 imágenes, referencias de vídeo, elementos y voces independientes combinados; los vídeos de referencia más los elementos de vídeo no pueden superar 5. Cada vídeo de referencia debe durar 2–30 s (2–20 s para Flash), y su duración combinada, incluidos los elementos de vídeo, es como máximo de 30 s (20 s para Flash). Los nombres deben ser únicos sin distinguir mayúsculas de minúsculas, de 1–20 caracteres chinos, letras, dígitos o guiones bajos; los nombres de referencia integrados están reservados. Menciona las referencias proporcionadas como @image_1, @video_1 o su @name declarado. Las menciones no declaradas se rechazan.

Los modelos Keyframe usan firstFrameUrl. Standard Keyframe también acepta keyframeUrls ordenados (hasta 8 fotogramas intermedios) y lastFrameUrl; estos requieren un primer fotograma. El total de fotogramas no puede superar min(duration + 1, 10). Flash Keyframe solo admite el primer fotograma. Menciona los fotogramas como @first_frame, @keyframe_1, @last_frame. La salida basada en fotogramas sigue la relación de aspecto de la primera imagen.

Todos los campos multimedia, incluidos los elementos y voces anidados, aceptan URL o ID de archivo V4V propios en API/MCP. Los puertos de imagen/vídeo de Flujos de trabajo usan reference_image_urls / reference_video_urls, o first_frame_url / keyframe_urls / last_frame_url; los prompts usan script-in. Standard Reference también acepta audio en voice_audio_urls, declarado como @voice_1, @voice_2, etc. Ambas salidas de Flujos de trabajo son video / clips estándar, adecuadas para el renderizador y el editor existentes. API/MCP devuelven la tarea asíncrona habitual y los archivos de resultado descargables; consulta la tarea o usa webhooks de finalización.

Tarifas base aprobadas en créditos V4V por segundo, antes de anulaciones del administrador o ajustes existentes del flujo de trabajo. Estas tarifas se usan directamente, sin conversión a USD ni recargo minorista:

Modelo720p, sin vídeo720p, con vídeo1080p, sin vídeo1080p, con vídeo
Standard Reference28.51742.525.5
Standard Keyframe28.5no disponible42.5no disponible
Flash Reference1711.3no disponibleno disponible
Flash Keyframe17no disponibleno disponibleno disponible

Ejemplos para una salida de 5 segundos:

Modelo5 s sin vídeo de origen5 s con hasta 5 s de vídeo de origen
Standard Reference, 720p142.5 créditos170 créditos
Standard Reference, 1080p212.5 créditos255 créditos
Standard Keyframe, 720p / 1080p142.5 / 212.5 créditosno disponible
Flash Reference, 720p85 créditos113 créditos
Flash Keyframe, 720p85 créditosno disponible

Sin entrada de vídeo, los segundos facturables son iguales a los segundos de salida. Con vídeo de referencia o un elemento de vídeo, los segundos facturables son iguales a max(total input video seconds, output seconds) + output seconds, con la tarifa correspondiente a entrada de vídeo. Por ejemplo, una salida Standard Reference de 10 s a 1080p con 15 s de entrada son 25 segundos facturados, 637.5 créditos antes de ajustes. Los créditos fraccionarios se conservan; el cargo completo se redondea una sola vez a dos decimales. Si se desconoce la duración de entrada, se usa la duración máxima de entrada permitida por el modelo para una estimación conservadora; el servidor verifica las duraciones reales de origen antes de cobrar. Solicita un presupuesto actual usando las mismas entradas que la generación. La administración expone tarifas separadas de resolución/entrada de vídeo para cada nodo. Los nodos Kling más antiguos mantienen sus precios y ajustes actuales.

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 este cuerpo con generate_lab en MCP o POST /api/v1/lab en HTTP. Para un presupuesto, añade "source": "lab" y usa estimate_generation en MCP o POST /api/v1/generation/quote en HTTP. Descubre siempre primero el modelo seleccionado con get_model o GET /api/v1/models/{id}. Se aplican la autorización estándar de generación, las comprobaciones de saldo, las claves de idempotencia, los callbacks y los reembolsos por fallos.

23

Chat GPT-6 Astra#

Usa list_models con {"type":"chat"}, después get_model con {"model":"chat.gpt_6_astra"} para inspeccionar las entradas actuales, las tarifas de tokens y el redondeo. Envía 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.

El chat reserva inicialmente 1 crédito. El coste final usa los tokens reales de entrada, caché y salida, redondeados al alza a un crédito entero con un mínimo de 1. Cualquier importe por encima de la reserva se deduce después de la respuesta; la reserva inicial no es un límite de gasto. Las tarifas de tokens las publica get_model. Reutiliza la misma clave de idempotencia y los mismos argumentos para los reintentos de red; no envíes automáticamente otra generación de pago tras un fallo.

Para el chat y la generación de imágenes con precio por uso, estimate_generation también devuelve credits_range.min y credits_range.max en créditos V4V, con el margen y los ajustes de precio actuales incluidos. Preséntalo como un intervalo aproximado. Sus assumptions describen escenarios de uso ilustrativos; el coste real puede quedar fuera del intervalo, y is_spending_cap es false. credits_estimated y initial_reservation_estimated siguen siendo la estimación separada de la reserva inicial. Esta vista previa no reserva créditos ni inicia ninguna generación.

24

Modelos actuales de imagen y 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") admite 1K/2K/4K y hasta 10 referencias. Lee pricing_by_variant para su modo de facturación actual. La generación de Google/Vertex liquida los tokens reales de entrada, entrada en caché, salida de imagen, salida de texto y razonamiento, incluido el margen; otro enrutamiento usa la tarifa de imagen configurada. Gemini 4 Argon (chat.gemini_4_argon) incluye los tokens de razonamiento en la facturación por uso. Usa estimate_generation para mostrar intervalos aproximados de créditos; la reserva inicial y el intervalo están separados del uso final y no son límites de gasto. Nunca inventes parámetros de enrutamiento ni cambies en silencio los ajustes de administración.

25

Vídeos de producto masivos de Estudio#

Usa generate_studio_bulk cuando quieras vídeos para una lista de productos. Acepta entre 1 y 300 elementos y devuelve un batch_id de inmediato. Comparte el saldo normal de créditos de la cuenta y la cola compartida normal de generación de V4V con REST y la aplicación 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"
}

La entrada y los parámetros del elemento anulan la configuración compartida; los valores predeterminados de Estudio completan el resto. Proporciona ID de producto propios, URL públicas de páginas de producto o detalles y medios del producto ya preparados. Usa la configuración compatible con el modelo actual de Estudio del despliegue. Omite test_count para procesar toda la lista. Con test_count: 5, los cinco primeros elementos (o todos si son menos de cinco) se ejecutan antes de que el lote se pause para revisión.

HerramientaFinalidad¿Gasta créditos de generación?
generate_studio_bulkCrea un lote de vídeos de producto con un presupuesto de créditos obligatorioSí, a medida que empieza cada elemento
list_studio_batchesEnumera los lotes más recientes de la cuentaNo
get_studio_batchLee el progreso paginado, los ID de tarea de los elementos, los resultados y un state_token estableNo
wait_studio_batchEspera un cambio, finalización, pausa o cancelación; 25 segundos por defectoNo
control_studio_batchpause, resume, cancel, retry_failed, rework o restart; max_credits opcional aumenta el presupuesto acumuladoLa reanudación y los nuevos intentos pueden gastar créditos

DIRECTOR_REQUEST_FAILED identifica el rechazo de la solicitud de texto de AI Director; REFERENCE_MEDIA_UNAVAILABLE identifica un problema al leer sus archivos de referencia. Explica la fase que ha fallado e informa del ID de la tarea; nunca supongas que esto significa que una solicitud de generación de vídeo ha fallado ni crees automáticamente otro intento de pago.

Las URL públicas de artículos de eBay admiten una alternativa de importación protegida mediante navegador. Si una tienda sigue rechazando una importación, envía un product_id propio o detalles/imágenes del producto ya preparados. IMPORT_FAILED se produce antes de la admisión de pago e incluye el motivo de importación conocido; PREPARATION_FAILED identifica un fallo posterior de preparación. Un intento fallido permanece terminal. Cuando el usuario solicite un reintento, llama a control_studio_batch con action: "retry_failed" y una nueva idempotency_key; opcionalmente proporciona item_indexes con base cero. Para entradas corregidas o una nueva creación deliberada, usa action: "rework" con items: [{task_id: "task_…", input: {prompt: "New direction"}}] (o usa index: 1 en lugar de task_id). Usa action: "restart" solo cuando el usuario solicite de nuevo todos los elementos, incluidos los correctos. Estas tres acciones requieren una nueva clave para cada operación intencionada; reutiliza la misma clave y los mismos argumentos en caso de errores de red. resume no reintenta intentos fallidos.

Para rehacer solo los resultados que no te gustan, selecciona sus items[].task_id actuales y llama a control_studio_batch con action: "rework", esos ID en items y una nueva idempotency_key. Omite los cambios de entrada para volver a ejecutar la misma instrucción. Los resultados actuales seleccionados se eliminan de inmediato y el mismo lote reanuda el procesamiento; los demás elementos completados permanecen sin cambios. items[].results siempre describe la última versión prevista, mientras que attempts conserva la salida anterior. Un ID de tarea sustituida obsoleto devuelve BATCH_ITEM_VERSION_CHANGED; vuelve a leer el lote antes de una nueva reelaboración intencionada.

Supervisar un lote en el conector de navegador de Claude

Un webhook envía una solicitud HTTP a un receptor real. No proporciona a esta conexión MCP una forma de reiniciar una conversación inactiva del navegador de Claude. No inventes nunca una URL de callback ni prometas un futuro mensaje de chat después de que la conversación haya terminado.

Durante el flujo de trabajo por lotes solicitado por el usuario, Claude debe supervisar automáticamente:

  1. Conserva batch_id y state_token de generate_studio_bulk, generate_studio_variants o get_studio_batch.
  2. Llama a wait_studio_batch con batch_id, after_state establecido en ese token y wait_seconds: 25 para conectores de navegador. La paginación opcional usa offset y limit (50 por defecto, 100 máximo).
  3. El servidor responde cuando hay un cambio relevante en el lote, su finalización, pausa, cancelación o al agotarse el tiempo de espera limitado. Los latidos del worker y las firmas de resultados que caducan no cambian el token. La respuesta contiene la página actualizada del lote, changed, timed_out, stop_reason y next_action.
  4. Mientras status sea running, sigue esperando con el token devuelto sin pedir al usuario que diga “comprobar de nuevo”. Informa de hitos útiles, no de cada tiempo de espera sin cambios. Un tiempo de espera no provoca fallo ni cancela la generación. No envíes un lote de sustitución.
  5. En completed, informa de los resultados y de los fallos. En paused, explica waiting_reason y espera la decisión del usuario. No reanudes nunca automáticamente, no aumentes un presupuesto ni reintentes intentos de pago. cancelled también pone fin a este bucle de supervisión.

Esto utiliza long polling del lado del servidor dentro de un flujo de herramientas activo. Si Claude termina su turno, el usuario cierra la conversación o el cliente impone un límite de tiempo de ejecución, el lote sigue ejecutándose, pero esta conexión no puede garantizar un nuevo mensaje de chat. Cancelar/desconectar una espera solo detiene la observación, no el lote. Comprobar o esperar no consume créditos de generación.

wait_seconds acepta de 1 a 240 segundos. Claude Code permite enviar automáticamente a segundo plano llamadas MCP largas en versiones recientes; para una espera de 240 segundos, configura el timeout de ese servidor al menos en 300000 milisegundos y permite que la solicitud supere los tiempos de espera del proxy. Los conectores de navegador deben usar el valor predeterminado de 25 segundos. Consulta Claude Code long tool calls. Este comportamiento es específico del cliente y no garantiza la reactivación del navegador.

Webhooks de lotes para receptores externos

Pasa callback_url al crear un lote masivo o variantes. Se aplican el secreto de firma del webhook existente de la clave API y la verificación de X-V4V-Timestamp / X-V4V-Signature. El destino de callback queda fijado por la solicitud de creación idempotente; reutiliza la misma URL y los mismos argumentos tras errores de red.

El worker registra instantáneas relevantes y entrega batch.updated, batch.completed, batch.paused y batch.cancelled. Los eventos incluyen event_id, batch_id, batch_revision, observed_at, state_token, estado, recuentos y totales de créditos estables. result_lookup apunta a get_studio_batch para archivos paginados y detalles de tareas; las cargas útiles de webhook no insertan URL de resultados que caducan. Las transiciones intermedias pueden agruparse entre ticks del worker.

La entrega usa una bandeja de salida duradera con concesiones y reintentos limitados. La entrega repetida tiene el mismo ID de evento y la misma carga útil; las firmas se renuevan en cada intento. Los receptores deben eliminar duplicados y tolerar entregas fuera de orden, y después obtener el estado actual del lote cuando sea necesario. Los errores HTTP permanentes abandonan la entrega; los fallos transitorios aplican retroceso. Un receptor de webhook lento no bloquea al worker de generación/admisión. Las pausas, las cancelaciones con trabajo activo y los reinicios/reelaboraciones solicitados después siguen produciendo actualizaciones. La entrega nunca inicia otro intento de pago.

Para lecturas manuales ocasionales del estado, llama a get_studio_batch con al menos cinco segundos de intervalo; para supervisión activa por parte del agente, prefiere wait_studio_batch. Los intentos individuales usan la herramienta habitual get_task para enlaces de descarga firmados. Estas herramientas siguen procesándose en el servidor sin que la conversación o una pestaña del navegador permanezcan abiertas.

Las colas masivas reservan solo la estimación del siguiente elemento admitido. max_credits limita los créditos gastados más las reservas activas. Un saldo o presupuesto insuficiente pausa los nuevos inicios; cuando el usuario lo solicite, llama a control_studio_batch con action: "resume", aumentando opcionalmente max_credits. Pausar/cancelar permite que terminen los intentos activos. Los lotes cancelados no pueden reanudarse, pero pueden reiniciar o reelaborar explícitamente elementos terminales después de que finalice el trabajo admitido. Los elementos seleccionados deben ser terminales (BATCH_ITEMS_ACTIVE); las solicitudes activas del proveedor o con estado incierto bloquean los reintentos (GENERATION_UNRESOLVED). NO_FAILED_ITEMS significa que ya no quedan fallos más recientes. El historial, los resultados y el gasto acumulado sobreviven a todas las operaciones; los recuentos y el estado de los elementos usan solo las últimas versiones previstas. Las nuevas versiones comparten las mismas colas y la misma atribución del Registro de créditos. Los cambios opcionales de entrada/parámetros para toda la operación se combinan sobre la solicitud anterior, y prevalecen las sustituciones por elemento de la reelaboración. Una puerta de muestra conservada sigue requiriendo una reanudación explícita; reiniciar la elimina. Consulta el contrato REST para conocer los límites de solicitud/historial y ejemplos completos. Reutiliza la misma idempotency_key y los mismos argumentos tras un error de red; no crees nunca otro lote para evitar la espera en cola.

Las solicitudes de generación comparten como máximo 10 ranuras activas entre cuentas y procesos de la aplicación. La generación ordinaria tiene prioridad; los lotes usan capacidad sobrante bajo límites globales y por usuario definidos por el administrador. Una respuesta perdida del proveedor mantiene ocupada su ranura para conciliación y nunca desencadena una solicitud de pago duplicada automática. Los eventos de créditos de API y MCP se etiquetan por separado en los Registros de créditos del administrador.

Esta versión ofrece generación y descargas individuales mediante API/MCP. Las pantallas masivas de Estudio del plan más amplio, la carga de CSV, la aprobación de resultados y la exportación ZIP siguen siendo trabajo futuro. Actualiza la lista de herramientas de tu conector MCP después del despliegue para descubrir las nuevas herramientas de lotes. Consulta el contrato REST de lotes para ver campos, semántica de presupuesto y errores.

26

Editor de vídeo#

El editor en /video-editor te permite a ti y a tu asistente trabajar en la misma línea de tiempo guardada y multicapa. Admite vídeo, imágenes/logotipos, audio fuente, capas independientes de música/voz, texto, subtítulos temporizados, recorte, división, velocidad, volumen, fundidos y notas de revisión de tomas. El navegador ofrece vista previa interactiva y exportación local a MP4/WebM. Abre Video Editor para editar de forma interactiva; las herramientas y los límites se describen a continuación.

Empieza con get_editor_guide (también disponible como recurso v4v://video-editor). Actualiza la lista de herramientas del conector después del despliegue.

Para una fábrica de contenido completa, lee get_factory_guide / v4v://factory. create_factory_run, list_factory_runs, get_factory_run y submit_factory_stage conservan los nueve roles con reintentos exactos de operación y revisiones distintas de ejecución/proyecto. prepare_factory_review devuelve imágenes capturadas reales, get_factory_frame las vuelve a leer y preview_factory_audio devuelve un fragmento WAV medido. Inspecciona cada fotograma capturado y revisa el movimiento y el habla antes de emitir un juicio. repair_factory_run permite como máximo dos correcciones; release_factory_run encola y luego verifica una exportación privada completa de Biblioteca, un ZIP editable, una portada y REVIEW.md. Estas herramientas requieren propiedad del proyecto; las escrituras necesitan OAuth de lectura + escritura, sin permiso de generación ni cargos de créditos. La generación de escenas de pago sigue siendo una operación separada con presupuesto. Consulta el contrato de fábrica ucraniano para ver rutas HTTP, recuperación y evidencias medidas frente a las informadas por el revisor.

HerramientaFinalidad
get_editor_guideContrato de línea de tiempo, flujo de trabajo de edición y ejemplo de línea de tiempo vacía
get_motion_guideAPI de motion versionada, esquemas reales, ejemplos nativos/HTML, unidades de tiempo/geometría y ciclo de vida; también v4v://motion-api
get_editor_troubleshootingGuía de recuperación versionada para errores reales; también v4v://troubleshooting; la lectura nunca realiza una reparación ni un reintento
get_project_transfer_guideInteroperabilidad ZIP local/V4V, solicitudes binarias, permisos y recuperación; también v4v://project-transfer
export_editor_bundlePreparar una solicitud de descarga binaria delimitada para un proyecto en la revisión actual; ejecútala para obtener el ZIP real
import_editor_bundlePreparar una carga binaria ZIP con {} y luego recuperar su nuevo proyecto con transfer_id; sin base64 en el texto del modelo
get_editor_capabilitiesFormatos reales, tiempos de ejecución, operaciones locales/compartidas y servicios opcionales
get_creative_library / search_creative_libraryDescubrir el registro creativo compartido instalado
get_creative_itemEsquema exacto de un elemento, ejemplo original, rutas de vista previa, licencia y límites
get_style_format_guideFormato de paquete comunitario solo de datos; mismo contenido que v4v://style-format
create_style_exampleImportar una nueva muestra de estilo editable y material original a la cuenta; sin créditos de modelo
apply_styleVista previa con dry_run=true y después confirmar en la misma revisión; los bloqueos y las sustituciones manuales se mantienen
check_editor_projectRevisión estructural/multimedia P0/P1; inspecciona por separado fotogramas y audio reales
list_editor_projectsBuscar proyectos del editor propios/compartidos, filtrar scope y leer niveles de acceso
create_editor_projectCrear un proyecto vacío o una línea de tiempo validada
get_editor_projectLeer línea de tiempo, revisión y URL de medios renovables
update_editor_projectGuardar una línea de tiempo completa en una revisión esperada
edit_editor_projectAplicar operaciones atómicas de clip/capa/subtítulo en una revisión esperada
propose_editor_silence_cutsMedir el audio fuente real y proponer intervalos silenciosos ampliados sin editar; aplica explícitamente los remove_time_ranges revisados en la misma revisión para desplazar en cascada todas las pistas
propose_editor_audio_duckingMedir stems reales de voz/música y la automatización propuesta; inspecciona el RMS antes/después y luego aplica explícitamente los set_audio_envelope devueltos en la misma revisión
get_safe_area_guidePerfiles de destino editorial versionados y esquema personalizado; también v4v://safe-areas
inspect_editor_textMedir texto nativo/motion/HTML guardado con fuentes incluidas e informar de hallazgos muestreados de desbordamiento, solapamiento y legibilidad
propose_editor_text_fitProponer tamaño de fuente de texto estático sin cambiar palabras, tiempos ni el proyecto guardado
propose_editor_scene_layoutProponer límites explícitos de contenido motion/HTML y tamaño mínimo de fuente a partir del perfil de área segura guardado; revisa y aplica set_scene_layout devuelto
list_editor_mediaBuscar medios propios de Biblioteca por tipo y nombre
get_editor_mediaInspeccionar duración, dimensiones y URL de reproducción de una fuente propia
preview_editor_projectDevolver hasta seis fotogramas JPEG compuestos reales para inspección visual
get_editor_text_stylesDescubrir preajustes de texto/subtítulos, contornos, motion y reacción al sonido
quote_editor_captionsCitar la transcripción del habla fuente sin generar
transcribe_editor_mediaIniciar la transcripción del habla; consume créditos normales de la cuenta
get_editor_captionsLeer el progreso de la transcripción y las marcas temporales del material fuente
append_editor_audioAñadir ID de recursos de audio ordenados a una capa desbloqueada, con pausas opcionales
export_editor_projectEncolar/recuperar MP4, WebM, MP3 o MP4 con portada estática; devuelve export_id de inmediato
get_editor_exportConsultar estado/fase y recuperar el recurso completado de Biblioteca con enlaces renovados
get_editor_project_sharingPropietario: listar colaboradores y devolver el enlace privado del proyecto
share_editor_project_with_userPropietario: invitar por correo electrónico o cambiar acceso de lectura/escritura, opcionalmente notificar por correo electrónico
remove_editor_project_accessPropietario: revocar un colaborador por ID de usuario
transfer_editor_project_ownershipPropietario: transferir explícitamente a otra cuenta de V4V por correo electrónico
share_editor_projectPublicar un enlace público para el vídeo exportado actual, cuando se solicite explícitamente

Motion API y recuperación

A partir de Kit 0.1.31, get_motion_guide y get_editor_troubleshooting aceptan {} y coinciden exactamente con sus recursos JSON. Ambos contienen version y engineVersion; descubre las herramientas del servidor actual después del despliegue. Su ámbito de OAuth de V4V es v4v:read. Leer estos recursos no edita, renderiza, reintenta ni reserva créditos.

La guía de motion contiene esquemas registrados reales, ejemplos add_clip nativos y HTML, ciclo de vida determinista de prepare / renderAt / dispose, tiempo local de escena y reglas de geometría fraccional. En un nuevo proyecto vacío, aplica sus operaciones de ejemplo en la revisión guardada y previsualiza los segundos 1 y 5. En proyectos existentes, adapta deliberadamente los ID de pista/clip y la colocación. Solo se aceptan escenas JSON registradas; la línea de tiempo no instala HTML ni scripts arbitrarios. Inspecciona los fotogramas reales y el motion exportado antes de aceptarlo.

Usa la resolución de problemas con el código de error real y el estado guardado. Un CONFLICT significa recargar y conservar las ediciones simultáneas; los medios que faltan requieren una fuente real autorizada; las fuentes que faltan necesitan una restauración explícita. Inspecciona el intento existente de exportación/plano tras una respuesta desconocida. Leer una receta de recuperación nunca autoriza una compra nueva, omitir un permiso ni reiniciar una operación cancelada.

Propuestas de diseño y audio medidas

Los perfiles de área segura son guías editoriales versionadas, no garantías oficiales de la plataforma. set_safe_area_profile conserva la guía sin cambiar los píxeles renderizados. propose_editor_scene_layout la usa para proponer motion.layout explícitos; revisa applicable y el informe, y luego aplica las operaciones devueltas mediante edit_editor_project en la misma revisión. layout:null revierte el ajuste. Cambiar la guía después no readapta el contenido. inspect_editor_text toma muestras de glifos reales/cajas DOM; el texto integrado en medios, el recorte rotado, el contraste sobre metraje, el movimiento completo y la escucha siguen siendo tareas de revisión.

Para música bajo voz, llama a propose_editor_audio_ducking con project_id, revision, voice_clip_ids disjuntos y music_clip_ids reales, y options opcional. Los valores predeterminados apuntan a un margen RMS de voz/música de 12 dB, detectan actividad a −40 dBFS y limitan la atenuación a 30 dB. El servicio mezcla las fuentes seleccionadas con sus recortes, velocidad, volumen y fundidos reales; también remezcla y mide la música propuesta. Inspecciona comparison de referencia, after medido, targetMet, advertencias e intervalos de frase, escucha y luego aplica explícitamente operations devueltos mediante edit_editor_project en la misma revisión.

La automatización musical seleccionada se sustituye en lugar de acumularse; la ganancia y los fundidos base se mantienen. Las curvas se pueden transportar en ZIP y siguen a su clip de música. Recalcula después de cambiar la temporización o el nivel de la voz, las fuentes o la colocación de la música. Hasta 500 clips de voz y 20 de música, 100 MiB por fuente de V4V, 512 MiB en total y 64 clips que se crucen por ventana de análisis; también se aplican límites de recursos y de tasa. El acceso de lectura permite propuestas, mientras que aplicarlas requiere acceso de escritura. Ni la medición ni la edición local consumen créditos. El RMS y la amplitud detectada no demuestran inteligibilidad; las sugerencias de cortes silenciosos también requieren escucha antes de hacer ediciones ripple en todas las pistas.

ZIP portátil mediante V4V MCP

Lee get_project_transfer_guide / v4v://project-transfer. Ambos hosts usan el mismo contenido de .v4v.zip: un bundle.json versionado y los bytes originales de assets/<sha256>. Solo el Kit local acepta el argumento directory; V4V rechaza explícitamente las rutas locales del sistema de archivos.

Exportación: llama a export_editor_bundle con project_id y el revision actual, luego ejecuta su download_request usando la cabecera con ámbito exacta y guarda la respuesta binaria real. La herramienta ha preparado una solicitud, pero aún no ha creado un archivo. La descarga vuelve a comprobar cuenta/clave/OAuth, acceso al proyecto/medios y revisión. Su respuesta contiene X-Content-SHA256; compara los bytes descargados. Si el proyecto cambió, vuelve a leer su revisión y solicita deliberadamente otra exportación.

Importación: llama a import_editor_bundle con {}, haz POST de los bytes ZIP originales usando el upload_request devuelto (application/zip, no multipart) y luego llama a import_editor_bundle con su transfer_id. Esto crea un proyecto nuevo, verifica/sondea fuentes y reasigna los ID de recursos anidados. Tras perder una confirmación, recupera la misma transferencia: una importación completada devuelve el proyecto existente. Una importación interrumpida puede recuperar su concesión caducada usando los bytes originales; un archivo distinto requiere una transferencia nueva. Nunca inventes datos de archivo ni imprimas base64 grande en el contexto del modelo. Los clientes sin acceso a archivos binarios pueden usar Estudio Abrir ZIP de proyecto.

Las credenciales de transferencia caducan a los 15 minutos; los recibos siguen siendo recuperables durante siete días. Los tokens deben ir en la cabecera de solicitud devuelta, no en URL, cronologías ni mensajes públicos. La importación requiere OAuth de lectura + escritura; la exportación requiere lectura y acceso al proyecto actual. El ZIP y su contenido expandido están limitados a 100 MiB; se aplican dos transferencias por proceso, cuerpos de solicitud acotados, concesiones y límites de tasa por usuario/solicitud. La importación/exportación no realiza generación, compartición pública ni notificaciones. Los permisos de compartición de cuenta y las credenciales de modelo no viajan en el ZIP. Vuelve a abrir el proyecto devuelto e inspecciona los medios/fotogramas reales antes de la entrega.

Compartición privada de proyectos a través de MCP

El asistente puede completar la compartición privada sin pedir al usuario que opere el navegador. Si falta el correo de V4V del destinatario o su nivel de acceso de lectura/escritura, solicítalo y luego llama a:

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 cuando el usuario haya solicitado una notificación por correo; su valor predeterminado es false. Devuelve project_link para que el usuario lo envíe e informa de emailNotification con precisión: failed significa que se concedió el acceso pero no se envió el correo. El enlace del proyecto requiere la cuenta invitada; los destinatarios con la sesión cerrada inician sesión y vuelven al mismo proyecto. No se necesita exportación de vídeo, generación ni créditos de generación.

get_editor_project_sharing lista los colaboradores y sus userId, correo y acceso. Cambia permisos con share_editor_project_with_user; revoca a un usuario listado con remove_editor_project_access y su user_id. Transfiere solo cuando el usuario haya solicitado explícitamente la transferencia de propiedad y haya proporcionado el correo del nuevo propietario. El antiguo propietario pierde el acceso; los demás colaboradores y las referencias de fuentes se mantienen. Todas las llamadas de gestión exigen propiedad del proyecto; las mutaciones OAuth requieren además v4v:write.

share_editor_project sigue siendo una acción diferente: publica el vídeo exportado terminado en una página pública para compartir. No lo uses para invitaciones privadas a colaboradores. Actualiza/reconecta el conector MCP después del despliegue para descubrir las nuevas herramientas e instrucciones.

Los ID de proyecto del editor son distintos de los ID de proyecto de generación de Estudio/Laboratorio. Usa list_editor_projects, no list_projects, para descubrirlos. La generación sigue disponible mediante las herramientas existentes de descubrimiento de modelos, estimación y generate_lab. Los file_id de los medios completados pueden usarse directamente como assetId de la cronología. El speech-to-text también puede descubrirse como type: "subtitle"; prefiere ai.gemini_3_5_transcribe (Gemini 3.5 Transcribe). Los resultados de sus tareas API completadas contienen texto, SRT, VTT y cues/words temporizados en segundos de la fuente. Las herramientas de transcripción dedicadas del editor simplifican el uso de una fuente existente de la Biblioteca.

Una solicitud típica de un agente:

Crea una película vertical de 20 segundos a partir de mis clips de la Biblioteca. Revisa fotogramas representativos y sustituye la toma distorsionada por una generación nueva después de mostrar su coste. Recorta los planos, añade mi logotipo, música de fondo suave, una voz en off y subtítulos temporizados. Guarda el vídeo terminado en la Biblioteca y dame un enlace de descarga.

El asistente debe:

  1. Lee la guía, busca el proyecto y los medios de origen, e inspecciona duraciones y reproducción.
  2. Crea o edita la cronología usando su revisión actual. Añade un logotipo como imagen en una capa visual superior y voz/música en capas de audio. El medio original no cambia.
  3. Usa preview_editor_project para inspeccionar los tiempos de fotograma seleccionados. Establece review: "keep" o "replace" del clip y registra el motivo en note. Los fotogramas no determinan la calidad del movimiento ni del sonido; inspecciona también la reproducción de la fuente.
  4. Descubre/estima los modelos solicitados, genera sustituciones con claves de idempotencia únicas y espera a sus ID de archivo completados. Sustituye la fuente del clip seleccionado y ajusta su recorte/duración a la nueva fuente.
  5. Cotiza/transcribe la fuente de voz original, consulta con al menos cinco segundos de separación y luego añade cues con sourceClipId para tener en cuenta el recorte y la velocidad. Revisa el texto de la transcripción. Proporcionar cues temporizados existentes no cuesta créditos.
  6. Envía la revisión actual con export_editor_project; consulta get_editor_export con al menos cinco segundos de separación mientras esté en cola/renderizando. Una solicitud MCP desconectada no cancela el trabajo. Solo completed con un ID de recurso y una URL de descarga significa éxito; inspecciona los fallos antes de reintentar explícitamente con retry_failed: true. Crea un enlace para compartir solo si se solicita.

Ejemplo de edición dirigida después de 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 usan segundos de la cronología, trimStart usa segundos de la fuente y la división time es un tiempo absoluto de la cronología. Lee la duración real del medio antes de recortar. add_clip acepta un clip con id, trackId, kind, assetId, start y duration únicos; los demás campos tienen valores predeterminados. El texto usa kind: "text" y text en lugar de un recurso. Los tipos de pista son visual, audio o text. add_track, update_track, remove_track y reorder_tracks gestionan capas. Las pistas se renderizan en el orden del array, la última arriba. Superpón capas visuales y usa fundidos para las disoluciones.

El servidor rechaza medios inaccesibles, tipos de medio no coincidentes, recortes no válidos y revisiones obsoletas. Si hay un conflicto de revisión, lee la nueva versión y vuelve a aplicar los cambios previstos. No sobrescribas el trabajo del otro editor. Los editores limpios del navegador abiertos recogen automáticamente los cambios del agente; los borradores modificados localmente conservan sus cambios y muestran conflictos.

La inspección de fotogramas por parte del agente y la exportación WebM de cronología visual requieren Playwright Chromium en el despliegue. Estas exportaciones de cronología visual admiten hasta dos minutos y 300 MB de medios de origen, y devuelven un WebM guardado; una exportación repetida de la misma revisión reutiliza su recurso existente. La exportación del navegador admite cronologías de diez minutos y ofrece MP4 cuando el dispositivo tiene codificadores H.264/AAC. Si el renderizado falla, informa del error y del enlace al editor; no afirmes que la exportación ha sido correcta. La edición/renderizado de cronología no consume créditos de modelo; la generación/transcripción sí. Compartir crea un enlace visible para cualquiera que lo tenga.

27

Gemini text-to-voice#

Usa list_models con type="audio", y luego get_model para ai.gemini_3_8_flash_tts o ai.gemini_3_8_flash_lite_tts. Ambos generan audio WAV de un solo locutor a partir de hasta 10.000 caracteres hablados:

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

Texto con estilo, subtítulos y transcripción de Google#

get_editor_text_styles devuelve 14 preajustes de subtítulos, 6 preajustes de títulos y un fontCatalog con 12 fuentes incluidas más 4 alias heredados del sistema. Cada preajuste de subtítulos reacciona a marcas de tiempo reales de palabras. Usa el preajuste category y use para elegir un tratamiento: word-pop (Creator punch), caption-marker (Lime marker), caption-underline, editorial (Podcast panel), caption-soft, caption-outline o neon-pulse (Neon glow), además de otros estilos de movimiento de palabras. Los títulos tienen sus propios preajustes: title-clean, title-condensed, title-magazine, title-tech, title-sticker y cinema-gold. Los subtítulos nuevos usan por defecto Montserrat en mayúsculas de 100 px con tres palabras por frase. Mantén un estilo de subtítulos coherente y un estilo de título complementario, contraste fuerte y márgenes seguros. Las cronologías guardadas existentes conservan sus ajustes hasta que se les vuelva a aplicar estilo. Consulta el catálogo tipográfico completo.

Prefiere los ID de fontFamily incluidos: inter, montserrat, manrope, oswald, rubik, roboto-condensed, unbounded, nunito, playfair-display, roboto-slab, jetbrains-mono, comfortaa. Admiten latín y cirílico ucraniano y se cargan desde V4V antes del renderizado en la vista previa y en ambas rutas de exportación. fontCatalog.weights proporciona el intervalo admitido de cada familia. Los heredados sans, impact, serif y mono dependen de las fuentes del sistema. Nunca ignores un error de carga de fuente y afirmes que la exportación se ha realizado correctamente.

Los clips de texto aceptan strokeWidth (0–24 píxeles de salida), strokeColor, color, fontFamily (ID de catálogo), fontWeight (400/500/600/700/800/900, ajustado al intervalo admitido por la fuente), textBackground, backgroundColor, backgroundOpacity, accentColor, textAnimation, activeWordEffect (none, color, pop, shake, swing, spin, box, underline, glow), activeWordColor (color de primer plano del marcador), 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 y audioSourceClipId opcional. Las animaciones son none, fade, slide, pop, float, shake, pulse, color-cycle y karaoke. audioReactive: true usa el volumen de audio real, incluidos recorte, velocidad, fundidos, volumen y pistas silenciadas/ocultas. Sigue todas las fuentes audibles salvo que se proporcione un ID de clip de fuente; no detecta pulsos musicales. La vista previa, la búsqueda, la exportación local y la exportación del servidor comparten este renderizador.

Usa edit_editor_project con { "type": "apply_text_style", "clipIds": ["caption-1", "caption-2"], "stylePreset": "creator-pop" } para aplicar estilo a varios subtítulos. Ajusta con precisión con update_clip. add_captions acepta stylePreset, maxWordsPerCaption (1–8, predeterminado 3) y words de cue como { "text": "Hello", "start": 1.2, "end": 1.6 }. Las palabras del cue usan segundos de la fuente y sourceClipId las alinea con el recorte, la velocidad y la posición en la cronología. En un clip de texto individual, wordTimings usa segundos relativos a ese clip. Los efectos de palabra hablada resaltan y animan solo la palabra pronunciada en ese momento; conserva las marcas de tiempo reales. Las mayúsculas cambian el renderizado sin reescribir el texto original ni los tiempos. SRT solo proporciona temporización de cues, así que nunca inventes la temporización de palabras a partir de él.

Para la transcripción, llama a list_models con type: "subtitle" y luego a get_model con model: "ai.gemini_3_5_transcribe". Cotiza con estimate_generation y envía la misma solicitud mediante 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"
}

Como alternativa, proporciona videoUrl con una referencia de vídeo de tu propiedad. Elige exactamente una fuente, de hasta 15 minutos. La cuenta de servicio de Google conectada se encarga de la autenticación. No proporciones credenciales del proveedor ni parámetros de enrutamiento. Consulta get_task para results con type: "subtitle"; conserva sus cues y temporizaciones de palabras para los subtítulos del editor. Google actualmente marca las marcas de tiempo de palabras como experimentales, así que revisa la precisión de la transcripción. Las herramientas de cotización/transcripción del editor ahora usan este modelo por defecto. El heredado ai.speech_to_text sigue siendo independiente; los administradores pueden ocultarlo de forma independiente. Las solicitudes de pago fallidas se reembolsan mediante el ciclo de vida normal del trabajo y no deben reintentarse automáticamente como una compra nueva.

Completa el flujo de trabajo de subtítulos del editor

Transcribir un archivo no inserta subtítulos en un proyecto del editor. Para una película existente:

  1. Lee get_editor_project e identifica el clip de origen y su assetId.
  2. Si ya tienes un resultado de subtítulos generate_lab / get_task correcto para este origen, reutiliza su cues y pasa directamente a la inserción en el paso 4; no hace falta una file_id de vídeo ni una segunda transcripción. En caso contrario, llama a quote_editor_captions y después a transcribe_editor_media con ese asset_id, language: "auto" (o un código BCP-47) y una idempotency_key única. Reutiliza esa clave tras un tiempo de espera de red.
  3. Consulta get_editor_captions dejando al menos cinco segundos entre consultas. En failed, informa de error y detente. Un nuevo intento de pago requiere la solicitud del usuario.
  4. En succeeded, exige un cues no vacío, obtén la revisión más reciente del proyecto y pasa esas entradas exactas a edit_editor_project con type: "add_captions", el sourceClipId del clip de origen, stylePreset: "word-pop" y maxWordsPerCaption: 3 (u otro preajuste de palabras solicitado).
  5. Verifica los nuevos clips de texto en la línea de tiempo guardada y la vista previa en un momento real de subtítulo. Comprueba la precisión del texto. Debe informarse si el origen cambió durante la transcripción o si hay un recorte sin voz superpuesta; no afirmes que la inserción se ha realizado correctamente. Reutiliza las entradas completadas para resolver conflictos de edición sin volver a generarlas.

Conserva todas las marcas temporales de palabras devueltas, incluidos los desplazamientos de inicio/fin iguales para palabras cortas. Cambia el nombre de una superposición con update_clip / changes.name; cambia las palabras visibles con changes.text. Cambia el nombre de su capa con update_track / changes.name. Conserva los ID y respeta las capas bloqueadas.

La transcripción de Gemini cuesta al menos 1 crédito por solicitud, incluidos los clips cortos; indica el precio actual según la duración antes de generar. El JSON de subtítulos incluye time_unit: "seconds", una matriz plana de words y cues[].words, con el text, start, end y el speaker_id opcional de cada palabra. Usa estas palabras para karaoke y otros estilos sincronizados. El SRT solo tiene temporización por línea. Laboratorio puede previsualizar palabras temporizadas y copiar/descargar JSON o SRT. El Editor de vídeo acepta directamente el JSON mediante Subtítulos → Importar SRT o JSON; elige uno de los preajustes grandes de palabra hablada y usa Propiedades del clip → Palabras y temporización para corregir palabras individuales sin eliminar su temporización. Las correcciones de MCP deben pasar tanto changes.text como el changes.wordTimings corregido completo; cambiar solo el texto borra la temporización obsoleta.

Para acortar una capa de subtítulos temporizada existente sin otra generación, usa:

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

Usa la revisión actual real y el ID de capa. Esto conserva la temporización real de palabras, el estilo y la capa, y devuelve la línea de tiempo actualizada con nuevos ID de clip. Aplica un preajuste de palabras compartido a esos ID con apply_text_style. En el navegador, usa Propiedades del clip → Palabras y temporización → Palabras por subtítulo → Dividir esta capa en subtítulos cortos, y después Texto y apariencia → estilo → Aplicar estilo a la capa. Las líneas SRT no pueden dividirse con precisión en palabras temporizadas sin transcripción.

Audiolibros: ensamblar voces, definir etiquetas, exportar MP3 o MP4 con portada

MCP 1.15.0 añade el mismo flujo de trabajo de Audio y audiolibro disponible en el Editor de vídeo. Lee get_editor_guide para audiobookTimeline, o lee el proyecto actual antes de editar. Define timeline.mode como audiobook para una línea de tiempo de hasta 7.200 segundos (dos horas), 1.000 clips y 24 capas. El modo de vídeo mantiene su límite de diez minutos/500 clips.

  1. Busca grabaciones existentes mediante list_editor_media / get_editor_media, o súbelas/impórtalas. Genera voz nueva solo cuando se solicite, usando el descubrimiento de modelos, una estimación de créditos y las herramientas Gemini TTS existentes. El editor ensambla grabaciones; no adivina el hablante de cada línea.
  2. Añade una capa de audio para cada narrador, diálogo, música o efectos según sea necesario. Usa append_editor_audio con los asset_ids en orden, track_id, la revision actual y gap_seconds opcional (0–60). Añade clips completos a esa capa sin huecos por redondeo de fotogramas. Nunca ordena nombres de archivo ni recorta la última parte para que encaje. Para solapamientos o temporización personalizada usa las operaciones de clip existentes. Los recortes, la velocidad, el volumen, los fundidos, el silencio y las capas ocultas afectan a la mezcla; cambiar la velocidad cambia el tono.
  3. Guarda etiquetas, tasa de bits y portada mediante edit_editor_project, por ejemplo:
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 sustituye la configuración de audio guardada: conserva los campos que el usuario no haya pedido cambiar. Todas las etiquetas son cadenas. artist registra narradores/intérpretes, composer puede registrar el autor, album identifica el libro, year tiene cuatro dígitos y track es un número o número/total. No inventes créditos ni copyright. Un título vacío recurre al título del proyecto. El MP3 contiene etiquetas Unicode ID3v2.3 y, si se selecciona, una imagen APIC de portada frontal. La imagen se incrusta en el archivo, en lugar de referenciarse por URL. El MP3 permite no tener portada; el MP4 con portada requiere una. Las tasas de bits son 96, 128 (predeterminada), 192, 256 o 320 kbps.

  1. Envía export_editor_project con la revisión guardada y format: "mp3" o format: "mp4-cover". Solicita ambos cuando se quieran ambos archivos. Cada proyecto/revisión/formato tiene su propio trabajo persistente, por lo que un formato nunca sustituye a otro. Consulta get_editor_export dejando al menos cinco segundos entre consultas hasta completed o failed. Las etapas incluyen cargar recursos, mezclar audio con progreso, codificar y guardar. Un cliente desconectado no cancela el trabajo; volver a enviarlo lo recupera. Los trabajos fallidos requieren un retry_failed: true explícito.
  2. Confirma status: "completed", assetId y los enlaces firmados de descarga/reproducción. Comprueba la mezcla final, la duración, las etiquetas solicitadas y la imagen antes de informar de la finalización. El MP3 se guarda como un recurso de Biblioteca de audio; el MP4 con portada es un recurso de vídeo. La inspección solo de fotogramas no puede verificar audio ni metadatos. La herramienta pública de uso compartido de vídeo no es para archivos MP3; la colaboración privada en proyectos sigue disponible.

El formato mp4-cover muestra una portada ajustada sobre el fondo del proyecto durante toda la duración del audio. Los clips visuales de la línea de tiempo, el texto y los subtítulos se excluyen de este formato. Para renderizarlos, usa la exportación MCP format: "webm" existente (predeterminada, hasta dos minutos) o la exportación MP4/WebM del navegador (hasta diez minutos).

Las exportaciones de audio son solo para el propietario, no cuestan créditos de generación y requieren el worker persistente del editor más FFmpeg/ffprobe con libmp3lame y libx264. Chromium no es necesario para estos dos formatos. Límites: 1 GB de archivos fuente, 300 MB por archivo exportado, 64 segmentos de clips de audio por cada ventana de mezcla de 30 segundos. Usa una tasa de bits más baja o divide un libro más grande en partes. La configuración y las referencias de portada persisten en la línea de tiempo, se comprueban por revisión y siguen los permisos de medios del proyecto tras compartirlo o transferir la propiedad. Esta versión no añade marcadores de capítulo, clonación de voz ni asignación automática de hablantes.

Galería y paquetes de estilos compartidos

/video-editor/gallery y el panel Diseño muestran los mismos 30 paquetes de estilos nativos originales que el Kit local. Cada uno contiene cinco escenas editables, una vista previa silenciosa de 12 segundos, una ilustración original etiquetada, prompt, rúbrica y manifiesto hash. Es una demostración reutilizable de familias de escenas, no una campaña factual de producto. Las rutas de vista previa de get_creative_item son relativas a /api/video-editor/creative-assets/; contienen solo material original incluido, nunca medios de la cuenta.

create_style_example importa la imagen de origen real a la Biblioteca del propietario que ha iniciado sesión y reasigna el ID de medio de la línea de tiempo. Usa v4v:write, sin créditos de generación. apply_style(dry_run=true) también requiere acceso de edición y la revisión actual, informa de clips cambiados/bloqueados/no compatibles y no realiza ninguna escritura. Aplica con los mismos parámetros y revisión después de revisar el plan. El alcance de escena seleccionada cambia la transición entrante de esas escenas; los tiempos de clip y el audio permanecen fijos.

Presupuesto de generación limitado de Open Video Kit

create_generation_budget crea un límite compartido inmutable sin realizar cargos; get_generation_budget lee el gasto real y las reservas, close_generation_budget cierra permanentemente las nuevas asignaciones. Para los medios compatibles, estimate_generation devuelve un quote_token firmado válido durante cinco minutos. Pasa budget_id, max_credits y quote_token juntos en el generate_lab / generate_studio actual; idempotency_key es obligatorio. Las repeticiones exactas de solicitudes aceptadas no activan una segunda generación. Las reservas paralelas se contabilizan en el servidor; el chat con precio por token queda excluido de esta ruta. El presupuesto no es una autorización independiente del usuario para gastar créditos. Contrato detallado y validaciones: Cloud Kit.

Estilos de referencia privados (Open Video Kit 0.1.24)

get_reference_guide / v4v://reference-style documenta el flujo de trabajo compartido. analyze_reference_style acepta un reference_id estable, un recurso de Biblioteca en propiedad (source: { type: "asset", assetId }) o una URL pública explícita de video|image|page. Devuelve paletas medidas, límites/ritmo provisionales y tiempos de fotograma reales; get_reference_frame devuelve contenido PNG. Inspecciona todos los fotogramas registrados antes de review_reference_style, que requiere reglas originales de tipografía/diseño/movimiento/transición/ritmo, tokens completos, limitaciones del revisor y citas de tiempo/SHA-256. get_reference_profile devuelve JSON portátil privado. apply_reference_style usa por defecto ejecución de prueba; para confirmar se requiere la revisión actual de un proyecto en propiedad, incluida la revisión cero. El metraje de referencia nunca se incrusta en el montaje ni en el ZIP.

Las herramientas de lectura requieren v4v:read; el análisis/revisión/aplicación requiere v4v:read y v4v:write. No requieren v4v:generate ni consumen créditos de generación. Los archivos privados de evidencia de referencia/fábrica de V4V se cifran con claves por objeto conservadas solo en manifiestos de base de datos con ámbito del propietario, y los archivos privados se bloquean en la entrega genérica de recursos. La propiedad original en la Biblioteca de la referencia se comprueba al acceder. Consulta implementación y límites ucranianos.

Máscaras geométricas de clip y parallax por capas

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 y recipes.parallax se comparten con Estudio local. Este último proporciona movimiento editable de dos capas mediante fotogramas clave de posición normales. Previsualiza los fotogramas reales; esto no es una estimación automática de profundidad. Los controles de GUI compartidos están en Diseño → Efectos. El ZIP conserva las máscaras; la inspección de texto devuelve TEXT_MASK_REVIEW porque las comprobaciones de límites no pueden garantizar la legibilidad dentro de una máscara curva. Consulta el contrato bilingüe compartido.

29

Colecciones creativas y planificación de agentes#

Diseño → Bibliotecas ofrece 28 composiciones nativas editables, incluidas collage, movimiento continuo de cámara, paneles elásticos, personajes pintados, subtítulos, recorridos de producto y secuencias de lanzamiento. Kit 0.3.7 también incluye diez estilos originales, cinco efectos ráster y quince transiciones. Las trece transiciones shader requieren WebGL y generan hasta 4096 píxeles por lado.

Usa get_reviewed_library_guide (recurso v4v://reviewed-libraries) para esquemas exactos, licencias de origen y límites. search_library_references y get_library_reference exponen 456 entradas de metadatos de referencia; no son plantillas ejecutables instaladas. plan_library_scene es de solo lectura y devuelve operaciones para edit_editor_project en la revisión actual. Usa medios de Biblioteca en propiedad o medios de proyecto local registrados; los bytes locales originales permanecen en el dispositivo del usuario. Inspecciona los fotogramas realmente renderizados después de editar.

Planificar con IA guarda el proyecto y prepara una solicitud editable de Video Factory. No envía un comando, no consume créditos, no sube originales ni autoriza la generación. El agente aclara las decisiones creativas relevantes que falten antes de editar. El renderizado nativo no necesita ningún servicio de generación; las acciones de pago opcionales mantienen los presupuestos existentes y la aprobación explícita. No está habilitado ningún instalador ascendente, HTML/JavaScript arbitrario, música ejecutable ni lector del historial local. La revisión de origen/licencia y los equivalentes originales se incluyen en la documentación versionada del Kit.

Calidad del montaje y evidencia

Lee get_montage_quality_guide / v4v://montage-quality para las reglas de criterio compartidas y los límites honestos de evidencia. plan_montage_beats deriva cortes visuales alineados a fotogramas a partir de temporizaciones reales de palabras; plan_compact_captions agrupa 1–3 palabras sin inventar marcas temporales. analyze_ui_regions mide los límites de capturas de pantalla en propiedad; rectify_ui_region crea una imagen separada corregida por perspectiva a partir de una huella digital/ID de región devueltos. detect_media_scenes mide cortes visuales en una ventana de origen de hasta 600 segundos. Estas operaciones conservan la fuente y no generan medios de pago.

compare_narration_transcript requiere una run_id de transcripción completada en propiedad del audio_asset_id exacto; compara la transcripción real con script y nombres confirmados opcionales. El texto ASR no establece el acento de pronunciación ni una locución natural. Compra la transcripción o una nueva toma solo mediante el flujo habitual de autorización con presupuesto.

preview_editor_project acepta hasta 12 times de fotograma reales; contact_sheet: true devuelve una imagen para revisión. El modo navegador de Factory realiza la inspección/rectificación en el dispositivo del usuario y mantiene los originales en local. Los llamadores MCP externos que usen un original solo de navegador reciben BROWSER_REQUIRED; usa el agente abierto de Factory para esas operaciones de navegador. Los nuevos comandos de Factory registran respuestas separadas de revisión de contenido/acabado para ocho preguntas explícitas de evidencia. La evidencia desconocida no es una revisión aprobada.

Los resultados fallidos de get_task incluyen error.provider_error, el motivo saneado del servicio del modelo y error.provider: "managed". Los fallos conocidos incluyen un hint y retryable; los límites de tasa/tiempos de espera transitorios también proporcionan retry_after_seconds: 60. Lee el motivo antes de cambiar la solicitud o pedir otro intento de pago. Los errores desconocidos conservan su motivo saneado sin asumir que un reintento vaya a funcionar. Las respuestas de tareas REST y las devoluciones de llamada firmadas de task.failed usan los mismos campos; consulta diagnóstico de generación fallida.