Ir a la documentación
v4v.Documentación para desarrolladoresPREVIEWTus claves de API ↗
EN ESTA GUÍA
AutenticaciónDescubrir modelos de LaboratorioSubtítulos temporizados del hablaModelos de última generaciónModelos de vídeo Kling 4.0Chat GPT-6 AstraLAB con una imagen externaSubir contenido multimedia privadoEstudio con contenido multimedia externo o privadoTareas y créditosRenombrar y organizar proyectosIdempotenciaCallbacks firmadosErrores y límitesGeneración masiva de Studio (API y MCP)
Disponible para pruebas
Vista previa de acceso directo
API reference · v1

Crea con la API de V4V.

Genera imágenes, vídeo y audio desde tus propias aplicaciones. Una clave API. Tus créditos de V4V actuales.

Empezar →Descargar OpenAPI ↓
ENDPOINThttps://v4v.ai/api/v1
cURL
curl https://v4v.ai/api/v1/models \
  -H "Authorization: Bearer $V4V_API_KEY"
01

Autenticación#

Crea una clave con nombre en Perfil → Claves de API. Guarda el secreto de API y el secreto de firma del webhook cuando aparezcan; solo se muestran una vez. Se pueden crear y revocar varias claves de forma independiente. Los secretos de clave se almacenan como hashes SHA-256.

Envía Authorization: Bearer v4v_live_… en cada solicitud de API. Mantén esta clave en tu servidor, fuera de las aplicaciones de navegador y del control de código fuente. La revocación bloquea futuras solicitudes; las generaciones ya aceptadas continúan.

URL base: https://v4v.ai/api/v1.

02

Descubrir modelos de Laboratorio#

GET /models enumera los ID de modelos actuales de Laboratorio, estado habilitado, entradas, parámetros, valores predeterminados, condiciones y límites. GET /models/{model} describe un modelo. Los ID y esquemas proceden del mismo catálogo y de los mismos valores predeterminados que usa Laboratorio. La configuración de Estudio es independiente.

Los nombres de modelo en los ejemplos siguientes son IDs reales del catálogo. Usa discovery para encontrar los modelos habilitados actualmente en tu cuenta. Los nombres de campo son específicos del modelo: conserva los nombres devueltos por discovery, incluidos los nombres en camelCase como aspectRatio o referenceImageUrls. Los valores de selección son cadenas; también se aceptan valores numéricos para opciones de selección con apariencia numérica. Los campos pueden proporcionarse en input o en parameters, pero nunca en ambos. Los campos desconocidos se rechazan. Los modelos con versiones seleccionables exponen parameters.variant; usa los valores y valores predeterminados devueltos por discovery.

bash
curl https://v4v.ai/api/v1/models \
  -H "Authorization: Bearer $V4V_API_KEY"
03

Subtítulos temporizados del habla#

Descubre ai.speech_to_text con el tipo subtitle. Envía un ID de archivo multimedia propio o una URL compatible en input.audioUrl o input.videoUrl a POST /lab; los parámetros opcionales incluyen language_code (por ejemplo uk, en o auto) y diarize. La estimación usa la duración original de la fuente. La transcripción consume créditos normales de la cuenta.

Una tarea completada devuelve results[].type: "subtitle", la transcripción text, srt y cues editable con start, end en segundos y text. Una entrada silenciosa correcta puede tener una lista de cues vacía. Para montaje, usa las herramientas MCP del Editor de vídeo para alinear estos cues con el recorte, la velocidad y la posición en la línea de tiempo de un clip fuente.

04

Modelos de última generación#

Omni Flash 1.2 (video.gemini_omni_flash-1-2) es el modelo preferido para solicitudes de vídeo sin un modelo explícito. El Laboratorio lo muestra primero; Omni Flash 1.1 sigue disponible en Más y con su ID actual. Descubre los parámetros actuales con GET /models/{model}. La versión 1.2 admite generación y edición de 3 a 15 segundos; la interpolación entre primer/último fotograma está limitada a 10 segundos. Las tarifas compartidas de 4/6/8/10 segundos coinciden con los precios configurados de la 1.1. Usa discovery y las estimaciones actuales para los precios en lugar de guardar esta relación como una regla permanente.

Elige GPT Image 2.6 mediante parameters.variant en image.text_to_image o ai.image_edit. Usa parameters.outputFormat con estas capacidades exactas por variante:

VarianteFormatos de salida
gpt-image-2.6-flare-textpng, jpeg, webp, gif, svg
gpt-image-2.6-sunburst-textpng, jpeg, webp, gif, svg
gpt-image-2.6-flare-imgpng, jpeg, webp
gpt-image-2.6-sunburst-imgpng, jpeg, webp
gpt-image-2.6-economy-textpng, gif
gpt-image-2.6-economy-imgpng

parameters_schema.outputFormat.allowed_by_variant es la fuente autorizada. Flare/Sunburst se liquidan según el uso real de entrada/salida; el uso de conversión SVG se incluye en el total final. Economy es solo 1K con precio por imagen. Las descargas conservan los fotogramas GIF y los bytes vectoriales SVG; las descargas SVG usan entrega como archivo adjunto.

Nano Banana 2.1 usa parameters.variant: "nano-banana-v2.1" en los mismos módulos de imagen, con hasta 10 referencias y salida 1K/2K/4K. Su modo de facturación actual se publica en . La generación de Google/Vertex se liquida a partir de la entrada verificada, la entrada en caché, la salida de imagen, la salida de texto y los tokens de thinking, con margen aplicado y el total combinado redondeado hacia arriba una sola vez. El componente de salida de imagen es de aproximadamente 11/16/36 créditos V4V para 1K/2K/4K antes de la entrada y del thinking. El Laboratorio y las estimaciones muestran un rango aproximado; la reserva inicial es independiente del coste final. Otras rutas usan la tarifa por imagen configurada. La gestión del enrutamiento sigue estando a cargo de V4V; no proporciones un parámetro de routing.

