Vidu en RunAPI

¿Qué hace Vidu en RunAPI?

Elegir ruta

• Para un artefacto o resultado puntual, utiliza el servicio registrado vidu en la CLI de runapi. Si el catálogo de comandos instalados no lo lista, detente e informa la ausencia del servicio en lugar de inventar un comando.
• Para una aplicación, backend, worker, biblioteca, pipeline de webhook o base de código en producción, ve directamente a Integrar con SDK. Nunca invoques la CLI desde el runtime de producción.

Descubrir contrato

Autentícate, luego inspecciona el catálogo de comandos instalados y el contrato actual de la operación seleccionada:

runapi auth status > auth.json
jq -e '.authenticated == true' auth.json
runapi vidu --help
runapi vidu <operacion> --help
curl --fail --location https://runapi.ai/docs/api/vidu/<operacion>.md --output contrato.md

Si la autenticación es falsa, detente antes de enviar. Pide al usuario que proporcione una RUNAPI_API_KEY válida, o importa una clave proporcionada por el usuario desde stdin con runapi auth import-token --token -; usa el inicio de sesión interactivo en el navegador solo cuando el usuario lo solicite explícitamente. Elige <operacion> únicamente de la ayuda del servicio. Trata la ayuda del comando como autoridad para la operación instalada, el modelo y la lista de campos de primer nivel. Trata la Referencia de la API como autoridad para el esquema completo de la solicitud, campos anidados, reglas condicionales, comportamiento de tareas y variantes de respuesta. Si ambas superficies discrepan, detente e informa la discrepancia del contrato en lugar de adivinar.

Construir solicitud

Crea request.json como JSON válido utilizando solo los campos aceptados por el contrato de la operación descubierta. Para el modelo y los valores elegidos, evalúa cada regla condicional aplicable como un conjunto: satisface todos los campos obligatorios, omite todos los campos prohibidos y detente ante contradicciones no resueltas.

Recorre objetos y arreglos anidados antes de la ejecución. Cierra cada relación declarada por el contrato descubierto, incluyendo restricciones de unicidad y referencias cruzadas entre valores anidados.

Para una entrada de medios locales descubierta, incluyendo campos de tipo archivo y campos de URL de medios de primer nivel, coloca una ruta de archivo local legible por el agente directamente en request.json. La CLI consume los campos de archivo según lo declarado y sube rutas locales en campos de URL de medios de primer nivel. Usa runapi files create solo cuando el usuario necesite una URL reutilizable, proporcione Base64, o el contrato descubierto exija explícitamente una subida separada.

Invariantes semánticas:

• El formato, tamaño y duración del audio de los medios remotos se verifican de forma asíncrona por el proveedor de generación.

Valida el archivo antes de enviarlo:

jq empty request.json

Ejecutar

Envía exactamente una vez y persiste la respuesta de la tarea antes de esperar:

runapi vidu <operacion> --async --input-file request.json > tarea.json
id_tarea="$(jq -er '.id' tarea.json)"

Para un resultado puntual, espera inmediatamente esa misma tarea y guarda la respuesta JSON completa. Esta espera bloqueante es el comportamiento por defecto:

runapi wait "$id_tarea" --service vidu --action <operacion> > resultado.json

Solo cuando el usuario solicite explícitamente ejecución en segundo plano, sondeo o integración con webhook, puedes detenerte después de validar tarea.json. Informa el id de la tarea y no afirmes que el entregable está completo.

Verificar

Un estado de éxito no es el entregable. Lee y valida la respuesta completa según el contrato de resultado descubierto. Conserva el resultado no multimedia completo en el formato exacto solicitado, incluyendo JSON, texto, SRT o VTT.

Para cada entregable multimedia solicitado que aparezca en la respuesta, descarga todos ellos en lugar de devolver solo la primera URL. Antes de descargar, deriva su tipo MIME o familia esperada a partir de los metadatos de respuesta cuando estén presentes, luego del formato de salida seleccionado, luego de un campo de resultado inequívoco como videos, images o audios en la Referencia de la API. Las familias de fallback declaradas en el Catálogo para esta habilidad son video/*. Detente solo cuando no se pueda establecer un solo tipo o familia esperada a partir de esas fuentes.

Para cada archivo descargado, requiere tanto un archivo no vacío como el tipo MIME o familia esperados:

curl --fail --location <url-del-entregable> --output <archivo-descargado>
for archivo in <archivos-descargados>; do
  mime_esperado=<patrón-de-MIME-o-familia-esperado-para-este-archivo>
  test -s "$archivo"
  [[ "$(file --brief --mime-type "$archivo")" == $mime_esperado ]]
done

No informes completitud cuando falte algún entregable solicitado, esté vacío o tenga un tipo MIME inesperado. Registra Conformidad de la Habilidad por separado de Resultado de la Tarea para que un fallo del servicio no oculte si se siguió esta receta.

Recuperar o detener

• Corrige la forma de una solicitud como máximo una vez, y solo cuando el contrato descubierto o el error de validación devuelto identifique la corrección.
• Reintenta un fallo transitorio de transporte como máximo una vez, y solo cuando la evidencia confirme que no se creó ninguna tarea, no hubo facturación y reintentar es seguro.
• Si la espera agota el tiempo o pierde el transporte después de que exista tarea.json, conserva el error y vuelve a ejecutar runapi wait para esa misma tarea como máximo una vez. Nunca envíes una tarea de reemplazo.
• Ante un fallo terminal de RunAPI o del servicio, conserva la evidencia de la tarea/error y detente. Mantén el modelo y la capacidad seleccionados, y no envíes otra solicitud paga sin autorización del usuario.
• Si al contrato le falta un hecho necesario para construir o verificar la solicitud, detente e informa la brecha del contrato. No conviertas un defecto del producto en una solución permanente de la habilidad.

Integrar con SDK

Usa esta ruta solo para integración en aplicaciones o código de producción. Abre la referencia del SDK de RunAPI actual a continuación, selecciona el paquete para el lenguaje objetivo y Vidu, y confirma su comando de instalación, métodos de cliente, tipos de solicitud, tipos de respuesta y clases de error antes de codificar. Construye la solicitud a partir del mismo contrato de producto descubierto y aplica las mismas reglas de verificación y detención de entregables. No invoques runapi como subproceso desde código de producción.

Referencias

• Resumen del modelo, precios y límites de tasa: https://runapi.ai/models/vidu.md
• Resumen del proveedor: https://runapi.ai/providers/vidu.md
• Catálogo completo de modelos: https://runapi.ai/models.md
• Integración con SDK: https://github.com/runapi-ai/vidu-sdk

Variantes

• vidu-q4-image-to-video: https://runapi.ai/models/vidu/q4-image-to-video.md
• vidu-q4-reference-to-video: https://runapi.ai/models/vidu/q4-reference-to-video.md