Vidu no RunAPI

O que Vidu no RunAPI faz?

Escolha a rota

• Para um artefato ou resultado único, use o serviço vidu registrado na CLI do runapi. Se o catálogo de comandos instalados não listá-lo, pare e reporte a falta do serviço, em vez de inventar um comando.
• Para um aplicativo, backend, worker, biblioteca, pipeline de webhook ou base de código em produção, vá diretamente para Integrar com SDK. Nunca chame a CLI como parte do ambiente de produção.

Descobrir contrato

Autentique-se e inspecione o catálogo de comandos instalados e o contrato atual da operação selecionada:

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

Se a autenticação for falsa, pare antes de submeter. Peça ao usuário que forneça uma RUNAPI_API_KEY válida, ou importe uma chave fornecida pelo usuário via stdin com runapi auth import-token --token -; use o login interativo no navegador apenas quando o usuário solicitar explicitamente. Escolha <operation> apenas a partir da ajuda do serviço. Trate a ajuda do comando como autoritativa para a operação instalada, modelo e lista de campos de nível superior. Trate sua Referência da API como autoritativa para o esquema completo da requisição, campos aninhados, regras condicionais, comportamento da tarefa e variantes de resposta. Se as duas superfícies discordarem, pare e reporte a incompatibilidade de contrato, em vez de adivinhar.

Construir requisição

Crie request.json como JSON válido, usando apenas os campos aceitos pelo contrato da operação descoberta. Para o modelo e valores escolhidos, avalie cada regra condicional aplicável como um conjunto: satisfaça todo campo obrigatório, omita todo campo proibido e pare em contradições não resolvidas.

Percorra objetos e arrays aninhados antes da execução. Feche todos os relacionamentos declarados pelo contrato descoberto, incluindo restrições de unicidade e referências cruzadas entre valores aninhados.

Para uma entrada de mídia local descoberta, incluindo campos do tipo arquivo e campos de URL de mídia de nível superior, coloque um caminho de arquivo local legível pelo agente diretamente em request.json. A CLI consome campos de arquivo conforme declarados e faz upload de caminhos locais em campos de URL de mídia de nível superior. Use runapi files create apenas quando o usuário precisar de uma URL reutilizável, fornecer Base64, ou o contrato descoberto exigir explicitamente um upload separado.

Invariantes semânticos:

• Formato, tamanho e duração do áudio da mídia remota são verificados de forma assíncrona pelo provedor de geração.

Valide o arquivo antes de enviá-lo:

jq empty request.json

Executar

Submeta exatamente uma vez e persista a resposta da tarefa antes de aguardar:

runapi vidu <operation> --async --input-file request.json > task.json
task_id="$(jq -er '.id' task.json)"

Para um resultado único, aguarde imediatamente essa mesma tarefa e salve a resposta JSON completa. Essa espera bloqueante é o padrão:

runapi wait "$task_id" --service vidu --action <operation> > result.json

Apenas quando o usuário solicitar explicitamente execução em segundo plano, polling ou integração com webhook, você pode parar após validar task.json. Reporte o id da tarefa e não afirme que a entrega está completa.

Verificar

Um status de sucesso não é a entrega final. Leia e valide a resposta completa conforme o contrato de resultado descoberto. Preserve o resultado completo que não seja de mídia no formato exato solicitado, incluindo JSON, texto, SRT ou VTT.

Para cada entrega de mídia solicitada listada em qualquer lugar da resposta, baixe todas elas em vez de retornar apenas a primeira URL. Antes de baixar, derive seu tipo MIME esperado ou família a partir dos metadados da resposta, quando presente; depois, a partir do formato de saída selecionado; e, em seguida, a partir de um campo de resultado inequívoco como videos, images ou audios na Referência da API. As famílias de fallback declaradas no Catálogo para esta skill são video/*. Pare apenas quando nenhum tipo ou família esperado único puder ser estabelecido a partir dessas fontes.

Para cada arquivo baixado, exija tanto um arquivo não vazio quanto o tipo MIME ou família esperado:

curl --fail --location <deliverable-url> --output <downloaded-file>
for file in <downloaded-files>; do
  expected_mime=<expected-MIME-or-family-pattern-for-this-file>
  test -s "$file"
  [[ "$(file --brief --mime-type "$file")" == $expected_mime ]]
done

Não reporte conclusão quando qualquer entrega solicitada estiver faltando, vazia ou tiver um tipo MIME inesperado. Registre Skill Conformance separadamente de Task Outcome para que uma falha de serviço não esconda se esta receita foi seguida.

Recuperar ou parar

• Corrija a forma da requisição no máximo uma vez, e apenas quando o contrato descoberto ou o erro de validação retornado identificar a correção.
• Repita uma falha de transporte transitória no máximo uma vez, e apenas quando evidências confirmarem que nenhuma tarefa foi criada, nenhuma cobrança ocorreu e que repetir é seguro.
• Se a espera exceder o tempo limite ou perder o transporte após task.json existir, preserve o erro e execute runapi wait novamente para essa mesma tarefa no máximo uma vez. Nunca submeta uma tarefa substituta.
• Em uma falha terminal do RunAPI ou do serviço, preserve a evidência da tarefa ou erro e pare. Mantenha o modelo e a capacidade selecionados, e não submeta outra requisição paga sem autorização do usuário.
• Se o contrato estiver faltando um fato necessário para construir ou verificar a requisição, pare e reporte a lacuna do contrato. Não transforme um defeito do produto em uma solução permanente da skill.

Integrar com SDK

Use esta rota apenas para integração em aplicações ou código de produção. Abra a referência atual do SDK do RunAPI abaixo, selecione o pacote para a linguagem alvo e Vidu, e confirme seu comando de instalação, métodos do cliente, tipos de requisição, tipos de resposta e classes de erro antes de codificar. Construa a requisição a partir do mesmo contrato de produto descoberto e aplique as mesmas regras de verificação de entrega e parada. Não invoque runapi como um subprocesso a partir do código de produção.

Referências

• Visão geral do modelo, preços e limites de taxa: https://runapi.ai/models/vidu.md
• Visão geral do provedor: https://runapi.ai/providers/vidu.md
• Catálogo completo de modelos: https://runapi.ai/models.md
• Integração 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