05

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 , o su declarado. Las menciones no declaradas se rechazan.

06

Chat GPT-6 Astra#

Descubre chat.gpt_6_astra con GET /models/chat.gpt_6_astra (slug: gpt-6-astra). Tiene el tipo chat y devuelve texto. El discovery incluye las tarifas por token y la regla de redondeo.

json
{
  "model": "chat.gpt_6_astra",
  "input": {
    "prompt": "Explain what is in this image.",
    "imageUrls": [
      "https://example.com/image.png"
    ]
  },
  "parameters": {
    "reasoningEffort": "high",
    "webSearch": true,
    "stream": false
  }
}

Send this body to POST /lab. Images are optional; up to 12 URLs or owned file IDs are accepted. Text-only requests use string input upstream; image requests use an array of message content. Reasoning effort: low, medium, high, xhigh (default low). Web search and streaming default to false. Streamed responses are returned as a completed task after generation finishes.

Para ofrecer una función, pasa input.functionTools como una cadena JSON que contenga de 1 a 10 definiciones con type: "function", name, description y parameters (un objeto JSON Schema). Establece parameters.webSearch en false. La solicitud upstream usa tool_choice: "auto"; las solicitudes de función se devuelven en results[].function_calls para que tu aplicación las gestione. El nodo de modelo no ejecuta funciones ni continúa la conversación con el resultado de una función.

Chat reserva 1 crédito antes de entrar en la cola. Esta es una reserva mínima, no un precio fijo ni un límite de gasto. Tarifas por 1M tokens: entrada 560, entrada en caché 56, escrituras de caché 700, salida 2.800 créditos. El coste combinado de tokens se redondea hacia arriba una sola vez a un crédito entero, con un cargo mínimo de 1. Después de la respuesta, cualquier cargo adicional se deduce de forma atómica del saldo disponible. Si el saldo es insuficiente, la tarea falla y la reserva no utilizada se libera.

Para chat e imágenes con precio por uso, el endpoint de estimación también devuelve credits_range con min, max, assumptions, includes_markup: true, is_estimate: true y is_spending_cap: false. Muéstralo como un rango aproximado en créditos V4V. Incluye el margen actual y los ajustes de precio. Estos son escenarios de uso ilustrativos; el coste real puede quedar fuera del rango. y describen la reserva inicial por separado. El rango no altera la liquidación por uso real ni habilita la admisión con presupuesto rígido.

07

LAB con una imagen externa#

Las entradas multimedia aceptan una URL externa o un ID de archivo de V4V en el mismo campo. Los arrays pueden mezclar ambos. Las URL deben devolver archivos multimedia reales sin cookies del navegador ni inicio de sesión interactivo. Se recomiendan HTTPS y URL firmadas con una validez suficientemente larga. V4V valida y copia los archivos multimedia externos antes de la generación; se rechazan las URL de redes internas y las redirecciones inseguras.

bash
curl https://v4v.ai/api/v1/lab \
  -H "Authorization: Bearer $V4V_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: product-edit-001' \
  -d '{"model":"ai.image_edit","input":{"prompt":"Place this product on a marble counter","referenceImageUrls":["https://example.com/product.jpg"]},"parameters":{"variant":"nano-banana-2","aspectRatio":"9:16","resolution":"2K"}}'
08

Subir contenido multimedia privado#

POST /files acepta un campo file usando multipart/form-data. Se admiten imágenes, vídeo y audio, sujetos a los límites del modelo. El límite de subida predeterminado es 100 MiB, restringido además por el límite de subida de almacenamiento y el límite del proxy de la implementación. Los archivos deben contener contenido multimedia decodificable; la inspección de audio/vídeo requiere ffprobe en el servidor.

bash
curl https://v4v.ai/api/v1/files \
  -H "Authorization: Bearer $V4V_API_KEY" \
  -F 'file=@product.png'
json
{
  "id": "6aa962444bd1dd7ab65bc6b6",
  "type": "image",
  "content_type": "image/png",
  "size": 123456
}

Usa directamente el ID devuelto, sin prefijo file_. GET /files/{id} consulta los metadatos de tu archivo sin consumir créditos.

json
{
  "model": "ai.image_edit",
  "input": {
    "prompt": "Create a studio product photograph",
    "referenceImageUrls": [
      "6aa962444bd1dd7ab65bc6b6",
      "https://example.com/side.jpg"
    ]
  },
  "parameters": {
    "variant": "nano-banana-2"
  }
}
09

Estudio con contenido multimedia externo o privado#

POST /studio usa el mismo flujo de trabajo de Estudio seleccionado, preparación, ejecución del modelo, multiplicador de precio y descuento de suscripción que la interfaz de Estudio.

json
{
  "input": {
    "product_name": "Example Product",
    "product_description": "Lightweight everyday backpack",
    "product_images": [
      "https://example.com/front.jpg",
      "6aa962444bd1dd7ab65bc6b6"
    ],
    "prompt": "Show the product in everyday use"
  },
  "parameters": {
    "duration": 10,
    "aspect_ratio": "9:16",
    "style": "UGC",
    "language": "en",
    "avatar": null
  },
  "callback_url": "https://partner.example/webhooks/v4v"
}

Para un flujo totalmente privado, primero sube cada imagen de producto usando POST /files y después pon los IDs devueltos en input.product_images. Sube las referencias de avatar, audio y vídeo del mismo modo.

Estudio acepta product_id (un producto guardado propio), avatar_id (un avatar de biblioteca propio o público activo, con prefijo public: compatible), product_name, product_description, prompt, product_images, reference_images, avatar_media, audio y video. Cada campo multimedia acepta referencias; los arrays admiten varios archivos. parameters.avatar acepta un ID de avatar de biblioteca, una única URL de imagen o ID de archivo, o null. Elige input.avatar_id o parameters.avatar. Los campos de producto explícitos sustituyen los valores predeterminados de la biblioteca. Los nombres/IDs de estilo activos aplican las instrucciones de estilo guardadas. Los valores de estilo desconocidos, inactivos o vacíos devuelven 422 INVALID_PARAMETER, field: "parameters.style" y error.allowed_values que contienen los IDs/nombres activos. Omite el estilo para usar el valor predeterminado actual (UGC cuando esté activo; en caso contrario, el primer preset activo). Los parámetros también incluyen style, language, voice, placement, duration, aspect_ratio y quality.

Migración para clientes que antes pasaban texto libre en parameters.style: mueve esa dirección creativa a y elige un estilo activo desde MCP (o omite el estilo para usar el valor predeterminado actual). Un estilo mal escrito ya no se convierte en un estilo personalizado.

10

Tareas y créditos#

La generación devuelve HTTP 202 después de validar la entrada y, cuando hay capacidad disponible, de reservar créditos, sin esperar a la generación:

json
{
  "task_id": "task_6aa962444bd1dd7ab65bc6b6",
  "status": "queued",
  "credits_reserved": 20,
  "created_at": "2026-09-15T18:00:00Z"
}

Nombre de proyecto opcional

Tanto POST /lab como POST /studio aceptan project_name en el nivel superior, junto con input, parameters y callback_url:

json
{
  "project_name": "Summer campaign — product photo",
  "model": "image-upscale-topaz",
  "input": {
    "image_url": "https://example.com/product.png"
  },
  "parameters": {
    "upscale_factor": "2"
  }
}

El nombre recortado (de 1 a 200 caracteres, no vacío) pasa a ser el título en Proyectos y, para LAB, en ejecuciones antiguas. Si se omite, se usa el título predeterminado existente. La respuesta de la tarea incluye project_name y project_id. Cambiar el nombre con la misma clave de idempotencia es un conflicto, igual que cambiar las entradas de generación.

Estado de la tarea

El servidor actualiza el estado de la generación en segundo plano. El sondeo devuelve el último status guardado: queued, processing, completed, failed o cancelled. Mientras la tarea esté en queued o processing, muestra un indicador de carga. Cuando status sea completed, lee el texto del chat desde results[].text o descarga los archivos multimedia desde results. Para failed, inspecciona error (incluidos el stage, brief_completed, retryable fallidos y el retry_after_seconds sugerido cuando se conozca) y credits_used. Una generación breve correcta puede conservar su cargo si el renderizado falla; una sugerencia de reintento transitoria no inicia ni autoriza un nuevo intento de pago. cancelled también es terminal.

Los webhooks son opcionales. Sin callback_url, repite la siguiente solicitud cada 3–5 segundos hasta que status sea completed, failed o cancelled:

11

Renombrar y organizar proyectos#

La organización de proyectos utiliza las mismas carpetas que el espacio de trabajo de Projects. No genera contenido multimedia, no reserva créditos ni cambia las entradas de generación, los resultados ni los hashes de idempotencia. Todas las operaciones requieren tu clave de API y solo acceden a los proyectos y carpetas de tu cuenta.

Método y rutaFinalidad
GET /projectsEncontrar proyectos de Estudio, Flujos de trabajo y Laboratorio, incluidas las tareas de API en cola
PATCH /projects/{project_id}Renombrar un proyecto y/o moverlo a una carpeta
GET /project-foldersListar las carpetas del espacio de trabajo
POST /project-foldersCrear una carpeta con {"name":"Summer campaign"}
PATCH /project-folders/{folder_id}Renombrar una carpeta con {"name":"Autumn campaign"}

Ambos endpoints de listado aceptan offset (valor predeterminado: 0) y limit (1–100, valor predeterminado: 50), y devuelven total y next_offset (null en la última página). Los proyectos se ordenan del más reciente al más antiguo con un desempate estable por ID; las carpetas se ordenan por nombre. Los filtros de proyecto son source=all|studio|workflow|lab, q (búsqueda literal del título, sin distinguir mayúsculas de minúsculas, de hasta 200 caracteres) y folder_id (un ID de carpeta en propiedad, o unfiled para ninguna carpeta). Omite folder_id para incluir todas las carpetas.

GET /projects devuelve projects con project_id, project_name, source, folder_id (cadena o null), status, created_at y updated_at. El estado refleja el proyecto original o el historial del Laboratorio; usa GET /tasks/{task_id} para el estado de generación. Usa el devuelto para las actualizaciones; las entradas heredadas del Laboratorio sin un proyecto de respaldo usan su ID de ejecución del Laboratorio. devuelve con , , , y .

12

Idempotencia#

Envía Idempotency-Key (de 1 a 200 caracteres) al enviar solicitudes del Laboratorio o de Estudio. La misma cuenta, valor de clave, endpoint y contenido JSON devuelven la tarea original, incluso entre distintas claves de API de esa cuenta. Se ignora el orden de las propiedades del objeto. Reutilizar una clave para contenido distinto devuelve HTTP 409 IDEMPOTENCY_CONFLICT. Si la solicitud original aún se está validando, HTTP 409 REQUEST_IN_PROGRESS te pide que reintentes con la misma clave. Un envío rechazado sigue asociado a su clave; corrígelo usando una clave nueva.

Los índices únicos persistentes evitan que los reintentos simultáneos creen otra generación o reserva. Los registros de idempotencia permanecen con el historial de tareas.

13

Callbacks firmados#

Proporciona un callback_url público opcional. V4V publica task.completed o task.failed con los campos de la tarea, la lista de resultados y event_id estable. Los callbacks tienen las cabeceras X-V4V-Timestamp y X-V4V-Signature: v1=<hex>. Verifícalos usando el secreto de firma del webhook que se mostró cuando se creó la clave de API.

La firma es HMAC-SHA256 sobre la marca de tiempo, un punto literal y el cuerpo bruto exacto de la solicitud. Rechaza las marcas de tiempo antiguas (por ejemplo, de más de cinco minutos) y compara las firmas en tiempo constante.

javascript
import crypto from 'node:crypto';
const expected = crypto.createHmac('sha256', webhookSecret)
  .update(`${timestamp}.${rawBody}`).digest('hex');
const valid = /^v1=[a-f0-9]{64}$/.test(signature)
  && Math.abs(Date.now() / 1000 - Number(timestamp)) < 300
  && crypto.timingSafeEqual(Buffer.from(signature.slice(3), 'hex'), Buffer.from(expected, 'hex'));

Devuelve una respuesta 2xx sin demora. La entrega es al menos una vez: elimina duplicados por event_id. Los fallos de red, los tiempos de espera, las respuestas HTTP 408/429 y 5xx se reintentan con retroceso exponencial, empezando en 30 segundos y con un máximo de una hora, hasta 12 intentos por defecto. Otras respuestas no satisfactorias, incluidas las redirecciones, detienen la entrega. Los reintentos nunca crean generaciones ni cobran créditos. Consulta el estado de la tarea si se agota la entrega del callback.

Callbacks por lotes de Studio

POST /studio/batches también acepta un callback_url opcional. Se aplica la misma verificación de callbacks firmados. Los eventos son batch.updated, batch.completed, batch.paused y batch.cancelled, con un event_id estable, batch_id, batch_revision, observed_at, state_token, recuentos y totales de créditos. Lee GET /studio/batches/{batch_id} para obtener los resultados paginados actuales. Los eventos contienen instantáneas compactas en lugar de URL de descarga que caducan; los cambios intermedios pueden agruparse entre ticks del worker.

La entrega es duradera y se reintenta de forma independiente de la generación. Elimina duplicados por event_id y tolera eventos fuera de orden; la entrega repetida conserva el mismo cuerpo. Los receptores lentos o con fallos no crean nuevas generaciones ni bloquean la cola de generación. La cancelación puede emitir una actualización adicional cuando termina el trabajo ya admitido. Un reinicio o retrabajo solicitado más tarde reactiva la supervisión. Un webhook es una integración HTTP y no despierta por sí mismo un chat del navegador ya finalizado.

14

Errores y límites#

Los errores usan un único formato:

json
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Allowed values: 5, 10.",
    "field": "parameters.duration"
  }
}

HTTP 400/422 indica entrada o parámetros no válidos; 401 una clave no válida/revocada; 402 créditos insuficientes; 403 modelos deshabilitados o acceso denegado; 404 modelos/archivos/tareas no disponibles; 409 un conflicto de idempotencia o una validación en curso; 429 un límite de tasa/concurrencia; 500 un error interno; y 503 indisponibilidad temporal del servicio. Los códigos de error incluyen INVALID_API_KEY, INSUFFICIENT_CREDITS, MODEL_NOT_FOUND, MODEL_DISABLED, INVALID_INPUT, INVALID_PARAMETER, INVALID_MEDIA_URL, MEDIA_NOT_ACCESSIBLE, UNSUPPORTED_MEDIA_TYPE, MEDIA_TOO_LARGE, FILE_NOT_FOUND, FILE_ACCESS_DENIED, RATE_LIMIT_EXCEEDED, GENERATION_FAILED, GENERATION_SERVICE_ERROR y SERVICE_UNAVAILABLE. GENERATION_SERVICE_ERROR identifica un error interno notificado del servicio del modelo; no establece que el tamaño de la entrada o los parámetros fueran no válidos. Los ID de archivo inexistentes e inaccesibles comparten una respuesta 404 para evitar revelar archivos de otras cuentas.

Default limits are 120 requests per minute per key, 10 generation submissions per minute per account, and 3 concurrent accepted generations per account. Every HTTP 429 includes error.retryable and a positive integer error.retry_after_seconds; the HTTP Retry-After header uses the same value. Request-window errors also return reason: "request_rate_limit", the configured limit, and a public scope (key, generation, bulk, mcp-upload-link or mcp-upload), without internal account/key IDs. The retry delay is the rounded-up time remaining in the minute window, not always 60 seconds. MCP tool errors preserve these fields in their JSON even when HTTP headers are unavailable. Account contention uses its own reason: "account_busy" and one-second delay. Generation capacity is handled separately by the durable queue; wait for the accepted task rather than resubmitting it.

json
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded. Retry after 18 seconds.",
    "reason": "request_rate_limit",
    "scope": "key",
    "limit": 120,
    "retryable": true,
    "retry_after_seconds": 18
  }
}

Para rechazos de ventana de solicitud (antes de la creación de la tarea), espera el retraso indicado y reutiliza la misma clave de idempotencia y los mismos argumentos. Una respuesta que identifica una tarea ya fallida es terminal para esa tarea. Esto no autoriza otro intento de pago después de un fallo terminal de generación.

15

Generación masiva de Studio (API y MCP)#

La generación masiva está disponible a través de la API y de MCP. Todavía no hay un espacio de trabajo masivo en la interfaz de Studio. Envía hasta 300 productos en una solicitud JSON. Cada elemento crea un flujo de trabajo de Studio con su propia tarea, flujo de trabajo/configuración guardados, resultados y contabilización de créditos. La importación de productos y las descargas de referencias se realizan en segundo plano; un elemento no válido falla de forma independiente mientras los elementos restantes continúan.

Studio, LAB, REST, MCP, Shopify y la generación de avatares comparten una cola de servidor persistente con un límite absoluto de 10 solicitudes de generación activas para este despliegue. Esperar un resultado de generación ocupa una plaza. Una generación finalizada libera esa plaza incluso mientras se guarda su archivo. Las solicitudes normales tienen prioridad sobre las solicitudes masivas; lo masivo usa la capacidad disponible, sujeto a los límites globales de masivo y por cuenta de un administrador. Los valores predeterminados son 2 flujos de trabajo masivos simultáneos y 1 por cuenta. Varios lotes pertenecientes a una misma cuenta comparten ese límite. El procesamiento continúa sin un navegador abierto ni sondeo del cliente.

Crear un lote

POST /api/v1/studio/batches — devuelve HTTP 202. Proporciona una cabecera Idempotency-Key obligatoria de 1 a 200 caracteres. Reutiliza la misma clave y un JSON idéntico tras una interrupción de red. Un cuerpo modificado con la misma clave devuelve HTTP 409; la aceptación nunca crea un segundo lote por un reintento.

bash
curl "$V4V_BASE_URL/api/v1/studio/batches" \
  -H "Authorization: Bearer $V4V_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: autumn-catalogue-001' \
  --data '{
    "name": "Autumn catalogue",
    "max_credits": 600,
    "input": { "prompt": "Show three benefits of this product in a calm reveal" },
    "parameters": { "duration": 8, "aspect_ratio": "9:16", "quality": "720p" },
    "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_description": "Adjustable warm light",
          "product_images": ["https://shop.example/lamp.jpg"]
        },
        "parameters": { "style": "TV Spot" }
      }
    ]
  }'

Usa la duración, el formato y la calidad compatibles con el flujo de trabajo actual de Studio de tu despliegue, igual que para POST /api/v1/studio. El ejemplo presupuesta 600 créditos para tres clips Omni de 8 segundos a 720p: 3 × 180 = 540 créditos, dejando 60 créditos de margen. Tres clips de 10 segundos a 720p usan 675 créditos; a 1080p usan 990 y a 4K usan 1.980, antes del precio del vídeo de referencia, pasos adicionales o reintentos. Obtén siempre estimaciones actuales para las entradas exactas antes de elegir un presupuesto de lote.

V4V / API reference · v1Crea algo que merezca la pena ver.
pricing_by_variant

Gemini 4 Argon (chat.gemini_4_argon) también está disponible a través del Laboratorio, Flujos de trabajo y API/MCP. Su uso de entrada, entrada en caché, salida y razonamiento se liquida después de la respuesta. Consulta en el discovery del modelo los precios actuales, las fechas de lanzamiento y los ajustes de tarifas.

@image_1
@video_1
@name

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.

credits_estimated
initial_reservation_estimated

GET /tasks/{task_id} y los callbacks de finalización devuelven texto en línea sin requerir un archivo multimedia:

json
{
  "status": "completed",
  "credits_reserved": 3,
  "credits_used": 3,
  "results": [
    {
      "type": "text",
      "text": "The image shows…",
      "incomplete": false,
      "function_calls": [],
      "usage": {
        "input_tokens": 4443,
        "uncached_input_tokens": 4443,
        "cached_input_tokens": 0,
        "cache_write_tokens": 0,
        "output_tokens": 47
      },
      "credits": 3
    }
  ]
}

credits_reserved refleja la reserva ampliada después de la liquidación. incomplete: true significa que se alcanzó el límite de salida; los tokens consumidos se siguen facturando. Sondear repetidamente o reintentar con la misma clave de idempotencia no crea otro cargo.

input.prompt
describe_studio

El flujo de trabajo seleccionado determina los límites. ProVid admite de 4 a 15 segundos enteros, 480p/720p/1080p y proporciones 9:16, 16:9, 1:1, 4:5, 4:3, 3:4, 21:9, adaptive. OmniVid admite 4/6/8/10 segundos, 360p/720p/1080p/4k y 9:16 o 16:9. Las nuevas solicitudes de OmniVid en Estudio usan por defecto 720p y 10 segundos salvo que se proporcionen ajustes explícitos. Las opciones no válidas devuelven un error de validación. También se aplican los límites de combinación de contenido multimedia. OmniVid admite IDs de referencia de audio en LAB, pero no acepta archivos de referencia de audio sin procesar en Estudio; las referencias no compatibles devuelven un error de validación.

bash
curl "$V4V_BASE_URL/api/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $V4V_API_KEY"

Al completarse, lee los resultados de texto en línea; descarga los archivos multimedia desde results[].url. Mientras se guardan los archivos generados, la tarea sigue en processing; el éxito de la generación por sí solo no equivale a la finalización. Repite la solicitud de estado para actualizar las URL de descarga caducadas. El sondeo no inicia otra generación ni consume créditos.

Haz sondeo de GET /tasks/{task_id} o proporciona una URL de callback. El estado es queued, processing, completed, failed o cancelled. El sondeo requiere una clave API propiedad de la misma cuenta que la tarea.

json
{
  "task_id": "task_6aa962444bd1dd7ab65bc6b6",
  "source": "lab",
  "status": "completed",
  "credits_used": 18,
  "results": [
    {
      "type": "video",
      "url": "https://v4v.ai/api/v1/results/…",
      "content_type": "video/mp4",
      "size": 18392832,
      "expires_at": "2026-09-16T00:00:00Z"
    }
  ]
}

Cada resultado multimedia incluye valores estables de asset_id y file_id. Usa file_id en entradas multimedia de generación posteriores. Las respuestas también incluyen project_id. La lista de resultados admite varias imágenes, vídeos y archivos de audio. Los enlaces de resultado están firmados y pueden usarse sin cookies de V4V ni autenticación. Vuelve a consultar el estado de la tarea para renovar los enlaces caducados. La garantía de reutilización consiste en un ID de archivo estable más una URL firmada renovable, mientras el archivo almacenado exista y el acceso siga permitido; no es una URL pública inmutable. Para reutilizar un resultado al día siguiente, resuelve de nuevo la misma tarea/ID de archivo y descárgalo mediante la nueva URL. Cualquiera que tenga un enlace de resultado puede usarlo hasta su caducidad.

Para solicitudes individuales de LAB/Studio, los créditos estimados se retienen cuando hay capacidad disponible en la cuenta. Si el límite configurado de tareas simultáneas está completo (3 por defecto), la solicitud devuelve la misma tarea en cola duradera con credits_reserved cero, credits_estimated y queue que contiene limit, retry_after_seconds: 5 y estimated_start_at: null. El worker admite las tareas en espera sin otro envío. Reserva créditos de forma atómica cuando se abre una plaza; si en ese momento el saldo es insuficiente, la tarea falla en stage: "admission" y programa su webhook. Reutiliza la clave de idempotencia original tras errores de red; no crees otra tarea para saltarte la espera. En lotes masivos, la estimación de cada elemento se retiene solo cuando ese elemento es admitido para empezar. Los cargos de generación consumen esa reserva. Los cargos por generación fallida siguen la ruta de reembolso existente; los créditos retenidos no usados se liberan al completarse o al fallar. Los pasos correctos de un flujo de trabajo de Estudio parcialmente fallido conservan sus cargos normales. Discovery, sondeo, consulta de archivos, callbacks y reintentos de callback no tienen cargo de generación.

GET /balance devuelve los créditos disponibles en ese momento. GET /usage devuelve las 100 solicitudes de generación más recientes de la cuenta. Profile muestra los recuentos de solicitudes/generaciones de por vida y los créditos liquidados de cada clave, además del historial reciente de tareas. Las cargas permanecen en la biblioteca del Laboratorio del usuario y pueden eliminarse allí.

project_id
GET /project-folders
folders
folder_id
name
color
created_at
updated_at
bash
# Discover projects and folders.
curl -H "Authorization: Bearer $V4V_API_KEY" \
  'https://v4v.ai/api/v1/projects?source=studio&limit=50'
curl -H "Authorization: Bearer $V4V_API_KEY" \
  'https://v4v.ai/api/v1/project-folders'

# Supply real IDs returned by the list endpoints.
curl -X PATCH "https://v4v.ai/api/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $V4V_API_KEY" -H 'Content-Type: application/json' \
  -d '{"project_name":"Summer campaign — approved","folder_id":"YOUR_FOLDER_ID"}'

Una actualización de proyecto acepta project_name (sin espacios al principio ni al final, de 1 a 200 caracteres), folder_id o ambos. Envía {"folder_id":null} para sacar un proyecto de cualquier carpeta. Los campos omitidos permanecen sin cambios. La respuesta contiene project_id y los campos actualizados. Los cambios de nombre y de ubicación también actualizan la tarea de API correspondiente y el historial del Laboratorio; las tareas en cola conservan la organización cuando se crean sus proyectos.

Los nombres de carpeta se recortan, deben contener entre 1 y 80 caracteres y son únicos dentro de una cuenta. La creación devuelve HTTP 201; el cambio de nombre devuelve 200, ambos con los campos de carpeta indicados arriba. Al renombrar se conservan el ID de la carpeta y sus proyectos. Un nombre duplicado devuelve 409 FOLDER_NAME_CONFLICT; los campos no válidos devuelven 422 INVALID_INPUT; los proyectos o carpetas inaccesibles devuelven 404 PROJECT_NOT_FOUND o FOLDER_NOT_FOUND. Después de una respuesta incierta al crear una carpeta, lista las carpetas antes de reintentarlo.

Las respuestas por lotes incluyen state_token, que cambia con el progreso o los controles significativos, y permanece estable cuando solo se renuevan las URL firmadas. MCP expone además wait_studio_batch para una espera acotada del lado del servidor durante una conversación activa; consulta supervisión de MCP.

CampoSignificado
nameNombre del lote obligatorio, de 1 a 200 caracteres
max_creditsPresupuesto de créditos positivo obligatorio; los créditos gastados más las reservas activas nunca pueden superarlo
input, parametersCampos compartidos opcionales de Studio, usando los mismos nombres que una única solicitud de Studio
itemsMatriz obligatoria de 1 a 300 objetos de producto
items[].skuReferencia de cliente opcional, de como máximo 200 caracteres
items[].product_idID opcional de la biblioteca Products perteneciente a esta cuenta
items[].product_urlPágina pública de producto opcional para importar; los parámetros de variante/consulta se conservan excepto el seguimiento de eBay, que se canoniza
items[].input, items[].parametersSobrescrituras por elemento; la precedencia es elemento → lote → valores predeterminados de Studio
test_countValor opcional 5; procesa solo los cinco primeros elementos y luego espera una reanudación explícita

Usa un ID de la biblioteca de productos, una URL de página de producto o detalles/imágenes del producto en input. Cuando se proporcionan tanto el ID del producto como la URL, se usa el producto de la biblioteca. Los campos de entrada proporcionados explícitamente por quien llama sobrescriben los valores importados. El contenido multimedia de referencia se copia al almacenamiento en propiedad mediante el mismo servicio que se usa para las generaciones individuales de API. Las importaciones de páginas de producto de API usan solicitudes HTTP públicas acotadas con redirecciones validadas. Los enlaces de anuncios de eBay también tienen una alternativa protegida mediante navegador. Aun así, una tienda puede rechazar una importación o requerir inicio de sesión; en ese caso, proporciona un ID de producto en propiedad o datos/imágenes de producto preparados. El límite del cuerpo de la solicitud es de 1 MiB. Envía listas de productos en JSON; la carga de archivos CSV no forma parte de esta versión de la API.

La respuesta incluye batch_id, status, total_items, max_credits, credits_used, credits_committed, recuentos y una primera página de elementos. La aceptación inicial no reserva créditos para todo el lote. Las tareas pueden aparecer en el siguiente tick del worker, por lo que un elemento aceptado puede tener inicialmente una matriz attempts vacía.

Progreso y resultados

  • GET /api/v1/studio/batches?offset=0&limit=50 lista los lotes de esta cuenta.
  • GET /api/v1/studio/batches/{batch_id}?offset=0&limit=50 devuelve el progreso de los elementos. La paginación se hace por índice de elemento basado en cero, con un tamaño máximo de página de 100.
  • Cada elemento incluye su index, sku opcional, estado y attempts. Un intento incluye un task_id, version, credits_used y estado normales; los intentos completados incluyen URL de resultados firmadas.
  • GET /api/v1/tasks/{task_id} recupera un único intento y actualiza sus enlaces de resultados firmados. Se aplican las reglas normales de propiedad de tareas entre claves pertenecientes a la misma cuenta.

Un elemento con IMPORT_FAILED falló antes de la admisión a la generación de pago. Su mensaje de error identifica una página bloqueada de eBay/seguridad cuando se conoce y sugiere un reintento o datos de producto preparados. PREPARATION_FAILED identifica un fallo inesperado de preparación de generación después de la importación; incluye task_id al contactar con soporte. Los errores de validación/contenido multimedia conservan sus códigos específicos. Los demás elementos continúan. Cada intento fallido es terminal: resume no lo reintenta. Después de corregir la entrada o desplegar una corrección, usa retry_failed o rework de abajo para crear un nuevo intento en el mismo lote. Reutilizar la clave de creación original devuelve el lote original; no lo vuelve a ejecutar.

DIRECTOR_REQUEST_FAILED means the AI Director's text-model request was rejected before it could produce a video brief. REFERENCE_MEDIA_UNAVAILABLE identifies an unreadable, unsupported or oversized Director reference image. Report the task_id to support; do not treat either error as a video-generation failure or automatically spend credits on another attempt. Saved account images are sent directly from storage to the Director as binary image inputs, so this stage does not need anonymous CDN access.

No consultes más de una vez cada cinco segundos. Un lote informa de completed cuando todos sus elementos han alcanzado un estado terminal; inspecciona los recuentos y los errores individuales porque la finalización puede incluir elementos fallidos. Un elemento retenido detrás de una muestra de cinco elementos informa de waiting_for_sample. La muestra se pausa con TEST_REVIEW_REQUIRED después de que sus intentos se estabilicen.

Pausar, reanudar, cancelar y aumentar el presupuesto

POST /api/v1/studio/batches/{batch_id}:

json
{
  "action": "pause"
}
json
{
  "action": "resume",
  "max_credits": 1000
}
json
{
  "action": "cancel"
}

Pausar y cancelar impiden futuros inicios. Los intentos ya admitidos para iniciarse conservan sus reservas y finalizan con normalidad. Reanudar continúa el resto tras una muestra, una recarga de saldo o un aumento del presupuesto. Los presupuestos solo pueden aumentar. La cancelación detiene los elementos restantes. Estos controles son idempotentes mientras el estado de lote solicitado no cambie; un lote cancelado no puede resume, pero sí puede restart o rework elementos terminales.

Reintentar fallos, rehacer elementos o reiniciar un lote

Usa el mismo endpoint POST /api/v1/studio/batches/{batch_id}. Estas acciones crean nuevos intentos, potencialmente de pago, y requieren una nueva cabecera Idempotency-Key (de 1 a 200 caracteres) para cada operación intencionada. Reutiliza esa clave y un JSON idéntico tras una interrupción de red. Un cuerpo modificado devuelve IDEMPOTENCY_CONFLICT. Las claves para estas operaciones se limitan al ámbito de la cuenta y del lote, por separado de la creación del lote. El cuerpo de la solicitud está limitado a 1 MiB.

AcciónQué se ejecuta
retry_failedSolo los elementos cuyo intento más reciente falló. El valor opcional item_indexes selecciona un subconjunto; omítelo para incluir todos los fallos.
reworkElementos terminales seleccionados, incluidos los correctos o cancelados. Las entradas obligatorias de items identifican exactamente un index de base cero o el task_id actual, además de product_id, product_url, input o parameters opcionales.
restartTodos los elementos, incluidos los correctos, con un nuevo intento. Espera primero a que termine el trabajo admitido. Se elimina la puerta de muestra.
bash
curl "$V4V_BASE_URL/api/v1/studio/batches/$BATCH_ID" \
  -H "Authorization: Bearer $V4V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: catalogue-retry-1" \
  -d '{"action":"retry_failed","max_credits":800}'

Para corregir solo un producto sin regenerar los elementos correctos:

json
{
  "action": "rework",
  "items": [
    {
      "index": 1,
      "product_url": "https://www.ebay.de/itm/227541601859",
      "input": {
        "prompt": "A slow close-up of the bag and its details."
      },
      "parameters": {
        "duration": 8
      }
    }
  ]
}

Para rehacer resultados que no te gusten, copia su items[].task_id actual de la respuesta del lote. Puedes mantener las mismas entradas o proporcionar un nuevo prompt:

json
{
  "action": "rework",
  "items": [
    {
      "task_id": "task_0123456789abcdef01234567"
    },
    {
      "task_id": "task_abcdef0123456789abcdef01",
      "input": {
        "prompt": "Slower close-up, softer lighting"
      }
    }
  ]
}

Usa la URL del lote existente y una nueva operación Idempotency-Key. El lote vuelve a running, los elementos seleccionados pasan a queued y sus task_id/results/error de nivel superior se vacían hasta que el nuevo intento se materializa/se completa. Los demás elementos completados permanecen sin cambios. La salida anterior solo se conserva en el historial de attempts; los consumidores deben mostrar items[].results para el resultado actual. Se permite exactamente uno de index o task_id por entrada. Una tarea ajena/no relacionada devuelve TASK_NOT_FOUND; una tarea de una versión ya reemplazada devuelve BATCH_ITEM_VERSION_CHANGED (409), para que las selecciones obsoletas no puedan volver a ejecutar en silencio un resultado más reciente. Volver a reproducir una clave aceptada sigue siendo seguro incluso después de que su tarea seleccionada pase a ser histórica.

Para una reejecución completa, envía {"action":"restart"} con una nueva clave. Las tres acciones aceptan cambios opcionales de input y parameters para toda la operación, además de un max_credits aumentado. Los cambios se combinan con la solicitud anterior de ese elemento; los cambios por elemento tienen prioridad. Cambiar product_id o product_url borra la alternativa anterior. Las instantáneas de solicitudes y resultados anteriores permanecen sin cambios. Los reintentos posteriores heredan las últimas correcciones aceptadas y preparan un flujo de trabajo nuevo.

Los intentos seleccionados deben ser terminales. BATCH_ITEMS_ACTIVE (409) significa que el trabajo sigue en cola/admitido/en procesamiento, que un elemento de reintento seleccionado no falló o que acaba de aceptarse otro reintento. Para un reinicio completo, cancela el trabajo pendiente y espera a que terminen los intentos admitidos. GENERATION_UNRESOLVED (409) bloquea los reintentos mientras una solicitud de generación anterior esté en cola, en ejecución, en despacho o en estado incierto; primero reconcilia su resultado. NO_FAILED_ITEMS (409) significa que no hay nada que reintentar. Reintentar y rehacer inicia el procesamiento de forma explícita, incluidos otros elementos pendientes de ese lote; una puerta de muestra existente de cinco elementos se mantiene a menos que resume o restart la eliminen.

max_credits sigue siendo un límite acumulativo: los cargos anteriores más las reservas actuales siguen contando. Un reintento no reembolsa los pasos anteriores correctos ni reinicia el presupuesto. No se toma ninguna reserva para el lote completo. Las nuevas versiones usan las mismas colas globales y por cuenta para operaciones en bloque. Los registros de créditos de API/MCP conservan la atribución de lote, elemento y versión.

Las respuestas conservan todos los intentos en items[].attempts, cada uno con su propia tarea/proyecto y un version creciente (los números pueden saltarse). items[].version, el estado del elemento y counts describen la versión prevista más reciente; una versión nueva informa inicialmente de que está en cola incluso antes de que su tarea se materialice. credits_used incluye todas las versiones. Un lote se completa solo cuando la versión más reciente de cada elemento es terminal. Las operaciones reproducidas nunca inician intentos adicionales. Se conservan hasta 100 operaciones que crean versiones y 8 MiB de cambios acumulados por lote; BATCH_HISTORY_LIMIT (409) solicita un lote nuevo cuando se alcanza el límite.

INSUFFICIENT_CREDITS o BUDGET_EXCEEDED detiene nuevas ejecuciones. Añadir créditos a la cuenta no reanuda un lote automáticamente: llama a resume de forma explícita. La admisión del presupuesto y la reserva de la cuenta son atómicas dentro de sus respectivos documentos de MongoDB, por lo que los workers concurrentes no pueden superar el presupuesto del lote ni cargar dos veces el mismo intento. No se requiere un conjunto de réplicas de MongoDB.

Un tiempo de espera agotado en la consulta de estado no demuestra que una generación haya fallado. Si se pierde una respuesta de envío de generación, su hueco permanece ocupado para su reconciliación; el sistema no envía automáticamente una solicitud de pago de reemplazo. Cuando la generación se realiza correctamente, los reintentos de almacenamiento de archivos reutilizan el resultado de generación existente. Los envíos limitados por tasa rechazados explícitamente pueden reintentarse con backoff acotado. La revisión de resultados completados, la aprobación de versiones, la exportación ZIP y una interfaz masiva en Estudio del plan #194 más amplio quedan fuera de esta versión de la API; las descargas firmadas individuales están disponibles a través de los resultados normales de las tareas.

Registros de créditos

Los administradores pueden filtrar los registros de créditos por API o MCP. Las entradas incluyen el nombre/ID de la clave API, los ID de tarea/proyecto/trabajo, la fuente de generación y los marcadores de lote/elemento/versión en bloque cuando corresponda. Los secretos de las claves nunca se registran.

Las reservas y la liquidación son eventos de auditoría con un delta de créditos cero; los metadatos registran el importe reservado. Los cargos y reembolsos llevan el delta real de créditos exactamente una vez. balanceAfter es el saldo disponible de la cuenta, que excluye las reservas pendientes. Los cargos históricos de la API se restauran a partir de los recibos de trabajos almacenados sin volver a cargar la cuenta; cuando no puede reconstruirse el saldo disponible histórico, la interfaz de administración lo indica.

Diagnósticos de generación fallida

Las tareas REST fallidas, los resultados de MCP get_task y los callbacks firmados task.failed comparten un objeto de error. message es el resumen de V4V; provider_error conserva el motivo del servicio del modelo con credenciales, routing privado y ubicaciones de red ocultos. provider usa el alias de routing público managed.

json
{
  "error": {
    "code": "GENERATION_FAILED",
    "message": "Generation failed. Unused credits and failed generation charges have been released.",
    "stage": "generation",
    "retryable": false,
    "provider": "managed",
    "provider_error": "The model is currently unable to process speech edits. If you think this was an error, send feedback.",
    "hint": "Remove speech from the reference video or use still images."
  }
}

Los rechazos de seguridad, las ediciones de voz y las duraciones/resoluciones no compatibles requieren cambiar la solicitud. Los límites de tasa y los tiempos de espera incluyen retryable: true, retry_after_seconds: 60 y una sugerencia de recuperación. Los motivos desconocidos siguen estando disponibles sin inventar un diagnóstico ni una recomendación de reintento. Estos campos se omiten cuando no existe un diagnóstico del servicio del modelo. Las tareas fallidas antiguas se enriquecen mientras su registro de fallo del flujo de trabajo sigue disponible. Estudio y Laboratorio muestran el mismo motivo saneado y lo envían como generation_failed.reason de GA4 (sujeto al límite analítico existente de 120 caracteres).

Una sugerencia de reintento nunca inicia otra generación. Un nuevo intento de pago requiere una solicitud explícita del usuario y una nueva clave de idempotencia. La liquidación de créditos existente, los reembolsos por pasos fallidos, los cargos por pasos completados y la firma del webhook siguen en vigor.